Triggering functions from IoT Hub messages

Published on 21 August 2020

Function as a Service allows developers to run code without the hassle of managing the server/instance running it.

IoT Hub allows messages to be exchanged between devices and business-specific software. Some or all components of this software can be implemented using Function as a Service, and IoT Hub can be configured to trigger these functions to process messages being exchanged on the Hub.

Security & Identity (IAM):

You may need certain IAM permissions to carry out some actions described on this page. This means:

you are the Owner of the Scaleway Organization in which the actions will be carried out, or
you are an IAM user of the Organization, with a policy granting you the necessary permission sets

Requirements:

You have an account and are logged into the Scaleway console
You have created a function
You have created an IoT Hub and added a Device

How to set up a Route to a Function

Instruct your IoT Hub to trigger your function when a message is published on the my/super/topic topic. To do so we will use an IoT Hub REST Route.
Click the Routes tab of your IoT Hub.
Create a new route with the following settings:
- Name: any name you want
- Topic: my/super/topic
- Route type: REST Query
- Method: POST
- Endpoint: the Function endpoint you got earlier
- HTTP Headers: leave empty

In a typical use-case, the same Function will be used for many topics. It is possible to achieve this by using MQTT wildcards in the Route topic. You can then rely on the X-Mqtt-Topic HTTP header in your Serverless Function for your topic-based processing. Please see this blog post for more information about MQTT topics.

How to trigger the Function

Click the MQTT Webclient button on your device information page. The client will open and automatically connect.
Publish a message to the my/super/topic topic. In the Publish block:
- Write my/super/topic as the topic
- Leave QoS as 0
- Leave Retain unticked
- Write Hello World ! as the message
- Click Publish (no confirmation will be issued)
You can see your published message in the function logs.

Note:
There may be a few minutes delay before the logs show up.

How to reply to a message

In many cases, your Function will want to publish a message to react to the received message.

To allow this action, add an X-Mqtt-Topic header to your reply, and a new message will be published on your IoT Hub under the topic.

The content of the message will be the body of the reply.

Important:

The HTTP status code needs to be in the 2xx range.

How to use private Functions

If you require authentication to protect your Serverless Function, here is how to do it:

Click the settings tab of your function settings tab and tick the Private option.
Generate a token for your function.
Re-create your IoT Hub Route with the following HTTP header: SCW_FUNCTIONS_TOKEN: <function token here>.

Your Function is now private and still accessible from IoT Hub!