Scaleway DocumentationIoTIoT HubAPI/CLI
Getting started with the IoT Hub API

Jump toUpdate content

Getting started with the IoT Hub API

In this tutorial we will use the API through the well known utility curl. This will show you how to create Hubs and Devices, as well as more advanced features of the Scaleway Elements IoT Hub: Hub Events and Routes.

The API reference is here: IoT API

Requirements:

Setting up the IoT Hub

The Hub creation is done through a REST endpoint. To call it, you’ll need to provide:

  • Your Organization ID.
  • A name. The name is not important for this tutorial.
  • A product plan. The product plan is not important for this tutorial.

We will save the output to hub.json file to make it easier later:

curl -sS -H "X-Auth-Token: $SCW_SECRET_KEY" -d '{    "organization_id": "'$SCW_ORG'",    "name": "my_first_hub",    "product_plan": "plan_dedicated"  }' $IOT_API/hubs > hub.json
jq < hub.json

hub.json will contain something like:

{  "id": "a15ddd5b-ff73-4fb3-b043-1c9176dae295",  "name": "my_first_hub",  "organization_id": "<your organization ID>",  "status": "creating",  "product_plan": "plan_dedicated",  "endpoint": "iot.fr-par.scw.cloud",  "created_at": "2018-12-13T15:15:27.057005Z",  "enabled": true,  "device_count": 0,  "connected_device_count": 0,  "events_enabled": true,  "events_topic_prefix": "$SCW/events"}

We can poll the hub status until it is ready:

curl -sS -H "X-Auth-Token: $SCW_SECRET_KEY" $IOT_API/hubs/$(jq -r '.id' hub.json) | jq -r '.status'

At some point, the status will switch to ready.

Setting up the devices

Now we need to create 2 devices. You need to provide:

  • Your Organization ID.
  • The Hub ID. This is the "id" field from the JSON response received while creating a hub.
  • A name. Again, the name is not important for this tutorial.
Note:

As this tutorial aims to be simple and straightforward, the following commands are allowing the device to connect using insecure protocols, such as plain text MQTT or MQTTs without mutual authentication. In production, you should Deny Insecure connections to have the highest level of security. This is done by setting the field allow_insecure to false.

We will save the response to a file so we can use the fields later.

curl -sS -H "X-Auth-Token: $SCW_SECRET_KEY" -d '{    "hub_id": "'$(jq -r '.id' hub.json)'",    "name": "my_first_device",    "allow_insecure": true  }' $IOT_API/devices > dev1.json
jq < dev1.json

dev1.json should contain something like:

{  "device": {    "id": "ca973002-b87d-457e-8b9b-f5e19796e2b9",    "organization_id": "<your organization ID>",    "name": "my_first_device",    "status": "enabled",    "hub_id": "a15ddd5b-ff73-4fb3-b043-1c9176dae295",    "created_at": "2018-12-14T13:59:43.277945Z",    "allow_insecure": true,    "last_activity_at": "1970-01-01T00:00:00Z",    "is_connected": false,    "message_filters": {      "publish": {        "policy": "reject",        "topics": []      },      "subscribe": {        "policy": "reject",        "topics": []      }    }  },  "crt": "<certificate here>",  "key": "<certificate key here>"}

Let’s now create a second device:

curl -sS -H "X-Auth-Token: $SCW_SECRET_KEY" -d '{    "hub_id": "'$(jq -r '.id' hub.json)'",    "name": "my_second_device",    "allow_insecure": true  }' $IOT_API/devices > dev2.json
jq < dev2.json

How to subscribe and publish

Now that everything is set up, let’s simulate 2 devices and send data now.

Setup the subscriber:

# In one terminalmosquitto_sub \  -h $(jq -r '.endpoint' hub.json) \  -i $(jq -r '.device.id' dev1.json) \  -t mytopic/mysubtopic

Run the publisher:

# In another terminalmosquitto_pub \  -h $(jq -r '.endpoint' hub.json) \  -i $(jq -r '.device.id' dev2.json) \  -t mytopic/mysubtopic \  -m 'Hello, world!'

You should see the subscriber receive the Hello, world! message.

How to configure secure connections

If you require security, you can also connect your device to the Hub using TLS mutual authentication. With this method, the Hub can check the device’s identity, and the device can check the Hub’s identity.

Note:

It is possible to connect to the Hub using TLS but without Mututal authentication. In this case the device certificates are not needed as the Hub does not need to check the device identity. But the Hub certificate will still be needed as your client must check the hub’s identity.

First, download the IoT Hub’s server CA:

curl -sS -O https://iot.s3.nl-ams.scw.cloud/certificates/fr-par/iot-hub-ca.pemsha1sum iot-hub-ca.pem# 13cf3e59ed52d4c4b6bc249e85539d5fd5d572fb  iot-hub-ca.pem

Now, extract the certificates from the device JSON files, so that the mosquitto clients may use them:

jq -r '.crt' dev1.json > dev1.crtjq -r '.key' dev1.json > dev1.keyjq -r '.crt' dev2.json > dev2.crtjq -r '.key' dev2.json > dev2.key

Finally, run the same test as before, but with the added security:

# In one terminalmosquitto_sub \  -h $(jq -r '.endpoint' hub.json) -p 8883 \  --cert dev1.crt --key dev1.key --cafile iot-hub-ca.pem \  -i $(jq -r '.device.id' dev1.json) \  -t mytopic/mysubtopic
# In another terminalmosquitto_pub \  -h $(jq -r '.endpoint' hub.json) -p 8883 \  --cert dev2.crt --key dev2.key --cafile iot-hub-ca.pem \  -i $(jq -r '.device.id' dev2.json) \  -t mytopic/mysubtopic \  -m 'Hello, SECURE world!'
Tip:

You can mix MQTT and MQTTs clients on the same hub.

Further reading

You can harness the real power of MQTT Pub/Sub with a few more lines of reading.