API Reference

Require the TTN Client module:

import org.thethingsnetwork.data.mqtt.Client;

Class: Client #

Creates an instance of the client:

Client client = new Client(region, appId, accessKey [, connOpts]);

• region [String]: The region (e.g. eu) or full hostname (e.g. eu.thethings.network) of the handler to connect to.
• appId [String]: The ID of the application to connect to (e.g. hello-world).
• appAccessKey [String]: An access key for the application, formatted as base64 (e.g. '2Z+MU0T5xZCaqsD0bPqOhzA6iygGFoi4FAgMFgBfXSo=').
• connOpts [MqttConnectOptions]: Some custom configuration of the MQTT connection. This parameter is optional. For example to use TLS download mqtt-ca.pem and trust it following this guide: Trust self-signed certificates:

Event: connect #

Emitted on successful connection.

client.onConnected((Connection _client) -> System.out.println("connected !"));

• cb.client [Connection]: MQTT connection wrapper. See MQTT.

Event: error #

Emitted when the client cannot connect or when a parsing error occurs.

client.onError((Throwable _error) -> System.err.println("error: " + _error.getMessage()));

• cb.error [Throwable]: Error object. See MQTT.

Event: message #

Emitted when TTN forwards a message addressed to your application.

client.onMessage((String devId, Object data) -> System.out.println("Message: " + devId + " " + data));

• cb.devId [String]: Device ID, e.g.: my-uno.

• cb.data [Object]: Message data, e.g.:

  {
    "port": 1,
    "counter": 10,
    "payload_raw": "MQ==",
    "payload_fields": {
      "led": true
    },
    "metadata": {
      "time": "2016-09-07T12:50:07.068771281Z",
      "frequency": 868.1,
      "modulation": "LORA",
      "data_rate": "SF7BW125",
      "coding_rate": "4/5",
      "gateways": [{
        "gtw_id": "0000024B08060112",
        "timestamp": 3955426155,
        "time": "2016-09-07T12:50:07.053048Z",
        "channel": 4,
        "rssi": -109,
        "snr": 5.8,
        "rf_chain": 1
      }]
    }
  }
  

When no field is specified, cb.data holds a Message. It’s a JsonObject with an additional method: getBinary(String key), base64-decoding the requested field:

client.onMessage((String devId, Object data) -> {
    byte[] payload = ((Message) data).getBinary("payload_raw");
    System.out.println("Message: " + devId + " " + payload[0]);
});

Should give you:

Message: my-uno 0

Listen for a specific device #

client.onMessage("my-uno", (String devId, Object data) -> System.out.println("Message: " + devId + " " + data));

Listen for a specific field (and device) #

client.onMessage("my-uno", "led", (String devId, Object data) -> System.out.println("Message: " + devId + " " + data));

When a field is specified, cb.data holds the String representation of the field value.

Event: activation #

Emitted when a device registered to the application activates.

client.onActivation((String _devId, JSONObject _data) -> System.out.println("Activation: " + _devId + ", data: " + _data));

• cb.devId [String]: Device ID, e.g.: my-uno.

• cb.data [Object]: Activation data, e.g.:

  {
    "app_eui": "70B3D57ED0000AFB",
    "dev_eui": "0004A30B001B7AD2",
    "dev_addr": "260023BB",
    "metadata": {
      "time": "2016-09-07T12:43:17.97454032Z",
      "frequency": 867.1,
      "modulation": "LORA",
      "data_rate": "SF7BW125",
      "coding_rate": "4/5",
      "gateways": [{
        "gtw_id": "0000024B08060112",
        "timestamp": 3546311603,
        "time": "2016-09-07T12:43:17.938537Z",
        "channel": 2,
        "rssi": -107,
        "snr": 1.2
      }]
    }
  }
  

Event: device #

Emitted when a device event is published.

client.onDevice(null, "down/scheduled", (String devId, String event, JSONObject data) -> System.out.println("Received event " + event + "for device " + devId));

• cb.devId [String]: Device ID, e.g.: my-uno.

• cb.event [String]: Event name, e.g.: down/scheduled.

• cb.data [Object]: Event data, e.g. for down/scheduled:

  {
    "port": 1,
    "payload_raw": "MQ==",
  }
  

Method: send #

Send a message to a specific device.

client.send(devId, payload, port);

• deviceId [String]: The ID of the device to address, e.g. my-uno

• payload [mixed]: Message to send, either:

  • Byte array, e.g. [1]

  • ByteBuffer, e.g. ByteBuffer.allocate(2).put(0x00)

  • JsonObject, e.g. { led: true }

    This requires your application to be configured with an encoder payload function to encode the object in bytes.

• port [Integer]: Optional port to address. Default: 1.

See the Java ByteBuffer reference for different ways to create a buffer. The client will rewind the buffer before publishing the message to The Things Network’s MQTT broker.

Method: end #

Close the client via client.close().

client.end([timeout]);

• timeout [Integer]: The time you give to the client to close the connection. This parameter is optional. Default is 5000 ms.