Changelog

If using the Semtech UDP Packet Forwarder backend, it is possible to expose additional key / value metadata using an optional meta key in either the rxpk or stat package. The value of meta must be an object with key (string) / value (string) data if present.

Improvements

Update Go compiler to v1.19.3.
Update Alpine base container to v3.17.0.
Update prometheus/client_golang to v1.14.0.
Make metadata field in chirpstack_api consistent.

v4.0.1

Improvements

Expose ack-rate (Semtech UDP protocol) through Prometheus metrics.
Update Go compiler toolchain to latest version.

Bugfixes

Update Multitech Conduit packaging to work Monit for process monitoring (included in latest mPower).

v4.0.0

Features

This release implements the ChirpStack v4 API interface. Please note that this version is not compatible with ChirpStack v3.

v3.14.3

Bugfixes

Fix incorrect handling of MQTT token timeout, causing re-connect to not work in some cases. (#210)

v3.14.2

Bugfixes

Basics Station: Prefer gpstime over rxtime in case both are available.

v3.14.1

Improvements

Update dependencies.
Update to Go 1.18.

v3.14.0

Features

Add support for periodic time-sync requests (Basics Station).

Improvements

Make it possible to use 32bit downlink tokens instead of 16bit only (will be used by ChirpStack v4).

v3.13.3

Improvements

Update MQTT client to latest version.
Add timeout to MQTT token wait.
Basics Station backend:
- Add WORKAROUND_IGNORE_RX_TIME flag (environment variable) to disable the parsing of rxtime in cases where the gateway does not provide a correct rxtime value.

v3.13.2

Improvements

Expose SX1302 / SX1303 ftime as plain fine-timestamp if available.
Consolidate Tektelic .ipk packages to single kona architecture.

v3.13.1

Bugfixes

Fix stats Hz to kHz conversion for Concentratord backend.

v3.13.0

Features

Gateway metrics

This implements the aggregation of additional gateway metrics:

Uplink & downlink count split by frequency
Uplink & downlink count split by modulation parameters
Downlink (attempts) split by status

Improvements

Docker images added for ARM v6, v7 and ARM64. (#198)

Bugfixes

Correct the command_url logged. (#197)

v3.12.0

Features

Implement LR-FHSS modulation type.

Improvements

Make Kerlink .ipk packaging generic for all KerOS models.

Bugfixes

Fix null time when GPS is not available in gateway (Basics Station). (#196)

v3.11.0

Features

Connection state messages

This publishes a conn state message, indicating if a gateway is online or offline. State messages are published as retained so that a MQTT client will immediately receive the latest state of the gateway(s) after subscribing to the conn state MQTT topic. The default MQTT topic for state messages is gateway/ID/state/STATE where ID is the ID of the gateway and STATE is the state (in this case conn). This topic is configurable in the Configuration.

Improvements

When terminate_on_connect_error is enabled, terminate on connection lost. (#184)
Do not run as root (Docker). (#185)
Add ns precision to log output timestamp.

Bugfixes

Add websocket connection mutex to avoid concurrent writes. (#191)

v3.10.0

Features

Basic Station timesync request/response support. (#179)

Improvements

Refactor backend <> integration communication code.
Refactor the way how MQTT (un)subscribe is implemented.
Make MQTT keepalive interval configurable. (#176)
Add new Azure CA certificates. (#178)
Implement paho mqtt client logging. (#182)

v3.9.2

Improvements

Provide uplink / downlink stats when using the BasicStation backend.

v3.9.1

Bugfixes

Downlinks are now visible in the web-interface when using in combination with the BasicStation.
RX2 parameters are now set for Class-A downlinks when using in combination with the BasicStation.

v3.9.0

Features

Multi-downlink commands and ACKs

This multi-downlink feature allows a Network Server to send multiple downlink opportunities at once, e.g. one item for RX1 and one for RX2. The gateway will send at most one downlink item from the list. The ChirpStack Gateway Bridge will respond with a list of ACK items, indicating which item item was emitted, which item(s) failed and which item(s) were ignored (because the previous item was emitted).

Channel re-configuration

This implements channel re-configuration for the ChirpStack Concentratord backend over MQTT. This also removes the channel re-configuration for the Semtech UDP Packet Forwarder. While this feature had been removed from the documentation code references were still present. As there are different implementations of the Semtech UDP Packet Forwarder, there are also different flavors of configuration files.

The ChirpStack Concentratord provides a unified API to different types of gateways which makes it possible to implement channel re-configuration for this backend.

Kerlink iStation

This release provides IPK packages that can be installed on a Kerlink iStation gateway.

Improvements

Split multi-line meta-data returned by a command only once on delimiter.
Forward meta-data provided by a Packet Forwarder backend.

v3.8.0

Features

Multi-line meta-data commands

This makes it possible to let a meta-data command return multiple lines of values. In case of multi-line output, ChirpStack Gateway Bridge will split each line by a configured delimiter to obtain the key / value pairs.

Bugfixes

Fix race condition in Semtech UDP Packet Forwarder backend. (#162)

v3.7.1

Bugfixes

Fix duplicated configuration in the Tektelic config example.
Fix / improve ZMQ socket re-connect for Concentratord backend.

v3.7.0

Features

Concentratord backend

The Concentratord backend is compatible with the ChirpStack Concentratord daemon. Please note that this backend is experimental.

Syslog output

When log_to_syslog is enabled in the configuration file, the log output will be written to syslog.

Improvements

Change MQTT max. reconnect interval default value to 1 minute.
Refactor MQTT subscribe / unsubscribe logic.

Bugfixes

Use DevEUI object length instead of JoinEUI. (#154)
Remove default values for BasicStation filters. (#157)
Fix BasicStation websocket ping loop. (#156)

v3.6.0

Features

Raw packet-forwarder events / commands

Using the raw packet-forwarder events and commands, it is possible to use the BasicStation Remote Command and BasicStation Remote Shell features.

Terminate on connect error

The terminate_on_connect_error will terminate the ChirpStack Gateway Bridge process when it can't connect to the MQTT broker. In some cases this is preferred over the retry loop.

Improvements

FSK FDev

Before the frequency deviation was always set to the FSK datarate / 2. It is now possible to set it manually (falling back on datarate / 2 when unset).

v3.5.0

Features

MIPS builds

This is the first release providing binaries compiled for MIPS. These binaries are compiled with GOMIPS=softfloat and are compressed with upx as MIPS based gateways have usually limited storage space available. (#65)

RPM packaging

This is the first release providing .rpm packages for CentOS and RedHat. (#145)

Improvements

Environment variable configuration

The usage of . in environment variables for configuration has been deprecated (it will continue to work, but will log a warning). Instead of ., use a double underscore (__). (#144)

Multiple MQTT servers

This release adds support for the configuration of multiple MQTT servers. (#141)

v3.4.1

Bugfixes

Fixes init stop script which could cause the ChirpStack Gateway Bridge to not properly stop or restart.

v3.4.0

This release renames LoRa Gateway Bridge to ChirpStack Gateway Bridge. See the Rename Announcement for more information.

Bugfixes

Fix nested read lock. (#139)

v3.3.0

Features

Message IDs

This release implements unique message IDs (both for events and commands) that can be used for correlation or logging purposes.

BasicStation channel-plan configuration

To make it easier to work with the BasicStation Packet Forwarder, this release makes it possible to configure the channel-plan inside the LoRa Gateway Bridge configuration file. It is no longer needed to configure a Gateway Profile within LoRa App Server. This means that it is also possible to use the LoRa Gateway Bridge with BasicStation gateways, without the need of installing LoRa Server and LoRa App Server.

v3.2.1

Bugfixes

Fix NetID 3 & 4 filter according to the errata published by the LoRa Alliance.
Fix Basic Station bandwidth for LoRa Std channel (from kHz to Hz). (#130)

v3.2.0

Features

NetID and JoinEUI filters

Configuration options have been implemented to filter uplink messages on netID and JoinEUI. This makes it possible to ignore messages from neighboring to save on bandwidth usage (e.g. when the gateway is using a cellular backhaul).

Execute commands

This feature makes it possible to execute commands on the gateway (when the LoRa Gateway Bridge is running on the gateway). Note: commands must be pre-configured in the LoRa Gateway Bridge configuration file.

Improvements

Basic Station backend

Verify Common Name when using client certificates. (#129)

v3.1.0

Features

Azure IoT Hub X.509

X.509 certificate authentication is added to the azure_iot_hub MQTT authentication option.

Improvements

Prometheus metrics

The Prometheus metrics have been improved for consistency. Documentation has been updated to document the metrics that are available.

Max reconnect interval

The MQTT max. reconnect interval is now a global MQTT configuration and can be used regardless of the MQTT authentication type.

Lat / lon / alt = 0

When the latitude, longitude and altitude are all three 0, then LoRa Gateway Bridge assumes there is no GPS module / location available and it will not expose a location in the stats message.

Bugfixes

The CRC check has been fixed for the Semtech UDP backend.
Fix message buffering for QoS > 0 (on manual reconnect, the Paho library discards messages when offline).

Deprecated

Managed gateway configuration

Documentation (and configuration) references to the managed packet-forwarder configuration have been removed. The feature itself is still available and will stay available until the next major release. Please refer to this forum discussion for more background.

v3.0.1

Bugfixes

Fix acquiring double read-lock (which could result in a deadlock). #119

v3.0.0

Features

Basic Station packet-forwarder support

The LoRa Gateway Bridge has been refactored to support multiple packet-forwarder backends. Next to the Semtech UDP packet-forwarder, support has been added to support the Basic Station packet-forwarder. This backend implements the Basic Station LNS protocol.

Updated payload formats

The uplink payload contains a context field, used to store gateway specific context data (like the internal counter).

The downlink frame contains a timing field which can be either IMMEDIATELY, DELAY or GPS_EPOCH. Based on the timing value, an additional object must be given with the additional timing information. Refer to Commands for more details.

Azure IoT Hub integration

LoRa Gateway Bridge now has support to connect the Azure IoT Hub MQTT interface. Like with the Google Cloud Platform IoT Core integration this makes it easier to scale up and manage gateway credentials using the IoT Hub console (or API).

Fake RX time

In case the gateway does not have a GPS module, the RX time would would be left blank. This feature makes it possible to use the system time as a fallback. (#109)

Custom gateway meta-data

This feature makes it possible to expose additional meta-data in the gateway stats. Meta-data can either be static or dynamic (executing external commands). The latter option allows to for example read and expose the gateway temperature, humidity, ...

Upgrading

LoRa Gateway Bridge v3.0.0 include a couple of changes that are not backwards compatible. You need to re-generate the configuration file and update it where needed. LoRa Gateway Bridge v3 is compatible with LoRa Server v2.7+. Below a summary:

MQTT topics

The MQTT topic configuration has been updated from:


uplink_topic_template="gateway/{{ .MAC }}/rx"
downlink_topic_template="gateway/{{ .MAC }}/tx"
stats_topic_template="gateway/{{ .MAC }}/stats"
ack_topic_template="gateway/{{ .MAC }}/ack"
config_topic_template="gateway/{{ .MAC }}/config"

To:


event_topic_template="gateway/{{ .GatewayID }}/event/{{ .EventType }}"
command_topic_template="gateway/{{ .GatewayID }}/command/#"

Event types are: up, stats and ack. Commands are: down and config.

Please note that LoRa Gateway Bridge v3 is compatible with LoRa Server v2.7+, but you will need to update the MQTT topics in your loraserver.toml file. Example snippet:


uplink_topic_template="gateway/+/event/up"
stats_topic_template="gateway/+/event/stats"
ack_topic_template="gateway/+/event/ack"
downlink_topic_template="gateway/{{ .MAC }}/command/down"
config_topic_template="gateway/{{ .MAC }}/command/config"

Backends

With LoRa Gateway Bridge v2 you would configure the MQTT backend under the [backend...] section. This has changed and the [backend...] section is now used for selecting and configuring the packet-forwarder backends.

Integrations

The MQTT integration configuration has moved to the new [integration...] section. This allows for adding new integrations in the future besides MQTT.

Prometheus metrics

The Prometheus metrics have been updated / cleaned up.

v2.7.1

Bugfixes

Fix rxpk.brd parsing for some packet-forwarders. (#104)

v2.7.0

Features

Environment variable based configuration has been re-implemented.

Improvements

Remove QoS > 0 bottleneck with non-blocking MQTT publish (#101)

Bugfixes

Fix potential deadlock on MQTT re-connect (#103)
Fix logrotate issue (init based systems) (#98)

v2.6.2

Bugfixes

Fix QoS backend setting regression. #95

v2.6.1

Bugfixes

Fix corrupted gateway statistics for downlink packets. #94

v2.6.0

Features

Google Cloud Platform integration

LoRa Gateway Bridge is able to integrate with Cloud IoT Core. This makes it easier to scale up, but also makes it possible to manage gateway authentication using the web-based Cloud IoT console (or APIs).

Gateway IP address

The gateway IP address is exposed through the gateway stats.

v2.5.1

Bugfixes

Fix configuration parse error (some keys were not loaded because of configuration alias).

v2.5.0

Upgrade notes

When using the v2_json marshaler (default), this version is fully compatible with previous versions of LoRa Server. When changing the marshaler to protobuf or json, you first need to upgrade to LoRa Server v2.1.0. When LoRa Server v2.1.0 is installed, it is recommended to use either the protobuf or json marshaler as it provides better compatibility (e.g. with the iBTS gateway).

Features

Protocol Buffer data serialization

To save on bandwith between the gateway and the MQTT broker (e.g. when the gateway uses a cellular connection), this update makes it possible to configure the marshaler for encoding / decoding the data (in chirpstack-gateway-bridge.toml) using Protocol Buffers.

This will become the default option in LoRa Gateway Bridge v3.

Only log in case of UDP read / write errors (instead of breaking out of loop).

2.4.0

Features:

LoRa Gateway Bridge can now manage the packet-forwarder configuration (channels). See Send / receive data for more information.

2.3.2

Improvements:

Expose the following MQTT options for the MQTT gateway backend:
- QoS (quality of service)
- Client ID
- Clean session on connect

Bugfixes:

Use topic from configuration file on re-connect (this was still hardcoded).

2.3.1

Improvements:

MQTT topics are now configurable through the configuration file. See Configuration.

2.3.0

Features:

LoRa Gateway Bridge uses a new configuration file format. See configuration for more information.
Support MQTT client certificate authentication (#74).

Upgrade notes:

When upgrading using the .deb package / using apt or apt-get, your configuration will be automatically migrated for you. In any other case, please see configuration.

2.2.0

Features:

LoRa Gateway Bridge now publishes TX acknowledgement messages over MQTT. See MQTT topics.
TX (GPS) timeSinceGPSEpoch field is now exposed to transmit at given time since GPS epoch (1980-01-06, only possible when the gateway has a GPS time source).
RX (GPS) timeSinceGPSEpoch field is now exposed, containing the time since GPS epoch (1980-01-06, only available when the gateway has a GPS time source).

Bugfixes:

Without GPS time source, the gateway would use 0001-01-01T00:00:00Z as RX time. The time field is now omitted when unavailable.

2.1.6

Features:

Add Kerlink iBTS compatibility (multi antenna and multi board).

2.1.5

Improvements:

--mqtt-ca-cert / MQTT_CA_CERT configuration flag was added to specify an optional CA certificate (thanks @minggi).

Bugfixes:

MQTT client library update which fixes an issue where during a failed re-connect the protocol version would be downgraded (paho.mqtt.golang#116).

2.1.4

Retry connecting to MQTT broker on startup (thanks @jcampanell-cablelabs).
Make latitude, longitude and altitude optional as this data is not always provided by the packet_forwarder and would else incorrectly be set to 0.

2.1.3

Provide TXPacketsReceived and TXPacketsEmitted in stats.
Implement --skip-crc-check / SKIP_CRC_CHECK config flag to disable CRC checks by LoRa Gateway Bridge.