Java SDK


The Thingstream Java Client SDK provides the API and classes required to interact with the Thingstream service and can be downloaded from the Thingstream download centre.

This SDK project can be imported into Eclipse using the option Import > Existing Projects into Workspace.

For an overview of the SDK and details about the API see the doc directory: docs/index.html


The project contains a set of examples:

  1. MessageClientExample - Example of using a message client to connect, subscribe to a topic, publish to that topic and receive an incoming message for that topic.

  2. LocationClientExample - Example of using a location client to poll for GSP locations, retrieve a set of GMS locations from local cell towers and a temperature reading.

  3. MessageLocationClientExample - Example of using a MessageLocationClient which contains a message client and location client and how they can be used concurrently on the same modem device.

  4. ClientServiceExample - Example of using the client service to manage a message client and location client.

To run the examples, the project should be exported and installed onto the device on which it should run, for example a Raspberry Pi with an attached modem.

For simplicity, a set of shell scripts is included. The shell scripts must be made executable before they are run as root on the device:

chmod +x ./*.sh


Each example uses a common configuration file situated in the config dir to define specific installation parameters.

The key parameters:

  1. EXAMPLE_MESSAGE_CLIENT_PROTOCOL - this defines the protocol used by the clients examples:

    • mqttsn: MQTTSN over an attached device

    • mqtt: MQTT over http

  2. TEST_CLIENT_TYPE - this defines the type of client to use for the test example:

    • mqttsn_client: message client (MQTTSN utilising an attached device)

    • mqtt_client: message client (MQTT over http)

    • location_client: location client (utilising an attached device modem)

    • mqttsn_loc_client: MessageLocationClient consisting of a MQTTSN message client and a location client.

    • mqtt_loc_client: MessageLocationClient consisting of a MQTT message client and a location client.

  3. MODEM_PORT - this defines the port on which a device is attached. Typical values:

    • /dev/ttyS0 - Pi serial port

    • /dev/ttyUSB0 - Pi USB port

  4. MQTT_CLIENT_ID, MQTT_USERNAME & MQTT_PASSWORD - if using an MQTT message client these must be set your own credentials.

  5. MQTT_TOPIC - If using an MQTT message client this must be set to a pre-defined topic.

The remaining parameters should not need changing.


  1. The thingstream, client-thingstream & client-ref-thingstream jars are mandatory.

  2. The org.eclipse.paho.client jar is required to run an MQTT message client.

  3. The jSerialComm jar is required to run an MQTTSN message client with a modem.

  4. The client-service-thingstream jar is required to use the ClientServiceWrapper and run ClientServiceExample.

  5. The client-test-thingstream & junit jars are required to run the included junit tests and TestRunnExample.

Still need help?

If you need more help or have any questions, please send an email to