|
| 1 | +--- |
| 2 | +title: MQTT bridge |
| 3 | +group: tools |
| 4 | +description: 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. |
| 5 | +--- |
| 6 | + |
| 7 | +## Introduction |
| 8 | + |
| 9 | +MQTT (MQ Telemetry Transport) is a protocol designed on top of TCP/IP and based on a publish/subscribe principle. See [this page]({% link docs/tools/mqtt-broker.md %}) for a detailed description of MQTT and IoT-LAB broker, notably how to connect to it using the MQTT client of your choice. |
| 10 | + |
| 11 | +This page describes the use of `iotlab_mqtt_bridge`, a tool designed to bridge nodes serial ports to any MQTT broker. |
| 12 | + |
| 13 | +## Installation |
| 14 | + |
| 15 | +The tool is available as a python package, so `pip3 install iotlab_mqtt_bridge` should be sufficient to install it. |
| 16 | + |
| 17 | +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). |
| 18 | + |
| 19 | +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. |
| 20 | + |
| 21 | +## Principle |
| 22 | + |
| 23 | +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]({% link docs/tools/serial-aggregator.md %}) |
| 24 | +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. |
| 25 | + |
| 26 | + |
| 27 | +<figure style="text-align:center"> |
| 28 | + <img src="{{ '/assets/images/docs/mqtt/' | relative_url}}MQTT-bridge.png" style="width:500px;"/><br/> |
| 29 | + <figcaption>The iotlab_mqtt_bridge architecture</figcaption> |
| 30 | +</figure> |
| 31 | + |
| 32 | + |
| 33 | +### Node topics construction |
| 34 | + |
| 35 | +Each individual node topic root is constructed as follow : |
| 36 | + 1. The local node name is extracted from its address. Ex: `dwm1001-1.toulouse.iot-lab.info` becomes `dwm1001-1` |
| 37 | + 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. |
| 38 | + 3. `topic_root` is prepended to this identifier to form the `node_topic` |
| 39 | + |
| 40 | + |
| 41 | +### Node output handling |
| 42 | + |
| 43 | +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. |
| 44 | + |
| 45 | +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. |
| 46 | + |
| 47 | +### Node input handling |
| 48 | + |
| 49 | +Each message published on `<node_topic>/in` gets written directly on the serial port of the associated node. |
| 50 | + |
| 51 | +## Options |
| 52 | + |
| 53 | + |
| 54 | +See `iotlab-mqtt-bridge --help` for detailed options. Notably, the following parameters of the bridge can be configured : |
| 55 | + * IoT-LAB API credentials, automatically read from ~/.iotlabrc (generated by `iotlab-auth`) if not provided as argument or environment variable. |
| 56 | + * broker (IP, broker port, encryption certificate, authentification) |
| 57 | + * verbosity |
| 58 | + * topic root (`topic_root` hereafter) is used to construct individual node topics. |
| 59 | + * ID dictionnary (json file) used to convert iotlab IDs to a custom set of ids (each must be unique). |
| 60 | + |
| 61 | +Most of these arguments can be passed as environment variable, see help for the corresponding variables. |
| 62 | + |
| 63 | +The arguments not described in `iotlab-mqtt-bridge --help` are passed down the `serial_aggregator` (on which this project is based). |
| 64 | + |
| 65 | +## Known issues |
| 66 | + |
| 67 | + * The serial port can be opened only once. Consquently : |
| 68 | + * A given node can be bridged by only one iotlab\_mqtt\_bridge at a time |
| 69 | + * Web serial consoles must be closed before starting the MQTT bridge |
| 70 | + * `serial_aggregator` can not access a given node at the same time as `iotlab_mqtt_bridge` |
| 71 | + * Serial ports can be disturbed when nodes are flashed, so it may be necessary to restart `iotlab_mqtt_bridge` after re-flashing the nodes. |
| 72 | + |
| 73 | +## Usage |
| 74 | + |
| 75 | +### CLI on SSH frontend |
| 76 | + |
| 77 | +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`). |
| 78 | + |
| 79 | + |
| 80 | +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>`. |
| 81 | + |
| 82 | +### Run script |
| 83 | + |
| 84 | +#### CLI |
| 85 | + |
| 86 | +See the [run script documentation]({% link docs/tools/run-script.md %}) 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. |
| 87 | + |
| 88 | +#### Python examples |
| 89 | + |
| 90 | +See [this python script](https://github.com/iot-lab/iotlab-mqtt-bridge/blob/master/iotlab_mqtt_bridge/examples/script_launcher.py) for a sample script that creates an experiment (node reservation, firmware association, ...) with the `iotlab_mqtt_bridge` script association. |
0 commit comments