Scaleway Elements IoT Hub - Devices

IoT Hub Devices - Overview

A Device is a representation of a device or program that is connected to the cloud. Through a Hub, it exchanges messages with other Devices and cloud services.

Devices use the MQTT protocol to send and receive messages. MQTT over Websocket is also supported through a dedicated Network.

The Hub provides per-device usage metrics, see this page for more information.


Security modes

A device can be configured to either Deny or Allow insecure connections. In other words, connection security is either required or optional. Here is how this translates with the 3 available connection methods.

By default, you can only open a single connection per Device. Opening a second one with the same credentials will terminate the first one, so you will notice if your device credentials are used by another MQTT client. If you want multiple MQTT to share the same credentials, you can turn on the allow multiple connections setting for a Device (not available on Shared plan Hubs).

The Device ID therefore provides a simple way of authenticating a device, which should not be considered secure. To establish a secure connection, a Device must connect using mutual TLS authentication.

  • Mutual-authentication TLS This is the strongest security for a Device. The connection is encrypted with TLS, and during the handshake the Hub will verify the identity of the Device, and the Device the identity of the Hub.
    For that two-way verification to occur, the client must possess the Device’s certificate and private key, which are displayed only once at the creation of the Device (Scaleway does not store them). It must also possess the certificate authority of the Hub, which can be downloaded from the Hub overview.

    If the Device is configured to Deny Insecure connection, it must connect in this mode.
    If the Device is configured to Allow Insecure connection, it may connect in this mode.

  • Server-authentication TLS This mode offers an intermediate level of security. The connection is still encrypted, but only the Device verifies the identity of the Hub, not the other way around. For that one-way verification to occur, the physical device must only possess the certificate authority of the Hub, which can be downloaded from the Hub’s Network tab.

    If the Device is configured to Deny Insecure connection, it cannot connect in this mode.
    If the Device is configured to Allow Insecure connection, it may connect in this mode.

  • Plain This mode offers least security. The connection is neither encrypted nor authenticated. This is a good starting point for application development, but we recommend avoiding it in production stage.

    If the Device is configured to Deny Insecure connection, it cannot connect in this mode.
    If the Device is configured to Allow Insecure connection, it may connect in this mode.

For both TLS modes, your MQTT clients can authenticate the Hub with the Server Certificate Authority, which is available in the IoT Hub Networks tab in your Scaleway Console, in the Default MQTT Network item.

Please note you will deal with 2 different Certificate Authorities (CA): the Hub CA which signs Device certificates, and the Server CA which signs IoT Hub Endpoint certificate.

Devices can also be identified by a custom certificate authority (CA). See this page for instructions on how install a custom CA on a Hub. When using a custom CA, devices will be identified by the common name of their provided certificates. If a device with that name does not exist in the Hub, it will be disconnected during the TLS handshake, unless you enable device auto-provisioning. When device auto-provisioning is enabled, if there’s no Hub device corresponding to the common name, a Hub device will be created and the device won’t be disconnected. See this page for instructions on how enable device auto-provisioning. If you want to customize auto-provisioned devices, you can set up a REST route to trigger on the associated Hub events.

Important: When using a custom CA, the complete certificate chain, from the device certificate up to the custom CA installed in the Hub, must be provided when establishing the TLS connection. Failing to do so will result in the client being disconnected during the TLS handshake. The Hub relies on the Certificate Authority to find your Hub, and on the certificate chain to check that the device certificate was directly or indirectly signed by the custom CA.


Device Identification

A Device can identify itself to IoT Hub in 2 different ways:

  • By certificate Issue a certificate with the Common Name field set to the Device Name. This can only be used when the Device connects with mutual-authentication TLS, in other modes the Device doesn’t use a certificate.

  • By device ID Use the Device ID in the MQTT Username field. Alternatively, you can also use it as MQTT Client ID. However, this is not recommended for new applications as this option is now deprecated.


Multiple connections for a Device

By default, you can only open a single connection per Device. Opening a second one with the same credentials will terminate the first one so you will notice if your device credentials are used by another MQTT client. If you want multiple MQTT to share the same credentials, you can turn on the allow multiple connections setting for a Device (not available on Shared plan Hubs).


Message filters

Message filters allow you to control which topics a device can publish and subscribe to. There is a publish filter and a subscribe filter, each filter operates independently.

You can either accept topics in the list (topic whitelist) or reject topics in the list (topic blacklist). Topics in the lists may contain MQTT wildcards. You can type in as many topics as you want, one topic per line.

A message published to a forbidden topic will be dropped. When subscribing, if at least one subscription matches a forbidden topic (directly or using a wildcard) the whole subscription will be rejected. In both cases yon can monitor Hub events to detect such errors.

The default filter does not restrict publications and subscriptions, thus accepting all topics.

Note: This is not equivalent to “Accept #” because MQTT ‘#’ wildcard excludes topics starting with ‘$’, as per the MQTT specification.

Message filters template

Note: This feature is currently in beta status.

The Message filters now accept templating to use some metadata associated with the Hub and Device to be used in the filter.

The following elements are available:

  • hub.name: The Hub’s name
  • hub.id: The Hub’s ID
  • device.name: The Device’s name
  • device.id: The Device’s ID

To use them in your message filters use double curly brackets arround the element you want to use. For example:

    /{{ hub.name }}/{{ device.name }}/#

Will build the following filter when the Hub is named MyHub and the Device MyDevice:

    /MyHub/MyDevice/#

Issues when parsing the template will be reported through Hub events as warnings, in that case the filter may be dropped from the list.

Note: This feature is currently in “beta”, it might still change while we add templating to other components of the IoT Hub, in order to unify the experience inside the platform.


How to create a Device

Once you have created a Hub, you can add a Device to it.

1 . Click Add Devices in the Devices tab of your Hub.

Add Device IoT Hub

2 . Enter a name for your Device. It must be unique among the devices in this hub, and can’t be changed once created.

Name Device IoT Hub

3 . (Optional) Set a Device description. This is only for display purposes.

4 . Choose a security setting for your Device.

 IoT Hub Device Security

5 . Click Add a Device to your Hub.

6 . The credentials of the Device are displayed. You must keep them safe for later as we do not store the private key ourselves.

 IoT Hub Device Credentials

Important: Make sure to download or copy the device certificate and the device private key. These files are required to establish a connection from the device to your hub. For security reasons the private key is not stored on our side, and you will not be able to access it later.

7 . Click Close or Add a new Device.

8 . Once the device is added, you may continue to configure IoT Hub Routes to export your data to other Scaleway services.


How to delete a Device

1 . In the IoT Hub section of the Scaleway console, click on the IoT Hub that contains the device you want to delete.

2 . Click on the Devices tab to list your devices, then on the device you want to delete.

 IoT Hub Device List

3 . On the Device details page, click Delete Device.

 IoT Hub Device Credentials

4 . Confirm the deletion of the device in the popup.

Important: The device won’t be able to connect once deleted. If the device is still connected to the Hub, it will be disconnected.

Note: It is also possible to delete multiple Devices at once by selecting them in the Device list.

Examples and tutorials


Learn more about Scaleway IoT Hub, discover how to add Devices to the hub, check the IoT Hub metrics or get started in a few clicks with the IoT Hub Kickstarts.

Discover the Cloud That Makes Sense