Implement your first device

The simplest way to kick-off IoT development is to implement a device that sends sensor data to the cloud. This article explains basic AllThingsTalk APIs that you should use to develop a software that runs on an IoT device.

Apple counter example

The experienced apple farmer knows that an apple is perfectly ripe only when it falls to ground on it’s own weight. That’s why he doesn’t pick them directly from tree, but waits for apples to fall. It’s proven that apples won’t get spoiled during 24h being on the ground, so it’s perfectly fine to collect them at the very end of a day.
The businessman inside him would like to know how many apples hit the ground during the day, so he can keep financial records and further grow his business.

The farmer wants you to implement an IoT solution for his problem.
He’ll pay you in apples. 😃

Hardware
The first step for you is to build a smart device that is able to sense when apples hit the ground.

Software sketch
The software on the device will need to increment the counter every time an apple hits the ground, and transfer that data to AllThingsTalk. It will also need to reset the counter for maintenance, and be able to run for a long time.

Maker platform
You can use Maker platform to remotely track the counter as it increases and reset it when needed.

Prep yourself

To follow this article you’ll need:

AllThingsTalk account
Create one at https://maker.allthingstalk.com

cURL
cURL is a computer software project providing a library and command-line tool to transfer data using HTTP and other protocols.

Mosquitto
Mosquitto is a handy command-line tool that allows you to publish and subscribe for MQTT messages. You will use two commands — mosquitto_pub and mosquitto_sub.

Creating a device in Maker

Before being able to send data to the cloud, the device should be authorized to do so. You authorize the device to talk with the cloud by creating it’s digital representation in Maker.
To create a device in Maker do the following:

• Sign in
• Choose a ground
• Choose Devices
• Choose Connect a device
• Under WAN / LAN choose Your own device
• Enter the Device Name

Device ID
For each device that you create, Maker will generate a Device ID that the client needs to use to identify the device resource on the cloud.

Example:

• Device ID: lYDeviceIDfQ

Device Token
Besides the Device ID, Maker will generate a Device Token that the client needs to use to authenticate with the cloud. The token will also allow client to:

• add, update and delete assets
• publish asset state
• read asset feed
• read asset commands

Example:

• Device Token: maker:4SDeviceTokenXNcYNuLzTHg1

Getting device

The simplest API call is to get the device you’ve just created:

curl -X GET "https://api.allthingstalk.io/device/lYDeviceIDfQ" \
  -H "Authorization: Bearer maker:4SDeviceTokenXNcYNuLzTHg1"

Adding assets

A device uses assets to explain what kind of data it can measure and present it to the cloud. Our device has two assets — count sensor and reset actuator.
For the two assets that we want to add, run these two commands:

cURL

// Create 'count' sensor
curl -X POST "https://api.allthingstalk.io/device/lYDeviceIDfQ/assets" \
  -H "Authorization: Bearer maker:4SDeviceTokenXNcYNuLzTHg1" \
  -H "Content-Type: application/json" \
  -d '{
    "is": "sensor",
    "name": "count",
    "profile": {
      "type": "integer"
    }
  }'
// Create 'reset' actuator
curl -X POST "https://api.allthingstalk.io/device/lYDeviceIDfQ/assets" \
  -H "Authorization: Bearer maker:4SDeviceTokenXNcYNuLzTHg1" \
  -H "Content-Type: application/json" \
  -d '{
      "is": "actuator",
      "name": "reset",
      "profile": {
          "type": "booolean"
    }
  }'

After the device ran the two requests, you’ll be able to see the counter and reset assets under your device in Maker.
For detailed API usage, read Assets API Reference

Publishing state

When the apple counter device detects a first fallen apple, it needs to publish the new counter increment to the cloud.

cURL

curl -X PUT "https://api.allthingstalk.io/device/lYDeviceIDfQ/asset/count/state" \
  -H "Authorization: Bearer maker:4SDeviceTokenXNcYNuLzTHg1" \
  -H "Content-Type: application/json" \
  -d '{"value": 1}'

Mosquitto

mosquitto_pub -h 'api.allthingstalk.io' -t 'device/lYDeviceIDfQ/asset/count/state' \
  -u 'maker:4SDeviceTokenXNcYNuLzTHg1' -P '' \
  -m '{"value": 2}'

Now that the counter says that enough apples have fallen to the ground, the fruit farmer can take a hike and collect them.

Listening for commands

At the end of the day when the fruit farmer has collected all the apples, he would like to reset the counter so the ground gets clean for other apples to fall. As your device doesn’t have a physical button, you would need to actuate it from the Maker.

Subscribing to an MQTT topic will deliver the command to your device in real-time and allow it to actuate upon:

Mosquitto

mosquitto_sub -h 'api.allthingstalk.io' -t 'device/lYDeviceIDfQ/asset/reset/command' \
  -u 'maker:4SDeviceTokenXNcYNuLzTHg1' -P ''

Response would be:

{"at":"2017-12-20T13:12:32.219892Z","value":true}

We don’t support listening for commands over HTTP yet.

Confirming actuation

When you send a command to your device, it will not provide any feedback to the cloud confirming the device has acted on that command. To confirm the command has been executed, the device should report the changed state of the asset back to the cloud.
So when the farmer clicks the reset button, device should send back the state of the reset count:

Mosquitto

mosquitto_pub -h 'api.allthingstalk.io' -t 'device/lYDeviceIDfQ/asset/count/state' \
  -u 'maker:4SDeviceTokenXNcYNuLzTHg1' -P '' \
  -m '{"value": 0}'

State vs Feed

To receive the device data in real time you can subscribe to both — State and Feed topic. Subscribing to the Feed topic will ensure that messages are formatted in a valid way by the cloud. If you subscribe to the State topic, the messages you’ll get will be exactly the same as those that the device publishes to the cloud.

Mosquitto

mosquitto_sub -h 'api.allthingstalk.io' -t 'device/lYDeviceIDfQ/asset/count/feed' \
  -u 'maker:4SDeviceTokenXNcYNuLzTHg1' -P ''

Where to go next?

In this article you have learned which API calls you can use to implement a basic device program.
Go on and read about Messaging to fine-tune communication between your device and the cloud by using additional MQTT topics.