IoT Hub API

Introduction

Scaleway IoT Hub is a resilient message broker which supports multiple communication protocols and displays export capabilities. It is a PaaS (Platform-as-a-Service) enabling device-to-device and device-to-Scaleway communication.

When connecting to a Hub, devices can exchange messages, granting them access to various cloud services. Hub routes also allow devices to send messages to other services that do not use MQTT (Message Queuing Telemetry Transport). MQTT is the most commonly used messaging protocol in IoT applications for its lightweight property and Publish/Subscribe model. Allowing interaction with services that do not use MQTT is an essential feature that increases flexibility and interoperability of the system.

Scaleway IoT Hub is thus versatile and can easily adapt to the various use cases, requirements, and constraints of a given IoT project. IoT Hub features include :

• Pub/Sub architecture
• MQTT protocol, with or without TLS, with or without WebSockets
• Mutual authentication available on TLS connections
• High Availability and Scalability
• Routes to Scaleway's ecosystem for data ingestion
• Multiple other IoT Networks such as SigFox or LoRa
• Usage metrics

Concepts

Refer to our dedicated concepts page to find definitions of the different terms referring to IoT Hub.

Quickstart

Set up your IoT Hub

1. Configure your environment variables.

   Note

   This is an optional step that seeks to simplify your usage of the APIs. Since there is only one Availability Zone for IoT Hub, we have already set the value to the fr-par region for you.

   export IOT_API="https://api.scaleway.com/iot/v1/regions/fr-par"
   export SCW_ACCESS_KEY="<API access key>"
   export SCW_SECRET_KEY="<API secret key>"
   

2. Edit the POST request payload that we will use in the next step to create an IoT Hub.

   {
     "name": "my_first_hub",
     "product_plan": "plan_dedicated",
   }
   

   Parameter	Description
   project_id	ID of the Project to create your flexible IP in.
   name	Name of the Hub.
   product_plan	Product plan for your IoT Hub. Three product plans are currently available for Hubs: plan_shared, plan_dedicated and plan_ha. To find which plan is better suited to your needs, you can consult the IoT Hub Quickstart page.

3. Create a Hub. Run the following command to create the Hub. Make sure you include the payload you edited in the previous step.

   Note

   We will save the output in a file called myhub.json.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "project_id": "7281793f-8474-727d-7688-72893f747g7e",
       "name": "my_first_hub",
       "product_plan": "plan_dedicated"}' \
   "$IOT_API/hubs" > myhub.json
   

4. Get your Hub's information. Run the following command to pull your Hub's information from the myhub.json file.

   curl -X GET \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     "$IOT_API/hubs/$(jq -r '.id' myhub.json)"
   

   You should get an output similar to the following. The status should be indicated as ready.

   Note

   This is a response example, the UUIDs displayed are not real.

   {
     "region":"fr-par", 
     "id":"6e38b739-2872-52fg-9gb7-e8gf8185be69", 
     "organization_id":"7281793f-8474-727d-7688-72893f747g7e", 
     "project_id":"7281793f-8474-727d-7688-72893f747g7e", 
     "name":"my_first_hub", 
     "status":"ready", 
     "product_plan":"plan_dedicated", 
     "endpoint":"iot.fr-par.scw.cloud", 
     "created_at":"2023-04-06T09:37:31.162Z", 
     "updated_at":"2023-04-06T09:37:31.162Z", 
     "enabled": true,  
     "device_count":0, 
     "connected_device_count":0, 
     "disable_events": false, 
     "events_topic_prefix":"$SCW/events", 
     "enable_device_auto_provisioning": false, 
     "has_custom_ca": false
     }
   

Set up your IoT device

1. Edit the following POST request payload to create your first device.

   Note

   For the sake of simplicity, the following payload allows the device to connect using insecure protocols (such as plain text MQTT or MQTTs without mutual authentication). In production, you should always deny insecure connections to ensure the highest level of security. This would be done by setting the field allow_insecure to false.

   {
     "name": "my-first-device",
     "description": "This is a description for my first device that will act as subscriber"
     "allow_insecure": "true",
   }
   

   Parameters	Description
   name	Device name
   description	A description of your device.
   allow_insecure	Whether or not you allow insecure connections. Values are either true or false.

2. Create your first device. Run the following command to create your first device.

   Note

   The response output will be saved in a file called mydev1.json and then piped to jq < mydev1.json to pretty-print the output in your terminal.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "hub_id": "'$(jq -r '.id' myhub.json)'",
       "name": "my_first_device",
       "description": "This is a description for my first device that will act as subscriber",
       "allow_insecure": true
       }' \
   "$IOT_API/devices" > mydev1.json
   jq < mydev1.json
   

   You should get an output similar to the following, providing information about your device.

   Note

   This is a response example, the UUIDs displayed are not real.

   {
     "device": {
       "id": "98896561-9547-46a7-aa5b-8117a71a4b3c",
       "name": "my_first_device",
       "status": "enabled",
       "hub_id": "6e38b739-2872-52fg-9gb7-e8gf8185be69",
       "created_at": "2023-04-06T11:01:31.698Z",
       "updated_at": "2023-04-06T11:01:31.698Z",
       "allow_insecure": true,
       "last_activity_at": "1970-01-01T00:00:00Z",
       "is_connected": false,
       "message_filters": {
         "publish": {
           "policy": "reject",
           "topics": []
         },
         "subscribe": {
           "policy": "reject",
           "topics": []
         }
       },
       "allow_multiple_connections": false,
       "description": "This is a description for my first device that will act as subscriber",
       "has_custom_certificate": false
     },
     "certificate": {
       "crt": "<certificate here>",
       "key": "<certificate key here>"
     }
   }
   

3. Create your second device. Run the following command to create your second device.

   curl -X POST \
     -H "X-Auth-Token: $SCW_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "hub_id": "'$(jq -r '.id' myhub.json)'",
       "name": "my_second_device",
       "description": "This is a description for my second device that will act as publisher",
       "allow_insecure": true
       }' \
   "$IOT_API/devices" > mydev2.json
   jq < mydev2.json
   

Subscribe and publish

In the next part, you will simulate two devices to indicate how to set them up as publishers and subscribers.

1. Set up the subscriber. Open a new terminal window and run the following command to subscribe to an MQTT topic.

   mosquitto_sub \
     -h $(jq -r '.endpoint' myhub.json) \
     -i $(jq -r '.device.id' mydev1.json) \
     -t mytopic/mysubtopic
   

2. Set up the publisher. Open another terminal window and run the following command to publish a Hello, world! message to an MQTT topic.

   mosquitto_pub \
     -h $(jq -r '.endpoint' myhub.json) \
     -i $(jq -r '.device.id' mydev2.json) \
     -t mytopic/mysubtopic \
     -m 'Hello, world!'
   

   When you open the terminal window you used to set up the subscriber, you should see that the Hello, world! message has successfuly been received.

Technical information

Availability Zones

Hubs can be created in the following Availability Zone:

• Paris fr-par

Going further

For more help using Scaleway IoT Hub, check out the following resources:

• Our main documentation
• The #iot-hub channel on our Slack Community
• Our support ticketing system.

IoT Hubs

IoT Devices

IoT Routes

IoT Networks

IoT Cloud Twins