Software Components

We utilise Docker and Docker Compose to provide all necessary LoRaBridge software components as a multi-container Docker application. The components needed for bridges and gateways vary and are listed below.

Bridge

Butix, based on works by Lucasbosch and Cmykey, Raspberry Pi 3 illustration, modified, CC BY-SA 4.0

As shown here, a bridge needs a ZigBee dongle for connecting ZigBee devices, a LoRaWAN hat for establishing a link to the gateway as well as optionally a network connection.

Zigbee2MQTT

Zigbee2MQTT receives device data from the ZigBee dongle as it handles join events, status updates and so on. It keeps a list of devices and publishes the device data via MQTT messages to Eclipse Mosquitto.

Eclipse Mosquitto

Mosquitto is an MQTT message broker, meaning you can publish your own messages as well as subscribe to messages sent by others. In case of the bridge, Zigbee2MQTT publishes the sensor data to the Mosquitto server, while the Forwarder is subscribed to those.

Forwarder

The Forwarder is a self-provided Python3 program and listens to message on the Mosquitto server. It removes disabled attributes (a list that can be modified via the web interface) and performes a combination of key substitution, YAML reformatting and Brotli compression. The resulting compressed data is pushed to a list in a Redis server.

Redis

Redis is an in-memory data store and is used as a cache / message queue in our case. It receives compressed sensor data from the Forwarder and holds the data until LoRaWAN TX retrieves it.

LoRaWAN TX

LoRaWAN TX is a self-provided C program, which is based on the IBM LMIC code. It establishes a LoRaWAN connection to the gateway, pulls compressed device data from the Redis server and transmits the data to the gateway.

Web Interface

Our web interface is a self-provided SvelteKit web application that shows the ZigBee devices, which are retrieved via the SSE server. It enables you to disable unnecessary sensor attributes, in order to further reduce the transmitted data. Authentication is provided with basic auth via nginx.

Example

SSE Server

The SSE server is a self-provided TypeScript application. It retrieves a list of ZigBee devices from the Zigbee2MQTT server and provides the data per HTTP as well as any updates to the data (e.g. new devices, additional attributes) per server-sent events (SSE) for the web interface.

Basic Auth

This component consists of a nginx and provides authentication for the web interface via Basic HTTP Authentication.

LCD UI

The LCD UI controls the LCD display on the LoRaWAN hat and display various information like how many devices are joined, the state of the LoRaWAN connection and the current ip address. It also provides the ability to allow zigbee devices to join, by pressing the right button below the display. Informations is retrieved via Redis, Mosquitto and Ofelia.

Ofelia

Ofelia is a job scheduler design for docker environments. This container is only connected to the host network and we use Ofelia to periodically retrieve the current IP addresses and store them inside a file. This file is mounted into the LCD UI container and provides thie IP information. This setup is necessary, because docker does not allow a container to belong to multiple networks at once (per docker-compose.yml).

Gateway

Butix, based on works by Lucasbosch and Cmykey, Raspberry Pi 3 illustration, modified, CC BY-SA 4.0

As shown here, a gateway needs a LoRaWAN hat for establishing links to the bridges as well as optionally a network connection.

Packet Forwarder

The Packet Forwarder is a self-provided C application based on this repository that interacts with the LoRaWAN hat. It receives the LoRaWAN packets and publishes the data to the ChirpStack Gateway Bridge on port 1700/udp.

Eclipse Mosquitto (Gateway)

Mosquitto is an MQTT message broker, meaning you can publish your own messages as well as subscribe to messages sent by others. In case of the gateway, the ChirpStack Gateway Bridge publishes the forwarded LoRaWAN data to the Mosquitto server. Various other services read/write data from to the Mosquitto server, while modifying the data. The next service in line in the logical processing chain is ChirpStack.

ChirpStack Gateway Bridge

The ChirpStack Gateway Bridge converts LoRa Packet Forwarder protocols in a common data format. It receives the data from the Packet Forwarder, converts it and publishes it to the Mosquitto for the ChirpStack.

ChirpStack

ChirpStack handles parts of the LoRaWAN communication like the authentication as well as provides a device inventory as well as a web interface for displaying LoRaWAN connections, data and for configuration. It persists data in a PostgreSQL database and uses Redis as a session store and for non-persistent data. It receives and publishes data via Mosquitto.

Example

PostgreSQL

PostgreSQL is an object-relational database and by the ChirpStack for storing persistent data.

Redis (Gateway)

Redis is an in-memory data store and is used for storing session and non-persistent data by the ChirpStack.

Converter

The Converter is a self-provided Python3 application, which listens for the device data published by the ChirpStack Gateway Bridge via MQTT message on the Mosquitto. It decompresses the data, undoes the key substitution and reformats the data. Afterwards, the data is published back to the Mosquitto server.

Device Manager

The Device Manager is a self-provided Python3 application keeping track of the seen devices via the Redis server. It publishes MQTT messages on the Mosquitto server for device discovery events and status (data) updates. These messages are picked up by the HA Integration service.

HA Integration

The HA Integration is a self-provided Python3 application. It translates the MQTT messages sent by the Device Manager into messages understood by the MQTT integration of the Home Assistant.

Home Assistant

Our Home Assitant is a preconfigured version of the official Home Assistant, a home automation web interface, and is used to diplay the devices and sensor data. It subscribes to MQTT messages via Mosquitto.

Example