Jump toSuggest an edit

Configuring IoT Hub routes via the CLI

Reviewed on 04 November 2024

Routes are integrations with the Scaleway ecosystem: they can forward MQTT messages to Scaleway services.

Note

Find out more about IoT Hub Routes in the Routes reference page.

Before you start

To complete the actions presented below, you must have:

A Scaleway account logged into the console
Owner status or IAM permissions allowing you to perform actions in the intended Organization
Installed mosquitto-clients (mqtt client) and jq (JSON parsing tool) on your computer
Installed the Scaleway CLI and read the accompanying IoT document
Installed and configured s3cmd for Scaleway

Amazon S3 Routes

The Amazon S3 route allows you to put the payload of MQTT messages directly into Scaleway’s Object Storage.

Important

This section is a continuation of the Iot Hub CLI quickstart. Make sure to follow the quickstart before beginning.

Run the following commands in a terminal on your computer:

BUCKET="my-bucket-$RANDOM" # Buckets are globally unique, suffix with a random number
REGION="fr-par"
PREFIX="iot/messages"
# Create the bucket
s3cmd mb --region "$REGION" "s3://$BUCKET"
# Grant write access to IoT Hub Amazon S3 Route Service to your bucket
s3cmd setacl --region "$REGION" "s3://$BUCKET" --acl-grant=write:555c69c3-87d0-4bf8-80f1-99a2f757d031:555c69c3-87d0-4bf8-80f1-99a2f757d031
# Create the IoT Hub Amazon S3 Route
scw iot route create \
  hub-id=$(jq -r '.id' hub.json) \
  name=route-s3-cli topic="hello/world" \
  s3-config.bucket-region="$REGION" \
  s3-config.bucket-name="$BUCKET" \
  s3-config.object-prefix="$PREFIX" \
  s3-config.strategy=per_topic

The output will contain something like:

ID                     5ce53577-6905-4b22-970f-d1e345e7345a
Name                   route-s3-cli
HubID                  b20c3639-9030-496c-a1b2-6feb15846726
Topic                  hello/world
Type                   s3
CreatedAt              now
S3Config.BucketRegion  fr-par
S3Config.BucketName    my-bucket-26793
S3Config.ObjectPrefix  iot/messages
S3Config.Strategy      per_topic
UpdatedAt              now

Publish and see the result.

	sleep 5 # wait a little for the route to start
	mosquitto_pub \
	  -h $(jq -r '.endpoint' hub.json) \
	  -i $(jq -r '.device.id' dev2.json) \
	  -t hello/world \
	  -m 'Hello, world!'

An object called iot/messages/hello/world should now be stored in your bucket. Its content should be the words “hello world”.

Retrieve the object using s3cmd:

s3cmd get --region "$REGION" "s3://$BUCKET/$PREFIX/hello/world"
cat world

Database Routes

Database route allows you to store messages in your database.

When creating a Database route for one of your hubs, you must specify a topic (wildcards are allowed), a database (with valid credentials), and a query to execute (the query may contain $TOPIC and $PAYLOAD variables).

Note

$TOPIC and $PAYLOAD are the only available variables for Database routes.

The route will subscribe on this hub to this topic, and execute the query onto the given database for each received message:

First, $TOPIC and $PAYLOAD are replaced with the topic and payload of the received MQTT message,
Then the generated query is executed

Important

In PostgreSQL, the topic database field must be a of text type, and the payload must be a bytea.

This tutorial covers the PostgreSQL database system. You can use a Scaleway Database instance, or any other PostgreSQL instance publicly accessible.

Setting up a Database Route

Before you start

To complete the actions presented below, you must have:

A working PostgreSQL database, with valid credentials (username and password)

Run the following commands in a terminal on your computer:

# Database settings
DBHOST=<your db host>
DBPORT=<your db port>
DBNAME=<your db name>
DBUSER=<your db user>
DBPASS=<your db password>
# Create the target database table
psql -h $DBHOST --port $DBPORT -U $DBUSER -d $DBNAME -c '
  CREATE TABLE messages (
    time timestamp,
    topic text,
    payload bytea
  )
'
# Create the IoT Hub Database Route
# The query will insert message topic and payload with current timestamp
scw iot route create \
  hub-id=$(jq -r '.id' hub.json) \
  name=route-db-cli \
  topic="hello/world" \
  db-config.engine="$DBENGINE" \
  db-config.host="$DBHOST" \
  db-config.port=$DBPORT \
  db-config.dbname="$DBNAME" \
  db-config.username="$DBUSER" \
  db-config.password="$DBPASS" \
  db-config.query='INSERT INTO messages VALUES (NOW(), $TOPIC, $PAYLOAD)'

The output should look like the example below:

ID                 2251e2b1-c616-4a7e-9e72-b658da656424
Name               route-db-cli
HubID              b20c3639-9030-496c-a1b2-6feb15846726
Topic              hello/world
Type               database
CreatedAt          now
DbConfig.Engine    postgresql
DbConfig.Host      127.0.0.1
DbConfig.Port      5432
DbConfig.Dbname    route_tests
DbConfig.Username  jdoe
DbConfig.Password  <your_pass>
DbConfig.Query     INSERT INTO messages VALUES (NOW(), $TOPIC, $PAYLOAD)
UpdatedAt          now

Publish a message and check whether it is inserted into the message table.

sleep 5 # wait a little for the route to start
mosquitto_pub \
  -h $(jq -r '.endpoint' hub.json) \
  -i $(jq -r '.device.id' dev2.json) \
  -t hello/world \
  -m 'Hello, world!'
psql -h $DBHOST --port $DBPORT -U $DBUSER -d $DBNAME -c "SELECT * FROM messages"

Tip

More examples including MySQL and more advanced features are available on the Database Routes tips & tricks page.

Rest Routes

Rest route allows you to call any HTTP(s) endpoint on the received MQTT message. You can choose the HTTP verb used to call your REST uri, as well as add extra headers.

We can see what a rest route would publish on a rest API by simply listening to the port 80 on a public IP.

You can use a Scaleway Instance, or any other machine with a public IP address.

Launch the following command as root:

nc -p 80 -l

Define a variable with the public IP address of your Instance.

RESTHOST=<the_public_ip_address>

Create the route by running the following command:

# Create the IoT Hub Rest Route
scw iot route create \
  hub-id=$(jq -r '.id' hub.json) \
  name=route-rest-cli \
  topic="hello/world" \
  rest-config.verb=post \
  rest-config.uri="http://$RESTHOST/" \
  rest-config.headers.X-My-Header="Tutorial"

Publish a message and check that it triggers a request on the Instance.

sleep 5 # wait a little for the route to start
mosquitto_pub \
  -h $(jq -r '.endpoint' hub.json) \
  -i $(jq -r '.device.id' dev2.json) \
  -t hello/world \
  -m 'Hello, world!'

The output should be:

POST / HTTP/1.1
Host: <the_public_ip_address>
User-Agent: Go-http-client/1.1
Content-Length: 13
X-Mqtt-Retain: false
X-Mqtt-Topic: hello/world
X-My-Header: Tutorial
Accept-Encoding: gzip
Hello, world!