Get started with Device API

The AllThingsTalk API is everything you need to develop IoT device and application clients to use our cloud services. We use the same API in our official web, mobile and device client libraries.

This article explains how to start developing with our APIs and use Maker to manage and test your device clients development.

Devices

Devices are special type of client applications with main purpose to measure and feed cloud with real-time sensory data.

View Devices API Reference →

Authenticating devices

After creating a device in Maker, you will get a DEVICE_ID and TOKEN that allows the device client application to feed measured data on it’s behalf into the cloud.

Every time your device client uses this token, the request will be made on behalf of device itself and within it’s authorized scope, so it doesn’t interfere with the rest of your resources. If you try to access user or ground resources using a device token, your request will be blocked.

Add the token to a request authorization header in this form: Authorization: Bearer <TOKEN>

Assets

An asset is a generic term that designates a capability of a device or an object observed by devices, e.g. measure temperature, or turn on/off a switch.

A device can have one or more assets.

• A sensor asset describes and carries state measurements, such as temperature and location. It holds the current state of a measured thing as well as historical states measured in the past.
• An actuator asset allows user or automation system to send commands to change it’s state, for example turn on the led light. After receiving a command and actuating it successfully, device client should send the new state back to the cloud in order to confirm the actuation.

Asset holds the profile object that describes the state data. It’s purpose is to validate state data incoming from device client and send valid actuation commands as downlink messages.

View Assets API Reference →

List device assets

1
2

curl -X GET "https://api.allthingstalk.io/device/<DEVICE_ID>/assets" \
  -H "Authorization: Bearer <TOKEN>"

For the newly created device, response will be empty collection of assets.

Add a sensor

For the same device, you can add a temperature sensor asset that feeds "type": "number" values:

1
2
3
4
5
6
7
8
9
10
11

curl -X POST "https://api.allthingstalk.io/device/<DEVICE_ID>/assets" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "is": "sensor",
    "name": "temperature",
    "profile": {
      "type": "number",
      "unit": "°C"
    }
  }'

After doing this, try listing device assets again and you will get a one item collection of the asset that you have just added.

Delete a sensor

To delete the temperature sensor:

1
2

curl -X DELETE "https://api.allthingstalk.io/device/<DEVICE_ID>/asset/temperature" \
  -H "Authorization: Bearer <TOKEN>"

State and Command streams

Publish a sensor state

State is the particular condition that an asset is in at a specific time. Device clients should publish new temperature/state whenever the condition changes. The value should be of the same type that is defined in asset’s profile:

1
2
3
4

curl -X PUT "https://api.allthingstalk.io/device/<DEVICE_ID>/asset/temperature/state" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "value": 20.1 }'

Use MQTT to publish sensor state

You can also use MQTT protocol to publish sensor (or actuator) state:

1
2
3

mosquitto_pub -h 'api.allthingstalk.io' -t 'device/<DEVICE_ID>/asset/temperature/state' \
  -u '<TOKEN>' -P '' \
  -m '0|20.1'

Mosquitto is a handy command-line tool to test MQTT. Pick a suitable Binary Installation at Mosquitto download page

Listen for actuator commands

You can program your devices to listen for actuator commands by using Messaging Command topics.

API Reference

Full API Reference is available here