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.