Configuring IoT Hub routes via the CLI
Routes are integrations with the Scaleway ecosystem: they can forward MQTT messages to Scaleway services.
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) andjq
(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.
-
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).
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
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"
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!