Scaleway Elements IoT Hub - Routes

IoT Hub Routes - Overview

Routes allow your IoT Hub to forward messages to non-MQTT destinations.

Currently the following routes are available:


Scaleway Object Storage Route

Scaleway Object Storage is an object storage service provided by Scaleway and based on the S3 protocol.

The purpose of the Scaleway Object Storage Route is to store specific messages (published on a given topic) in a bucket.

Important: It is required to create the Object Storage bucket before creating the Route.

Messages Store Strategies

There are two distinct strategies for storing messages:

  • Per Topic
    Messages published on the same topic are stored in the same object (the last message overwriting the previous ones). The object name is composed of the prefix you chose and the topic name.

    For example: Publishing to 'hello/world' will create 's3://my-bucket/my-prefix/hello/world' object.

  • Per Message
    Each published message is stored in a distinct object. The object name is composed of the prefix you chose, the topic name and the timestamp the message is received on the route.

    For example: Publishing to 'hello/world' will create a 's3://my-bucket/my-prefix/hello/world/2006-01-02T15:04:05.999999999Z' object.

Permissions

When creating a Scaleway Object Storage Route through the Scaleway console, a write permission is automatically granted to the IoT platform for the selected bucket.

If the route is created using the Scaleway API or the CLI (Command Line Interface), the write permission on the target bucket must be manually granted to the IoT Hub:

> s3cmd setacl s3://<my-bucket> --acl-grant=write:555c69c3-87d0-4bf8-80f1-99a2f757d031:555c69c3-87d0-4bf8-80f1-99a2f757d031

Database Route

The purpose of the Database Route is to store specific messages (published on a given topic) in a database, or trigger the execution of any other SQL query on the given database. You need to create your Database before creating the Route. If you are not yet familiar with creating a Scaleway Elements Database, you can follow the documentation available here.

Supported databases:

  • PostgreSQL
  • MySQL

Writing the Query

When the given topic filter is matched, the provided query is executed on the given database.

This SQL query can use the two following pre-defined parameters:

  • $TOPIC: The string matching the topic on which the message was sent
  • $PAYLOAD: The payload of the MQTT message

Following is an example of the simplest request you can use to write the topic and payload in a pre-existing table «messages»: INSERT INTO messages (topic, payload) VALUES ($TOPIC, $PAYLOAD)

Note: $TOPIC and $PAYLOAD are both variables of a prepared statement.

This means that their respective PostgreSQL types are used:

  • text for $TOPIC
  • bytea for $PAYLOAD

On MySQL the types will also be determined at preparation time, see the MySQL PREPARE documentation for details.

Note: $TOPIC and $PAYLOAD may both appear multiple times in the query.

Writing the Query

Although $PAYLOAD is binary and $TOPIC is text, all postgresql functions and type conversions can be used to manipulate them. For example, if published payloads are always float values, they can be stored as a float into the database. The payload may also be decoded as JSON if needed. The query will be run by postgres, which means that all the expressiveness offered by postgres is available.

Examples using the advanced features of postgresql are available on the database route tips & tricks page.

REST Route

The purpose of the REST Route is to forward any messages published on a selected topic to a REST service.

Currently, the supported HTTP Verbs are: GET, POST, PUT, PATCH and DELETE.

Additional information:

  • By default, following headers are appended to the HTTP call:
    • X-MQTT-Topic: topic of the MQTT message
    • X-MQTT-Retain: Retain flag, which can be either true or false. (This feature is not available on shared plan hubs)
  • You can add a maximum of 10 extra headers.
  • HTTP redirections are not followed.

If the HTTP reply contains an HTTP OK status code (2xx) and a X-MQTT-Topic header, the reply payload will be published to this topic.

How to Create a Route

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

1 . Click on the Routes tab in the configuration of your hub.

2 . In the Routes page, click Create a Route.

Add IoT Hub Route

The Add a new Route form displays:

Add IoT Hub Route

  • Enter a name for your Route.
  • Enter the topic filter you want your route to subscribe to. This topic filter can contain wildcards (+ and #).
  • Choose the type of Route you want to create.
  • Configure the settings according to the type of route.

For an Object Storage Route:

  • Select the region of your Object Storage bucket.
  • Choose the bucket you want to store messages in (you cannot directly create a bucket from the «Object Storage» Route screen).
  • Enter the prefix that will be prepended to object names.
  • Select how your messages will be stored in the bucket (per topic or per message).

For a Database Route:

  • Enter the SQL query to be executed when the topic filter is matched.
  • Enter the settings to access to the database:
  • Engine: PostgreSQL or MySQL
  • Host: host name or IP address
  • Port: port number
  • Name: name of the database
  • Username: user name to use while connecting to the database
  • Password: password of the user

For a REST Route:

  • Choose the HTTP Verb used to call the uri.
  • Enter the REST Route endpoint.
  • Add optional HTTP headers.

3 . Click Add a new route to confirm.

How to Update a Route

After creating a Route, it is possible to edit it to change some of its configuration.

1 . Click on the Routes tab in the configuration of your hub.

2 . Locate the route that you need to update in the list, and click on the menu button on the right of this route.

3 . On the menu that pops up, select Edit.

Edit IoT Hub Route

4 . Edit the configuration as needed.

5 . Click Update Route to confirm.

How to Delete a Route

In the Routes tab of a Hub, click on the delete icon next to the route to delete:

Delete IoT Hub Route

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