Scaleway DocumentationIoTIoT HubHow to
Use the Function as-a-Service Kickstart

Jump toUpdate content

How to use the Function as-a-Service Kickstart

Reviewed on 02 June 2021Published on 01 September 2019

The function as-a-Service Kickstart provides a FaaS engine to trigger functions upon receiving messages on your IoT Hub.

It will set up and configure Nuclio on a Scaleway Instance.

Requirements:

How to create the Function as-a-Service Kickstart

  1. Create a new logging purpose Kickstart from the Scaleway console.

  2. Select the IoT Hub and device to use with the Kickstart.

    Important:

    Currently only devices supporting insecure connections are allowed for this IoT Kickstart.

  3. Choose the geographical region to deploy your Kickstart.

  4. Set a password for the Kickstart’s dashboard.

  5. Click Create a Kickstart to launch the installation of the software stack.

Note:

The Kickstart setup process will insert a first log item in the database to make sure it is up and running.

How to use the Function as-a-Service Kickstart

A first example function will be pre-configured for you during the Kickstart installation. It sends a message to a topic named events when triggered and is configured to be triggered when a message is published to any topic under please/react/to/ on your IoT Hub.

In the following example, you add 2 more devices to the IoT Hub you connected the Kickstart to. Device A subscribes to the events topic and device B publishes a message to the please/react/to/hello/world topic.

  1. Click IoT Hub in the IoT Station section of the side menu. The list of your IoT Hubs displays.

  2. Click the name of the IoT Hub you want to configure. The hub’s overview page displays.

  3. Click Devices to display the configuration of the device.

  4. Click Add devices in the devices tab. The Create a Device wizard displays.

  5. Enter a name for the first device, and allow insecure connections.

  6. Click Add a Device to your Hub. The details of the device display. Take a note of the Device ID:

  7. Repeat the steps above to add a second device.

  8. Retrieve your Hub’s endpoint on from the Networks tab. For this tutorial you use the Default MQTT Network:

How to communicate with your Hub

  1. Open a terminal window and define the following variables:

    ID_A="<Device_A_ID>"
    ID_B="<Device_B_ID>"
    ENDPOINT="<Default_MQTT_Network_Endpoint>"
  2. Run the following command using device A to subscribe to events topic: mosquitto_sub -h ENDPOINT -i ID_A -t events.

  3. Run the following command device B to publish a message to please/react/to/hello/world topic: mosquitto_pub -h ENDPOINT -i ID_B -t please/react/to/hello/world -m "Hi there.".

You should have received a message on device A with the following payload: Received a message on please/react/to/hello/world (length: 9). This message was generated by the example function running in Nuclio.

How to process and send messages

The function which will handle your messages will receive two arguments:

  • events.url: the topic the message was published to
  • events.body: the message payload

When the function is done processing the message, it may return a message to be published using the following parameters:

  • response status code: 200
  • response body: the message payload (any data)
  • response header X-MQTT-Topic: the topic to publish message to (any valid topic string)
  • response header X-MQTT-Retain: whether to set the retain flag on the message (boolean value) (optional, default: false)

How to trigger the function

Nuclio connects a MQTT client to the IoT Hub and subscribes to a topic. When a message is received, it runs the function against it and, if requested by the function, publishes back a message on the IoT Hub.

Because of the way triggers are implemented in Nuclio, it spawns one MQTT client per function. This means you need to add an IoT Device to your IoT Hub for each function.

To create the trigger for your function follow these steps:

  1. Open a web browser on your local computer and point it to http://<your_faas_instance_ip>. Authenticate using the admin user and the password set during the configuration of the Kickstart. The Nuclio dashboard displays.

  2. Go to the trigger tab in your function editor in Nuclio dashboard.

    • Select MQTT as trigger class
    • Enter iot.fr-par.scw.cloud:1883 as URL (this may vary, refer to the IoT Hub overview page in your Scaleway console)
    • Enter your device ID as Username, no password required
    • Create a new subscription
    • Choose the topic (MQTT topics documentation) and QoS level (MQTT QoS documentation)
    • Put anything you want in trigger name and worker allocator name
  3. Click Deploy to deploy your function

See Also