Getting started with the Scaleway IoT Hub CLI

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

You can find the API reference documentation at the following link: IoT API

CLI setup and configuration

If you already have configured the Scaleway command-line interface, you can skip this section. However, we recommend checking it for updates.

1. Follow the CLI installation steps.
2. Configure your CLI by running the following command and answering the questions:

   scw init
   Copy code

Setting up the hub

The Hub creation is done through the scw iot hub create command, your CLI configuration already includes the project ID, you can optionally set:

• A name, with name="my_first_hub". For this tutorial purposes, the name is not important.
• A product plan, with product-plan="plan_dedicated".

1. Save the output to a hub.json file to make it easier later, so we need to tell the CLI to output as json:

   scw iot hub create -o json > hub.json
   
   jq < hub.json
   Copy code

   The file hub.json will contain come content as like the following example:

   {
   "id": "b20c3639-9030-496c-a1b2-6feb15846726",
   "name": "cli-hub-cocky-hugle",
   "status": "enabling",
   "product_plan": "plan_shared",
   "enabled": true,
   "device_count": 0,
   "connected_device_count": 0,
   "endpoint": "iot.fr-par.scw.cloud",
   "disable_events": false,
   "events_topic_prefix": "$SCW/events",
   "region": "fr-par",
   "created_at": "2021-04-26T08:46:33.436Z",
   "updated_at": "2021-04-26T08:46:33.436Z",
   "project_id": "<your project ID>",
   "organization_id": "<your organization ID>",
   "enable_device_auto_provisioning": false,
   "has_custom_ca": false
   }
   
   Copy code

2. Poll the hub status until it is ready:

   scw iot hub get $(jq -r '.id' hub.json) | grep Status
   Copy code

   At some point, the status will switch to ready.

Set up the devices

Now create 2 devices. You just need to provide:

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

1. Save the response to a file so we can use the fields later.

   scw iot device create \
   hub-id=$(jq -r '.id' hub.json) \
   allow-insecure=true \
   -o json > dev1.json
   
   jq < dev1.json
   Copy code

   The file dev1.json should contain something similar to:

   {
   "device": {
       "id": "0a184d04-aa69-43e5-8fbf-0ee0793aea43",
       "name": "cli-device-pensive-bassi",
       "description": "",
       "status": "enabled",
       "hub_id": "b20c3639-9030-496c-a1b2-6feb15846726",
       "last_activity_at": "1970-01-01T00:00:00Z",
       "is_connected": false,
       "allow_insecure": true,
       "allow_multiple_connections": false,
       "message_filters": {
       "publish": {
           "policy": "reject",
           "topics": []
       },
       "subscribe": {
           "policy": "reject",
           "topics": []
       }
       },
       "created_at": "2021-04-26T09:36:10.708Z",
       "updated_at": "2021-04-26T09:36:10.708Z"
   },
   "certificate": {
       "crt": "<certificate here>",
       "key": "<certificate key here>"
   }
   }
   Copy code

2. Now create a second device:

   scw iot device create \
   hub-id=$(jq -r '.id' hub.json) \
   allow-insecure=true \
   -o json > dev2.json
   
   jq < dev2.json
   Copy code

Subscribe and Publish

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

1. Setup the subscriber:

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

2. Run the publisher:

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

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

Setting up TLS mutual authentication

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.

1. Start by downloading the IoT Hub CA:

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

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

   jq -r '.certificate.crt' dev1.json > dev1.crt
   jq -r '.certificate.key' dev1.json > dev1.key
   jq -r '.certificate.crt' dev2.json > dev2.crt
   jq -r '.certificate.key' dev2.json > dev2.key
   Copy code

3. Run the same test as before, but with the added security:

   # In one terminal
   mosquitto_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
   Copy code

   # In another terminal
   mosquitto_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!'
   Copy code

   Note:

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

You can harness the real power of MQTT Pub/Sub with this blog post: An Introduction to the MQTT protocol.