This feature makes it possible to implement end-to-end encryption between the
end-device and end-application. On OTAA join, the join-server will provide
Chirpstack with the encrypted
AppSKey, which will be forwarded on every
uplink to the end-application (integration events). The end-application then
first decrypts the
AppSKey with the KEK key shared between the JS and
end-application, and then uses the decrypted
AppSKey to decrypt the
On enqueue downlink, the end-application encrypts the application payload
before enqueue. As well, it must set the
such that ChirpStack knows that the payload is already encrypted and which
downlink frame-counter was used during the encryption of the payload.
Note: This feature requires an external join-server.
chirpstack_integration crate can be used to build external integrations
using the Redis Streams that are exposed by ChirpStack. An example implementation
is the ChirpStack Pulsar Integration.
This adds tags (like already can be found on device-profiles and devices) to tenants and applications. Note that the integration events will contain the aggregation of application + device-profile + device tags. Integration events will not contain the tenant tags.
This makes it possible to configure a JoinEUI prefix when configuring a join-server, to forward a range of JoinEUI to a single join-server without the need to add multiple join-server configuration blocks. As well, this makes it possible to configure a 'catch-all' join-server, using a JoinEUI prefix that would match all JoinEUIs.
This moves some of the API:
If you are using these messages in your application, then you might need to update the import paths when updating the API SDK.
As well, this adds a new Redis Stream exposing the Backend Interfaces requests and responses (Passive Roaming + Join Server).
This makes it possible to select which devices are allowed to use roaming
and which devices not. This option can be configured in the device-profile.
On migration this value will be set to
true (as all devices could use
roaming before this version).
Some OpenID Connect providers do not provide an
email_verified value. By
true, ChirpStack will assume that
the e-mail address has been verified. (#302)
skip_f_cntand device variables to ADR plugins.
- Reset uplink ADR history table in case of DR / TxPower / NbTrans change.
- Do not fail in case of corrupted mac-commands.
- Use region default RX2 frequency if device-session RX2 frequency == 0.
- Make it explicit that TX Power is in EIRP + update region configuration from ERP to EIRP.
- Refactor device-lock /
- Ignore unknown JSON fields when decoding JSON to API structures in Rust.
ns_timeto the gateway rx-info struct.
- Speed up API authorization validation queries (SQL).
- Improve log output (better log messages + adding better correlation identifiers to each message).
LoraModulationInfo(this is not used by ChirpStack, but it can be used by applications directly interacting with the gateway).
nullfields in Backend Interfaces JSON output. (#316)
- Reduce dependencies for AWS SNS integration by replacing
aws-sign-v4+ REST call.
- Make device metric name optional. (#313)
- Get all device-data in a single query to improve performance.
false(please v3 to v4 migration guide).
- Debian package: Fix
postinstto only run on install. (#295)
- Fix setting initial tags in tenant form (UI).
- Use unbounded MQTT client channels / fix dropping MQTT messages under high load.
- Add misspelled
ResultCodein Backend Interfaces (this is a typo in the specifications). (#317)
- Reload device on change event. (#319)
- Fix sending empty downlink to Relay in case uplink
ADRACKReqbit was set.
- Return error in ThingsBoard integration if
ThingsBoardAccessTokenis not set. (#277)
- Show notification in UI for form validation errors. (#282)
- Log OTAA join-requests of unknown devices as warning instead of error.
- Fix AS923 max-payload size table. (#283)
- Fix doughnut chart resizing in UI. ([https://github.com/chirpstack/chirpstack/issues/284])
While this refactor does not add additional features to the UI, it does eliminate some unnecessary reloading of data due to better route handling. This should result in less flickering when navigating between some of the UI pages.
- Make it possible to use
DeviceModeIndfor LoRaWAN 1.0.x devices (this is not according the LoRaWAN 1.0.x specs).
- Implement removing device from Relay filter list.
rediss://connection string example to config template (for TLS). (#219)
- Update internal dependencies.
- Fix showing initial InfluxDB integration form. (#254)
- Fix ADR plugin variable mapping typo (
- Fix setting empty username / password in MQTT. (#257)
- Fix RPM install error caused by auto dependencies. (#267)
- Wait for first uplink before scheduling Class-C downlink.
- Do not disable device activation fields in UI (making it impossible to read & copy session-keys).
create-api-keysub-command to create API keys using the CLI.
- Update internal dependencies.
- Fix sending multiple
- Update internal dependencies.
- Add support for JSON log output.
- Fix sending channel-mask twice (CFList + LinkADRReq) for US915-like regions.
This adds support for the Relay specification (TS011). In the Device Profile it is possible to configure the Relay and Relay capable end-device parameters. Under the Application view it is possible to assign devices to a Relay (required for filtering and exchanging the device list with the Relay).
Note: Please note that this requires a Relay and Relay capable end-device.
The build configuration has been updated to generate fully static binaries based on musl libc. This solves the issue where in some cases ChirpStack would not connect over TLS to a PostgreSQL database. (#156).
This also changes the Docker base image to
alpine, reducing the Docker image
size by ~ 50% compared to
debian:buster-slim. Within the
Dockerfile we now
COPY the already compiled binaries, which also reduces the build time on
If you are compiling ChirpStack from source, please refer to the
in the source repository as some commands have changed.
Configuration has been added to configure the prefix of the event name and to send arbitrary JSON payloads instead of the 3 value payload.
lrwn_filterscrate for filtering LoRaWAN PHYPayloads.
- Dependencies have been updated.
- Expose enabled device-class in API and integration event output. (#58)
panicin case of invalid DevAddr prefix type.
- Fix missing device
- Fix incorrect config template key for
- Fix default
CN470Class-B ping-slot frequencies.
- Fix using system CA certificates for TLS. (#204)
- Fix OTAA join-request MIC check and DevNonce validation order.
This add a configuration option, to enable / disable compatibility with the
latest ChirpStack Gateway Bridge v3 version. If compatibility is not needed,
v4_migrate=false to the
[regions.gateway.backend.mqtt] section (in
region_...toml). This will
save some bandwidth in the GW <> NS communication. The current default is
true, in ChirpStack v4.4+, the default will change to
false (and thus
it must be explicitly enabled).
- Add back web-interface option to download events and frames as JSON.
- Update internal dependencies.
- Fix sending to multiple URLs in case one endpoint fails.
- Enable new
redisdependency (fixes Redis TLS issues). (#170)
This adds a Forward messages on these FPorts to LoRa Cloud configuration option, which based on FPort, let LoRa Cloud Modem & Geolocation Services automatically handle the payload according.
This also adds a toggle button to make using the reported gateway location optional for geolocation assistance.
This improves the SDK
features, to make it easier to exclude certain
dependencies by disabling features in
Internal dependencies have been updated to the latest versions.
This adds support for generating C# API code. (#100)
This makes it possible to explicitly define which gateways will be used for a given multicast-group. In the gateways overview it is possible to select one or multiple gateways and then add these gateways to a multicast-group.
This moves the multicast scheduling configuration to the multicast-group
configuration from the
chirpstack.toml configuration file. Scheduling
options include scheduling based on GPS time or delay based.
This makes it possible to define per tenant if and how gateways can be used by other tenants. For example in case downlink is set to private, other tenants will benefit from uplinks received by these gateways, but they will not be able to send downlinks (ChirpStack will filter these gateways out when selecting the gateway for scheduling the downlink).
- Update internal dependencies.
- Add missing
fPortvalidation to avoid enqueue on
- Do not overwrite
locationfield with gateway location if it is already set.
- Do not log stats handling
- Decode FRMPayload mac-commands in device LoRaWAN frames log.
FCntin device event log.
/api/multicast-groups/...typo in enqueue API URL.
gateway_idis missing errors (in case the uplink was also received by an unknown gateway).
- Fix disabling mac-commands.
- Fix region configuration defaults + use region
idas fallback for
descriptionif the latter is missing. (#120)
- Fix API authorization for listing ADR algorithms. (#112)
- Fix US915 downlink channel
- Fix incorrect rendering of
.ca_certin config template. (#124)
tls_enabledconfig option as it is not actually implemented. (#128)
This adds a Region configuration option to the device-profile, which lists the region configurations for the selected Region. If a region configuration is selected, then the device will only be able to work under the selected configuration. If no region configuration is selected, then the device will be able to operate under all available region configurations for the selected region.
This adds support for Java and Kotlin API SDK code generation. (#64)
descriptionconfiguration option per region configuration.
idwithin the region configuration (
namewill be used as fallback option).
- Make gateway state in UI consistent and make expected stats interval configurable. (#76)
- Add Python type information to Python API SDK code. (#68)
- Add back
UplinkRxInfomessage (the status will be reported as no CRC until the ChirpStack Gateway Bridge, ChirpStack Concentratord and / or ChirpStack MQTT Forwarder have been updated).
- Add back Class-B ping-slot parameters to the device-profile.
- Update Class-B ping-slot data-rate configuration in examples.
- Remove separate gateway topic config and move it into single
- Reset internally stored channels to default on
ADRACKRequplink to avoid out-of-sync channel configuration on device.
- Update internal dependencies.
- Fix hiding Delete device option if the user has no permissions to perform this action. (#71)
- Fix not recording device metrics if auto-detect of measurements is disabled. (#94)
- Fix Redis
key_prefixconfiguration. While this value could be configured, it was not applied to the generated keys.
- Fix header
z-indexissue in UI. This was causing the dropdowns to render partly behind the header.
- Do not wait for integrations to finish before sending downlink.
- Update JS API dependencies to latest versions.
- Replace relative paths in Rust API build to absolute. (#69)
- Fix setting the full frame-counter to the uplink frame after resolving the device-session (this can affect payload decryption).
This feature logs API requests to Redis Streams. This enables external services to monitor for example device create, update and deletes by reading from the Redis Streams. A code-example can be found here.
While the feature to log frames was already present, it was not possible
to only read uplink frames of devices that are unknown. This extends the frame
logging feature to also log uplinks for unknown devices, in which case DevEUI
0000000000000000 is used. A code-example for reading the frame log can be
A code-example to read event logs from the Redis Streams was added. It can be found here.
metadatafields in gateway messages consistent.
- Emit all fields for JSON integration messages, even if they are their default values. (#63)
- Fix Redis pipelined commands in case Redis Cluster is configured.
- Fix UI notifications z-index.
import-ttn-lorawan-devicessub-command has been renamed to
keep_alive_intervalfor MQTT configuration.
- Fix incorrect splitting of multiple URLs in HTTP integration. (#62)
- Fix missing ThingsBoard location and status telemetry.
- Send ThingsBoard telemetry (fPort, fCnt, ...) even in case there is no decoded payload.
- Fix LeafletJS controls floating over header (UI).
- Fix coding-rate for LoRaWAN 2.4GHz. (#51)
- Fix not removing of queue-item after it was sent, if payload did not fit RX2.
- Add code example for reading frame-logs from Redis Streams.
- Add missing metadata logging and add code example for reading metadata from Redis Streams.
- Make it possible to enable / disable auto-detection of metrics in device-profile. (#42)
- Add Redis config examples for username and password configuration. (#54)
- Add metadata tab to gateway configuration in UI.
ca_pathfor MQTT integration. (#47)
- Fix Cannot serialize NaN as google.protobuf.Value.number_value error.
- Fix logout URL in case OIDC is enabled.
- Fix closing and detecting if eventlog channel is closed.
- Fix metrics interval calculation on daily aggregate in case of DST to non-DST timezone change.
- A new menu option Regions was added to the web-interface, exposing per region information.
- Internal dependencies were updated.
- Fix Wi-Fi geolocation issue in LoRa Cloud integration.
- Fix missing per data-rate stats in gateway dashboard.
- Fix terminating stream loop (and releasing of Redis connection) on client disconnect. (#40)
- Fix rendering
client_cert_lifetimerendering in configuration template (mqtt integration).
After many months of development and testing, we are really excited to share ChirpStack v4.
The aim of ChirpStack v4 is to make it significantly easier to setup and use ChirpStack, compared to the previous version. One of the major changes that you will notice is that the ChirpStack Network Server and ChirpStack Application Server have been merged into a single component. Over the years we have seen many issues reported on the forum and GitHub, related to setting up and connecting both services. ChirpStack v4 also provides multi-region support out-of-the-box, including region configuration. No longer it is needed to define your own configuration file or setup multiple ChirpStack Network Server instances to serve multiple regions simultaneously.
A big thank you to the ChirpStack community for supporting and contributing to the ChirpStack project! Please find below a breakdown of all the new features and changes that v4 brings.
ChirpStack v4 adds multi-region support, removing the need to setup multiple ChirpStack Network Server instances. Configuration files are included for the common regions (as defined by the LoRa Alliance), which should help getting started with ChirpStack.
Each enabled region has its own gateway backend, making it possible to use one
or multiple MQTT brokers for the different gateway pools. In case a single
MQTT broker is used, each backend must be configured with its own MQTT topic prefix
ChirpStack v4 also supports multiple configurations of the same region, e.g. to configure a US915 for 8 channels and to configure a US915 band for 16 channels.
ChirpStack v4 adds support for importing the TTN LoRaWAN Devices repository as device-profile templates, including codec functions if these are defined in this repository.
In the device-profile template and / or device-profile, it is possible to define the measurements that are exposed by the device in the decoded payload. Once defined, ChirpStack will automatically aggregate and store this data. These metrics can be viewed in the web-interface on the device dashboard.
Instead of using a single configuration file (e.g.
ChirpStack makes use of a configuration directory such that the configuration
can be split in multiple files. By default you will find a single
configuration file, and many
region_...toml configuration files, split
ChirpStack v4 removes the TOML hierarchy to environment variable mapping.
Instead it allows you to define the variables like
will get automatically substituted when an environment variable is found with
The REST interface that was present in ChirpStack Application Server v3 has
been removed, in favor of the gRPC API interface (please see the
of the repository for the API definitions). However, a gRPC to REST interface
bridge component will be provided as a separate service. Please note that
in v3, this bridge component was embedded and REST interface calls were
internally translated to gRPC calls. Therefore, gRPC was always recommended
interface to use.
ChirpStack v4 is fully compatibility with the latest version of ChirpStack
Gateway Bridge v3. This should help migrating from v3 to v4. Please note that
the ChirpStack Gateway Bridge must be configured with the
ChirpStack v4 contains a rewrite of the ChirpStack Application Server v3 UI. The new UI aims to be more user-friendly. Under the hood the API interface has been ported to gRPC-web and all code has been ported to Typescript.
The implementation of Passive Roaming has been improved, adding support for
/fns server endpoint suffixes. The usage of this
suffix is not specified in the Backend Interfaces specification, but is
required by some other network-server implementations.
All identifiers that are exposed have been changed to UUID. Previously most
identifiers (e.g. users, applications...) were incremental integers. In case
ChirpStack is setup as multi-tenant instance, this could expose some information
about the number of clients on the network. The migration script (see below)
will migrate these integers by converting these as strings, prefixed with
zeros in the UUID format. E.g. ID
123 would be converted to the UUID string
All binary identifiers have been changed to string type in the API. While
binary fields are more efficient, these were confusing when encoded as JSON
as the Protobuf to JSON mapping uses base64 encoding for binary fields.
For example, a Gateway ID
0102030405060708 was encoded as
While the structure of API messages is roughly the same as the ChirpStack Application Server API interface, some small changes have been made.
The integration event messages have been restructured for better consistency.
Each event message has a
deviceInfo field which holds device-related
information (tenant id & name, application id & name, device-profile id &
name, device EUI & name and tags).
ChirpStack v4 will make it a lot easier to make customizations, especially when API changes are involved, as API definitions are no longer separated from the code. In v3 these definitions were moved to an external repository to avoid cross dependencies.
For ChirpStack v4, it was decided to use Rust rather than Go. This was not an easy choice and the arguments for this decision are debatable. However, as most code was touched during the ChirpStack Application Server and ChirpStack Network Server merge, it was the only moment to re-consider this. The Rust memory management prevents many memory related pitfalls and helps catching bugs at compile time rather than runtime.
The recommended way to migrate from v3 to ChirpStack v4 is to create a new PostgreSQL and Redis database and to use the ChirpStack v3 to v4 migration script. This script will copy all the data from the "old" into the "new" database. While the script does not make any modifications to the old database, it is always recommended to make a backup first.