Navigate the docs

MQTT bridge

This document shows how to use the iotlab_mqtt_bridge tool. In this document, you will learn how to bridge the serial inputs/outputs of the nodes in a experiment to a MQTT broker.

Introduction

MQTT (MQ Telemetry Transport) is a protocol designed on top of TCP/IP and based on a publish/subscribe principle. See this page for a detailed description of MQTT and IoT-LAB broker, notably how to connect to it using the MQTT client of your choice.

This page describes the use of iotlab_mqtt_bridge, a tool designed to bridge nodes serial ports to any MQTT broker.

Installation

The tool is available as a python package, so pip3 install iotlab_mqtt_bridge should be sufficient to install it.

On your own computer you will not be able to launch the module directly, but you will be able to use the module in scripts to start the bridge when an experiment launches (see example below).

On iotlab ssh frontends, the script may already be installed by your local admin (such as toulouse.iot-lab.info for example). If not, you can ask them or install it at user level in your home directory.

Principle

The core of the module is a script intended to be run on an iotlab ssh frontend. It connects to the serial port of the nodes using serial aggregator and bridges it to several topics, publishing to the out topics what comes out of the serial port and writing to the serial port what was published to the in topic.


The iotlab_mqtt_bridge architecture

Node topics construction

Each individual node topic root is constructed as follow :

  1. The local node name is extracted from its address. Ex: dwm1001-1.toulouse.iot-lab.info becomes dwm1001-1
  2. If an ID dictionnary was provided, this local node name (dwm1001-1 in our example) is used as a key in the dictionnary to determine the new identifier, otherwise the local name is used as identifier.
  3. topic_root is prepended to this identifier to form the node_topic

Node output handling

The serial output of each node is split into substrings at every \n character, then each substring is published in a single message (containing also the node id and a timestamp) on a specific topic (<node_topic>/out) for each node.

If this substring can be parsed as a JSON object, it is also published on a second topic (<node_topic>/out_json). The payload of messages on the latter topic are thus guaranteed to be valid json objects.

Node input handling

Each message published on <node_topic>/in gets written directly on the serial port of the associated node.

Options

See iotlab-mqtt-bridge --help for detailed options. Notably, the following parameters of the bridge can be configured :

  • IoT-LAB API credentials, automatically read from ~/.iotlabrc (generated by iotlab-auth) if not provided as argument or environment variable.
  • broker (IP, broker port, encryption certificate, authentification)
  • verbosity
  • topic root (topic_root hereafter) is used to construct individual node topics.
  • ID dictionnary (json file) used to convert iotlab IDs to a custom set of ids (each must be unique).

Most of these arguments can be passed as environment variable, see help for the corresponding variables.

The arguments not described in iotlab-mqtt-bridge --help are passed down the serial_aggregator (on which this project is based).

Known issues

  • The serial port can be opened only once. Consquently :
    • A given node can be bridged by only one iotlab_mqtt_bridge at a time
    • Web serial consoles must be closed before starting the MQTT bridge
    • serial_aggregator can not access a given node at the same time as iotlab_mqtt_bridge
  • Serial ports can be disturbed when nodes are flashed, so it may be necessary to restart iotlab_mqtt_bridge after re-flashing the nodes.

Usage

CLI on SSH frontend

If iotlab_mqtt_bridge was installed by an admin on the SSH frontend you are using, simply running iotlab_mqtt_bridge without arguments will bridge your nodes to the broker mqtt4.iot-lab.info using iotlab/<login> as a base topic (this requires a ~/.iotlabrc file generated by iotlab-auth).

If it was manually installed, you can use python3 -m iotlab_mqtt_bridge -b <x.x.x.x> -u <broker_username> -p <broker_password> -t "topic_root/" . If TLS is used on the broker, it may be necessary to use the argument -C <ca_cert>.

Run script

CLI

See the run script documentation to learn more about starting a script when an experiment is launched. In this case, you will have to pass the arguments as environment variables using a script config file.

Python examples

See this python script for a sample script that creates an experiment (node reservation, firmware association, …) with the iotlab_mqtt_bridge script association.