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 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",
    }
    ParameterDescription
    project_idID of the Project to create your flexible IP in.
    nameName of the Hub.
    product_planProduct 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 .
  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",
    }
    ParametersDescription
    nameDevice name
    descriptionA description of your device.
    allow_insecureWhether 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.

Requirements

To perform the following steps, you must first ensure that:

  • You have a
  • You have and that the API key has sufficient to perform the actions described on this page
  • You have
  • You have
  • You have

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
  • The #iot-hub channel on our
  • Our .

IoT Hubs

Send and receive messages from connected IoT devices through managed message brokers

GET
/iot/v1/regions/{region}/hubs
POST
/iot/v1/regions/{region}/hubs
GET
/iot/v1/regions/{region}/hubs/{hub_id}
PATCH
/iot/v1/regions/{region}/hubs/{hub_id}
DELETE
/iot/v1/regions/{region}/hubs/{hub_id}
GET
/iot/v1/regions/{region}/hubs/{hub_id}/ca
POST
/iot/v1/regions/{region}/hubs/{hub_id}/ca
POST
/iot/v1/regions/{region}/hubs/{hub_id}/disable
POST
/iot/v1/regions/{region}/hubs/{hub_id}/enable
GET
/iot/v1/regions/{region}/hubs/{hub_id}/metrics

IoT Devices

Control which specific IoT devices are allowed to connect to a Hub

GET
/iot/v1/regions/{region}/devices
POST
/iot/v1/regions/{region}/devices
GET
/iot/v1/regions/{region}/devices/{device_id}
PATCH
/iot/v1/regions/{region}/devices/{device_id}
DELETE
/iot/v1/regions/{region}/devices/{device_id}
GET
/iot/v1/regions/{region}/devices/{device_id}/certificate
PUT
/iot/v1/regions/{region}/devices/{device_id}/certificate
POST
/iot/v1/regions/{region}/devices/{device_id}/disable
POST
/iot/v1/regions/{region}/devices/{device_id}/enable
GET
/iot/v1/regions/{region}/devices/{device_id}/metrics
POST
/iot/v1/regions/{region}/devices/{device_id}/renew-certificate

IoT Routes

Set up managed routes to control how IoT device messages are sent and received within a Hub

GET
/iot/v1/regions/{region}/routes
POST
/iot/v1/regions/{region}/routes
GET
/iot/v1/regions/{region}/routes/{route_id}
PATCH
/iot/v1/regions/{region}/routes/{route_id}
DELETE
/iot/v1/regions/{region}/routes/{route_id}

IoT Networks

Connect a Hub to external networks and services using links to external IoT networks

GET
/iot/v1/regions/{region}/networks
POST
/iot/v1/regions/{region}/networks
GET
/iot/v1/regions/{region}/networks/{network_id}
DELETE
/iot/v1/regions/{region}/networks/{network_id}

IoT Cloud Twins

Create cloud twins as virtual representations of IoT devices in the cloud to manage, monitor, and control them remotely

GET
/iot/v1/regions/{region}/twins/{twin_id}
DELETE
/iot/v1/regions/{region}/twins/{twin_id}
GET
/iot/v1/regions/{region}/twins/{twin_id}/documents/{document_name}
PUT
/iot/v1/regions/{region}/twins/{twin_id}/documents/{document_name}
PATCH
/iot/v1/regions/{region}/twins/{twin_id}/documents/{document_name}
DELETE
/iot/v1/regions/{region}/twins/{twin_id}/documents/{document_name}
Cloud Products & Resources
Dedicated Products & Resources
Scaleway
Follow us
© 1999-2024 – Scaleway SAS