Scaleway Elements IoT Hub - Networks

IoT Hub Networks - Overview

Networks allow devices, ranging from embedded systems to server software, to exchange messages with IoT Hub.

There are currently 4 network types:

• The MQTT network type, which uses the MQTT protocol.
• The Websocket network type, which uses the Websocket protocol.
• The Sigfox network type, which allows your Sigfox devices to communicate with your Hub.
• The REST network type, which allows any http client to communicate with your Hub.

Other network types are planned for future versions of the Hub.

Networks and authentication

Networks provide two different authentication mechanisms:

• Auth-by-device (MQTT, Websocket): the Hub client provides device credentials. All device features apply (message filters, metrics, …).
• Auth-by-token (Sigfox, REST): the Hub client provides a secret token. Published messages skip the device features and go directly to the message broker.

The Default Network (MQTT)

The default MQTT network, which is automatically created with a Hub, is a MQTT network. Being a default network, it cannot be deleted.

Here is a quick tutorial that explains how to connect to the MQTT network:

1 . Create a Hub device if you haven’t already done so. To keep this tutorial simple, choose to Allow Insercure connections.

2 . Configure the physical device (or client) to connect through the Network, using the following parameters:

• Host: The network endpoint.
• Port: Use 1883 for plaintext or 8883 for TLS.
• MQTT Username: The Device ID from the device you created earlier.
• If your client asks for a password, just pass in an empty string.

If you have configured your device to force mTLS (Deny Insecure connections*), you’ll also need to provide the Device certificate & private key, so that during the TLS handshake, the Hub will be able to verify the device identity.

3 . Connect and exchange messages.

Some networks support topic prefixes, but the default networks do not. The whole “topic space” is available to MQTT clients.

The Default Network (Websocket)

The default Websocket network, which is automatically created with a Hub, is a MQTT-over-Websocket network.

It can be used in the same way as the MQTT network above, except the network endpoint is different and the ports are 80 for HTTP and 443 for HTTPS.

Note: Mutual TLS authentication is not yet available on this network, which means that devices that connect over this network must Allow Insecure connections.

The Sigfox Network Type

The Sigfox Network type allows devices communicating with the Sigfox protocol to exchange messages with the IoT Hub. Sigfox will collect messages from your devices, and relay them to your IoT Hub.

The Sigfox network doesn’t support downlink messages yet. This will be available soon.

Setting-up a Sigfox Network

Here is a quick tutorial that explains how to use the Sigfox network with an IoT Hub.

To setup a Sigfox Network, a Sigfox account is needed. If you don’t have an account, take a look at this page to get started.

1 . On a Hub in the Scaleway console, and click on the Networks tab.

2 . On the Networks tab, click on the Add network button (the green +) to open the network creation form.

3 . Fill-in the different fields.

• Enter a name for your Network.
• Choose Sigfox as the type of Network you want to create.
• Choose a topic prefix your Network should publish to. You may leave this empty. All the messages published to this network will have their topics prefixed with this value.

4 . Click ‘Create Network’

The last page will show a summary of the network you just created, and 2 key parameters:

• The Network endpoint.
• The Network secret. Be careful, this secret will only be shown once !

This information will be needed to configure the Sigfox backend.

Configuring the Sigfox backend

Now you have successfully created your Sigfox network, it’s time to configure the Sigfox callbacks to relay messages to your Iot Hub.

1 . Login the Sigfox backend here

2 . Go the DEVICE TYPE tab

3 . Click on the CALLBACKS entry in the left menu

4 . Select the Custom callback option

5 . Fill-in the form like the image below.

Let’s go through each field:

• Type: DATA UPLINK because we do not support BIDIR callback (but we will soon, stay tuned)
• Channel: URL.
• Custom payload config: Leave it empty.
• Url pattern: Put the network endpoint in this field, for example https://sigfox.iot.fr-par.scw.cloud.
• Url method: POST.
• Send SNI: Check this box.
• Headers: In this section, we need to define three headers. Do not worry if you only see a single line, once you click on it a new empty line will appear.

• Choose a Content type and Body that fits your needs. In the example above we chose to send a JSON payload.

Wrapping-up

In this example, if the device id is A1234B, the sensor payload is ABCDEF01, the topic header is {device}/payload, and the Network prefix is myapp, then a message will be received on the myapp/A1234B/payload topic, containing the following payload:

{
	"data": "ABCDEF01",
	"id": "A1234B"
}

The REST Network Type

The REST Network type allows any HTTP client to send messages to the IoT Hub.

The REST network only allows publishing messages.

Setting-up a REST Network

1 . On your hub’s page in the Scaleway console, click on the Networks tab.

2 . On the Networks tab, click on the Add network button (the green +) to open the network creation form.

3 . Fill-in the different fields.

• Enter a name for your Network.
• Choose REST as the type of Network you want to create.
• Choose a topic prefix your Network should publish to. You may leave this empty. All the messages published to this network will have their topics prefixed with this value.

4 . Click ‘Create Network’

The last page will show a summary of the network you just created, and 2 key parameters:

• The Network endpoint.
• The Network secret. Be careful, this secret will only be shown once !

Keep this information, we’ll need it in a few minutes.

Using the REST Network

Any HTTP client can be used to publish a message through the Rest Network. The required headers are:

• X-Secret: This is the network secret that was given while creating the network on a Hub.
• X-Topic: This is the topic that the message should be published on.

Here is an example using curl:

> curl -XPOST -H "X-Secret: <network-secret>" -H "X-Topic: <topic>" -d <payload> <network-endpoint>

using following values:

• <network-secret>: Put here the network secret that was given when you created the network on your Hub.
• <network-endpoint>: Put here the network endpoint that was given when you created the network on your Hub.
• <topic>: Choose here the topic that suits your needs. This topic will be prefixed with the network topic.
• <payload>: Put here the payload you want to publish (a JSON string as example).

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.