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
You may need certain IAM permissions to carry out some actions described on this page. This means:
- you are the Owner of the Scaleway Organization in which the actions will be carried out, or
- you are an IAM user of the Organization, with a policy granting you the necessary permission sets
- You have an account and are logged into the Scaleway console
- You have
mosquitto-clients
(mqtt client), andjq
(json parsing tool) installed on your computer
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.
- Follow the CLI installation steps.
- Configure your CLI by running the following command and answering the questions:
scw init
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"
.
-
Save the output to a
hub.json
file to make it easier later, so we need to tell the CLI to output asjson
:scw iot hub create -o json > hub.jsonjq < hub.jsonThe 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} -
Poll the hub status until it is ready:
scw iot hub get $(jq -r '.id' hub.json) | grep StatusAt 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.
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
.
-
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.jsonjq < dev1.jsonThe 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>"}} -
Now create a second device:
scw iot device create \hub-id=$(jq -r '.id' hub.json) \allow-insecure=true \-o json > dev2.jsonjq < dev2.json
Subscribe and Publish
Now that everything is set up, let’s simulate 2 devices and send data.
-
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.
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.
It is possible to connect to the Hub using TLS but without Mutual 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.
-
Start by downloading the IoT Hub 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 -
Then extract the certificates from the device JSON files, so that the mosquitto clients may use them:
jq -r '.certificate.crt' dev1.json > dev1.crtjq -r '.certificate.key' dev1.json > dev1.keyjq -r '.certificate.crt' dev2.json > dev2.crtjq -r '.certificate.key' dev2.json > dev2.key -
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!'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.