├── src ├── guides │ ├── index.md │ ├── device-metrics.png │ ├── node-red-echo-flow.png │ └── pilot-things.md ├── chirpstack │ ├── api │ │ ├── index.md │ │ ├── js-examples.md │ │ ├── go-examples.md │ │ ├── csharp-examples.md │ │ ├── python-examples.md │ │ ├── rest.md │ │ └── grpc.md │ ├── use │ │ ├── index.md │ │ ├── event-log.md │ │ ├── applications.md │ │ ├── users.md │ │ ├── login.md │ │ ├── multicast-groups.md │ │ ├── frame-log.md │ │ ├── gateways.md │ │ ├── tenants.md │ │ └── device-profile-templates.md │ ├── backends │ │ ├── index.md │ │ ├── amqp.md │ │ ├── gcp-pub-sub.md │ │ ├── azure-iot-hub.md │ │ └── mqtt.md │ ├── features │ │ ├── index.md │ │ ├── geolocation.md │ │ ├── device-metrics.md │ │ ├── device-time.md │ │ ├── multicast.md │ │ ├── rx-parameters-configuration.md │ │ ├── device-status.md │ │ ├── rejoin.md │ │ ├── gateway-management.md │ │ ├── device-activation.md │ │ ├── channel-configuration.md │ │ ├── multi-region.md │ │ ├── join-server.md │ │ ├── frame-logging.md │ │ ├── adaptive-data-rate.md │ │ └── device-classes.md │ ├── index.md │ ├── integrations │ │ ├── index.md │ │ ├── mydevices.md │ │ ├── pilot-things.md │ │ ├── amqp.md │ │ ├── azure-service-bus.md │ │ ├── aws-sns.md │ │ ├── gcp-pub-sub.md │ │ ├── http.md │ │ ├── chirpstack-pulsar-integration.toml │ │ ├── ifttt.md │ │ ├── postgresql.md │ │ ├── building-new-integrations.md │ │ ├── thingsboard.md │ │ └── mqtt.md │ ├── streams │ │ ├── index.md │ │ ├── metadata.md │ │ ├── api-requests.md │ │ ├── events.md │ │ ├── backend-interfaces.md │ │ └── frames.md │ └── contribute.md ├── chirpstack-gateway-os │ ├── use │ │ ├── index.md │ │ ├── log-files.md │ │ ├── subscribe-to-mqtt.md │ │ ├── software-update.md │ │ ├── node-red.md │ │ ├── modifying-files.md │ │ └── configuration.md │ ├── applications.png │ ├── gateway-config.png │ ├── install │ │ ├── index.md │ │ ├── dragino.md │ │ └── seeed.md │ ├── downloads.md │ ├── index.md │ ├── image-types.md │ ├── contribute.md │ └── hardware-support.md ├── chirpstack-concentratord │ ├── api │ │ ├── index.md │ │ ├── events.md │ │ └── commands.md │ ├── installation │ │ ├── index.md │ │ ├── wifx.md │ │ └── kerlink.md │ ├── contribute.md │ ├── downloads.md │ ├── index.md │ └── chirpstack-concentratord-2g4.toml ├── chirpstack-gateway-bridge │ ├── backends │ │ ├── index.md │ │ ├── concentratord.md │ │ ├── semtech-udp.md │ │ └── basics-station.md │ ├── integrations │ │ ├── index.md │ │ ├── mqtt.md │ │ └── azure-iot-hub.md │ ├── payloads │ │ ├── index.md │ │ └── states.md │ ├── install │ │ ├── wifx-lorix-os-chirpstack-gateway-bridge.png │ │ ├── dragino.md │ │ ├── kerlink.md │ │ ├── multitech.md │ │ ├── tektelic.md │ │ ├── debian-ubuntu.md │ │ ├── wifx.md │ │ ├── index.md │ │ └── raspberry-pi.md │ ├── index.md │ ├── metrics.md │ ├── contribute.md │ └── configuration.md ├── chirpstack-gateway-mesh │ ├── install │ │ ├── index.md │ │ ├── rak.md │ │ └── raspberry-pi.md │ ├── protocol │ │ ├── index.md │ │ ├── tlv-payloads.md │ │ ├── stored-context.md │ │ ├── events.md │ │ ├── commands.md │ │ ├── uplink.md │ │ └── downlink.md │ ├── downloads.md │ ├── configuration.md │ ├── contribute.md │ ├── changelog.md │ ├── comparison.md │ └── events.md ├── sponsors │ ├── f3.png │ ├── rak.png │ ├── acklio.png │ ├── afnic.jpg │ ├── browan.png │ ├── pollex.png │ ├── reese.jpg │ ├── skiply.png │ ├── twtg.png │ ├── wifx.png │ ├── dragino.png │ ├── kerlink.png │ ├── miitors.png │ ├── cablelabs.png │ ├── milesight.png │ ├── my_devices.png │ ├── project_q.png │ ├── sidn_fonds.png │ ├── smartparks.png │ ├── thingstream.png │ └── objectspectrum.png ├── gateway-configuration │ ├── rak.md │ ├── tektelic.md │ ├── kerkink.md │ ├── multitech.md │ ├── dragino.md │ ├── matchx.md │ └── laird.md ├── chirpstack-mqtt-forwarder │ ├── install │ │ ├── index.md │ │ ├── tektelic.md │ │ └── rak.md │ ├── contribute.md │ ├── configuration.md │ ├── downloads.md │ └── index.md ├── context.json ├── v3-documentation.md ├── getting-started │ ├── raspberry-pi.md │ └── ansible-vagrant.md ├── index.md └── sponsors.md ├── .gitignore ├── .github └── FUNDING.yml ├── theme ├── favicon.png ├── img │ └── logo.png ├── head.hbs ├── header.hbs └── css │ └── chirpstack.css ├── landing ├── img │ ├── logo.png │ ├── chirpstack.png │ └── sponsors │ │ ├── f3.png │ │ ├── rak.png │ │ ├── afnic.jpg │ │ ├── reese.jpg │ │ ├── twtg.png │ │ ├── wifx.png │ │ ├── acklio.png │ │ ├── browan.png │ │ ├── dragino.png │ │ ├── kerlink.png │ │ ├── miitors.png │ │ ├── pollex.png │ │ ├── skiply.png │ │ ├── cablelabs.png │ │ ├── milesight.png │ │ ├── my_devices.png │ │ ├── project_q.png │ │ ├── sidn_fonds.png │ │ ├── smartparks.png │ │ ├── thingstream.png │ │ └── objectspectrum.png ├── robots.txt └── css │ └── style.css ├── examples └── chirpstack │ ├── integrations │ ├── http │ │ ├── go │ │ │ ├── go.mod │ │ │ └── main.go │ │ └── python │ │ │ └── main.py │ ├── aws-sns │ │ ├── go │ │ │ └── go.mod │ │ └── python │ │ │ └── main.py │ ├── azure-service-bus │ │ ├── go │ │ │ └── go.mod │ │ └── python │ │ │ └── main.py │ └── gcp-pub-sub │ │ ├── go │ │ └── go.mod │ │ └── python │ │ └── main.py │ └── api │ ├── js │ ├── package.json │ └── enqueue_downlink.js │ ├── csharp │ ├── ChirpstackApiExample.csproj │ └── Program.cs │ ├── go │ ├── go.mod │ └── enqueue_downlink.go │ └── python │ └── enqueue_downlink.py ├── docker-compose.yml ├── Dockerfile-devel ├── Makefile └── book.toml /src/guides/index.md: -------------------------------------------------------------------------------- 1 | # Guides 2 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | book 2 | node_modules 3 | -------------------------------------------------------------------------------- /src/chirpstack/api/index.md: -------------------------------------------------------------------------------- 1 | # API 2 | -------------------------------------------------------------------------------- /src/chirpstack/use/index.md: -------------------------------------------------------------------------------- 1 | # Use 2 | -------------------------------------------------------------------------------- /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | github: chirpstack 2 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/use/index.md: -------------------------------------------------------------------------------- 1 | # Use 2 | -------------------------------------------------------------------------------- /src/chirpstack/backends/index.md: -------------------------------------------------------------------------------- 1 | # Backends 2 | -------------------------------------------------------------------------------- /src/chirpstack/features/index.md: -------------------------------------------------------------------------------- 1 | # Features 2 | -------------------------------------------------------------------------------- /src/chirpstack/index.md: -------------------------------------------------------------------------------- 1 | # ChirpStack 2 | 3 | -------------------------------------------------------------------------------- /src/chirpstack-concentratord/api/index.md: -------------------------------------------------------------------------------- 1 | # API 2 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/index.md: -------------------------------------------------------------------------------- 1 | # Integrations 2 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/backends/index.md: -------------------------------------------------------------------------------- 1 | # Backends 2 | -------------------------------------------------------------------------------- /src/chirpstack-concentratord/installation/index.md: -------------------------------------------------------------------------------- 1 | # Installation 2 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/integrations/index.md: -------------------------------------------------------------------------------- 1 | # Integrations 2 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/payloads/index.md: -------------------------------------------------------------------------------- 1 | # Payload formats 2 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/install/index.md: -------------------------------------------------------------------------------- 1 | # Installation 2 | 3 | * [RAK](./rak.md) 4 | -------------------------------------------------------------------------------- /theme/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/theme/favicon.png -------------------------------------------------------------------------------- /theme/img/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/theme/img/logo.png -------------------------------------------------------------------------------- /landing/img/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/logo.png -------------------------------------------------------------------------------- /src/sponsors/f3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/f3.png -------------------------------------------------------------------------------- /src/sponsors/rak.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/rak.png -------------------------------------------------------------------------------- /src/sponsors/acklio.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/acklio.png -------------------------------------------------------------------------------- /src/sponsors/afnic.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/afnic.jpg -------------------------------------------------------------------------------- /src/sponsors/browan.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/browan.png -------------------------------------------------------------------------------- /src/sponsors/pollex.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/pollex.png -------------------------------------------------------------------------------- /src/sponsors/reese.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/reese.jpg -------------------------------------------------------------------------------- /src/sponsors/skiply.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/skiply.png -------------------------------------------------------------------------------- /src/sponsors/twtg.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/twtg.png -------------------------------------------------------------------------------- /src/sponsors/wifx.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/wifx.png -------------------------------------------------------------------------------- /src/sponsors/dragino.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/dragino.png -------------------------------------------------------------------------------- /src/sponsors/kerlink.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/kerlink.png -------------------------------------------------------------------------------- /src/sponsors/miitors.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/miitors.png -------------------------------------------------------------------------------- /landing/img/chirpstack.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/chirpstack.png -------------------------------------------------------------------------------- /landing/img/sponsors/f3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/f3.png -------------------------------------------------------------------------------- /landing/img/sponsors/rak.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/rak.png -------------------------------------------------------------------------------- /src/sponsors/cablelabs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/cablelabs.png -------------------------------------------------------------------------------- /src/sponsors/milesight.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/milesight.png -------------------------------------------------------------------------------- /src/sponsors/my_devices.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/my_devices.png -------------------------------------------------------------------------------- /src/sponsors/project_q.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/project_q.png -------------------------------------------------------------------------------- /src/sponsors/sidn_fonds.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/sidn_fonds.png -------------------------------------------------------------------------------- /src/sponsors/smartparks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/smartparks.png -------------------------------------------------------------------------------- /src/sponsors/thingstream.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/thingstream.png -------------------------------------------------------------------------------- /landing/img/sponsors/afnic.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/afnic.jpg -------------------------------------------------------------------------------- /landing/img/sponsors/reese.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/reese.jpg -------------------------------------------------------------------------------- /landing/img/sponsors/twtg.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/twtg.png -------------------------------------------------------------------------------- /landing/img/sponsors/wifx.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/wifx.png -------------------------------------------------------------------------------- /src/guides/device-metrics.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/guides/device-metrics.png -------------------------------------------------------------------------------- /landing/img/sponsors/acklio.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/acklio.png -------------------------------------------------------------------------------- /landing/img/sponsors/browan.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/browan.png -------------------------------------------------------------------------------- /landing/img/sponsors/dragino.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/dragino.png -------------------------------------------------------------------------------- /landing/img/sponsors/kerlink.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/kerlink.png -------------------------------------------------------------------------------- /landing/img/sponsors/miitors.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/miitors.png -------------------------------------------------------------------------------- /landing/img/sponsors/pollex.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/pollex.png -------------------------------------------------------------------------------- /landing/img/sponsors/skiply.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/skiply.png -------------------------------------------------------------------------------- /src/chirpstack/backends/amqp.md: -------------------------------------------------------------------------------- 1 | # AMQP / RabbitMQ 2 | 3 | This backend will be added in a future release of ChirpStack v4. 4 | -------------------------------------------------------------------------------- /src/guides/node-red-echo-flow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/guides/node-red-echo-flow.png -------------------------------------------------------------------------------- /src/sponsors/objectspectrum.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/sponsors/objectspectrum.png -------------------------------------------------------------------------------- /landing/img/sponsors/cablelabs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/cablelabs.png -------------------------------------------------------------------------------- /landing/img/sponsors/milesight.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/milesight.png -------------------------------------------------------------------------------- /landing/img/sponsors/my_devices.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/my_devices.png -------------------------------------------------------------------------------- /landing/img/sponsors/project_q.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/project_q.png -------------------------------------------------------------------------------- /landing/img/sponsors/sidn_fonds.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/sidn_fonds.png -------------------------------------------------------------------------------- /landing/img/sponsors/smartparks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/smartparks.png -------------------------------------------------------------------------------- /src/chirpstack/backends/gcp-pub-sub.md: -------------------------------------------------------------------------------- 1 | # GCP Pub/Sub 2 | 3 | This backend will be added in a future release of ChirpStack v4. 4 | -------------------------------------------------------------------------------- /landing/img/sponsors/thingstream.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/thingstream.png -------------------------------------------------------------------------------- /src/chirpstack/backends/azure-iot-hub.md: -------------------------------------------------------------------------------- 1 | # Azure IoT Hub 2 | 3 | This backend will be added in a future release of ChirpStack v4. 4 | -------------------------------------------------------------------------------- /landing/img/sponsors/objectspectrum.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/landing/img/sponsors/objectspectrum.png -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/applications.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/chirpstack-gateway-os/applications.png -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/gateway-config.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/chirpstack-gateway-os/gateway-config.png -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/install/index.md: -------------------------------------------------------------------------------- 1 | # Installation 2 | 3 | * [RAK](./rak.md) 4 | * [Raspberry Pi](./raspberry-pi.md) 5 | * [Seeed](./seeed.md) 6 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/downloads.md: -------------------------------------------------------------------------------- 1 | # Downloads 2 | 3 | Please refer to the [Installation](./install/index.md) section for per-target 4 | downloads and installation instructions. 5 | 6 | -------------------------------------------------------------------------------- /examples/chirpstack/integrations/http/go/go.mod: -------------------------------------------------------------------------------- 1 | module example 2 | 3 | go 1.17 4 | 5 | require ( 6 | github.com/chirpstack/chirpstack/api/go/v4 v4.0.0-test.18 7 | google.golang.org/protobuf v1.28.1 8 | ) 9 | -------------------------------------------------------------------------------- /src/chirpstack/streams/index.md: -------------------------------------------------------------------------------- 1 | # Streams 2 | 3 | ChirpStack provides various [Redis Streams](https://redis.io/docs/data-types/streams/) 4 | which can be used for monitoring, extensions, billing, ... purposes. 5 | -------------------------------------------------------------------------------- /src/gateway-configuration/rak.md: -------------------------------------------------------------------------------- 1 | # RAK 2 | 3 | ## RAK7268V2 4 | 5 | Please refer to the ChirpStack MQTT Forwarder [installation instructions](../chirpstack-mqtt-forwarder/install/rak.md) 6 | for this gateway. 7 | -------------------------------------------------------------------------------- /docker-compose.yml: -------------------------------------------------------------------------------- 1 | services: 2 | chirpstack-docs: 3 | build: 4 | context: . 5 | dockerfile: Dockerfile-devel 6 | ports: 7 | - 3000:3000 8 | volumes: 9 | - ./:/chirpstack-docs 10 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/install/wifx-lorix-os-chirpstack-gateway-bridge.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chirpstack/chirpstack-docs/HEAD/src/chirpstack-gateway-bridge/install/wifx-lorix-os-chirpstack-gateway-bridge.png -------------------------------------------------------------------------------- /src/gateway-configuration/tektelic.md: -------------------------------------------------------------------------------- 1 | # Tektelic 2 | 3 | ## Kona gateways 4 | 5 | Please refer to the ChirpStack MQTT Forwarder [installation instructions](../chirpstack-mqtt-forwarder/install/tektelic.md) 6 | for this gateway. 7 | -------------------------------------------------------------------------------- /landing/robots.txt: -------------------------------------------------------------------------------- 1 | # Exclude v3 documentation 2 | User-agent: * 3 | Disallow: /project/ 4 | Disallow: /gateway-bridge/ 5 | Disallow: /application-server/ 6 | Disallow: /network-server/ 7 | Disallow: /concentratord/ 8 | Disallow: /gateway-os/ 9 | -------------------------------------------------------------------------------- /src/gateway-configuration/kerkink.md: -------------------------------------------------------------------------------- 1 | # Kerlink 2 | 3 | ## Kerlink KerOS based gateways 4 | 5 | Please refer to the ChirpStack MQTT Forwarder [installation instructions](../chirpstack-mqtt-forwarder/install/kerlink.md) 6 | for this gateway. 7 | -------------------------------------------------------------------------------- /src/chirpstack/use/event-log.md: -------------------------------------------------------------------------------- 1 | # Event log 2 | 3 | For debugging purposes, ChirpStack keeps a log of the last events that are 4 | exposed through the available integrations. To view the last events, open 5 | the device in the web-interface and open the **Events** tab. 6 | -------------------------------------------------------------------------------- /src/chirpstack-mqtt-forwarder/install/index.md: -------------------------------------------------------------------------------- 1 | # Installation 2 | 3 | Please select your vendor from the menu at the left side. If your gateway is 4 | not listed, please create an [Issue](https://github.com/chirpstack/chirpstack-mqtt-forwarder/issues) 5 | to request it being added. 6 | -------------------------------------------------------------------------------- /Dockerfile-devel: -------------------------------------------------------------------------------- 1 | FROM rust:1.81.0-bookworm 2 | 3 | WORKDIR /chirpstack-docs 4 | 5 | 6 | RUN cargo install mdbook@0.4.48 7 | RUN cargo install mdbook-tera 8 | RUN cargo install mdbook-graphviz 9 | RUN cargo install mdbook-toc 10 | 11 | RUN apt-get update && apt-get install -y graphviz 12 | -------------------------------------------------------------------------------- /src/context.json: -------------------------------------------------------------------------------- 1 | { 2 | "chirpstack_version": "4.15.0", 3 | "gateway_os_version": "4.9.0", 4 | "gateway_bridge_version": "4.1.1", 5 | "concentratord_version": "4.5.3", 6 | "mqtt_forwarder_version": "4.4.1", 7 | "pulsar_integration_version": "4.0.0-test.3", 8 | "gateway_mesh_version": "4.1.1" 9 | } 10 | -------------------------------------------------------------------------------- /examples/chirpstack/integrations/aws-sns/go/go.mod: -------------------------------------------------------------------------------- 1 | module example 2 | 3 | go 1.17 4 | 5 | require ( 6 | github.com/aws/aws-sdk-go v1.44.73 7 | github.com/chirpstack/chirpstack/api/go/v4 v4.0.0-test.18 8 | google.golang.org/protobuf v1.28.1 9 | ) 10 | 11 | require github.com/jmespath/go-jmespath v0.4.0 // indirect 12 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/install/dragino.md: -------------------------------------------------------------------------------- 1 | # Dragino 2 | 3 | Please refer to the Dragino [ChirpStack MQTT Forwarder](../../chirpstack-mqtt-forwarder/install/dragino.md) 4 | installation instructions. Installing the ChirpStack MQTT Forwarder 5 | is recommendend over installing the ChirpStack Gateway Bridge on 6 | the gateway. 7 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/install/kerlink.md: -------------------------------------------------------------------------------- 1 | # Kerlink 2 | 3 | Please refer to the Kerlink [ChirpStack MQTT Forwarder](../../chirpstack-mqtt-forwarder/install/kerlink.md) 4 | installation instructions. Installing the ChirpStack MQTT Forwarder 5 | is recommendend over installing the ChirpStack Gateway Bridge on 6 | the gateway. 7 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | build: 2 | docker-compose run --rm chirpstack-docs mdbook clean 3 | docker-compose run --rm chirpstack-docs mdbook build 4 | 5 | serve: 6 | docker-compose run --rm --service-ports chirpstack-docs mdbook serve -n 0.0.0.0 7 | 8 | upload: 9 | cd book && rsync -avzh . root@chirpstack.io:/var/www/chirpstack.io/docs/ 10 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/install/multitech.md: -------------------------------------------------------------------------------- 1 | # Multitech 2 | 3 | Please refer to the Dragino [ChirpStack MQTT Forwarder](../../chirpstack-mqtt-forwarder/install/multitech.md) 4 | installation instructions. Installing the ChirpStack MQTT Forwarder 5 | is recommendend over installing the ChirpStack Gateway Bridge on 6 | the gateway. 7 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/mydevices.md: -------------------------------------------------------------------------------- 1 | # myDevices 2 | 3 | The [myDevices](https://mydevices.com/) integration forwards received uplink 4 | data to an myDevices endpoint. 5 | 6 | When configuring the myDevices integration, there are three possible endpoints: 7 | 8 | * Cayenne 9 | * IoT in a Box 10 | * Custom endpoint URL 11 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/install/tektelic.md: -------------------------------------------------------------------------------- 1 | # Tektelic 2 | 3 | Please refer to the Tektelic [ChirpStack MQTT Forwarder](../../chirpstack-mqtt-forwarder/install/tektelic.md) 4 | installation instructions. Installing the ChirpStack MQTT Forwarder 5 | is recommendend over installing the ChirpStack Gateway Bridge on 6 | the gateway. 7 | 8 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/install/rak.md: -------------------------------------------------------------------------------- 1 | # RAK 2 | 3 | The [ChirpStack Gateway OS](../../chirpstack-gateway-os/index.md) includes 4 | support for the ChirpStack Gateway Mesh. Please refer to the [RAK installation page](../../chirpstack-gateway-os/install/rak.md) 5 | for instructions on how to install the ChirpStack Gateway OS on supported RAK 6 | gateways. 7 | -------------------------------------------------------------------------------- /examples/chirpstack/api/js/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "js", 3 | "version": "1.0.0", 4 | "description": "", 5 | "main": "enqueue_downlink.js", 6 | "scripts": { 7 | "test": "echo \"Error: no test specified\" && exit 1" 8 | }, 9 | "author": "", 10 | "license": "MIT", 11 | "dependencies": { 12 | "@chirpstack/chirpstack-api": "^4.2.0" 13 | } 14 | } 15 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/install/raspberry-pi.md: -------------------------------------------------------------------------------- 1 | # Raspberry Pi 2 | 3 | The [ChirpStack Gateway OS](../../chirpstack-gateway-os/index.md) includes 4 | support for the ChirpStack Gateway Mesh. Please refer to the [Raspberry Pi installation page](../../chirpstack-gateway-os/install/raspberry-pi.md) 5 | for instructions on how to install the ChirpStack Gateway OS on Raspberry Pi 6 | based gateways. 7 | -------------------------------------------------------------------------------- /theme/head.hbs: -------------------------------------------------------------------------------- 1 | 2 | 3 | 10 | 11 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/protocol/index.md: -------------------------------------------------------------------------------- 1 | # Protocol 2 | 3 | This section describes the Relay encapsulated payload that is used for relaying 4 | uplink and downlink transmissions and events and commands payloads. 5 | 6 | * [Stored context](./stored-context.md) 7 | * [Uplink](./uplink.md) 8 | * [Downlink](./downlink.md) 9 | * [Events](./events.md) 10 | * [Commands](./commands.md) 11 | * [TLV payloads](./tlv-payloads.md) 12 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/use/log-files.md: -------------------------------------------------------------------------------- 1 | # Log files 2 | 3 | ## Web-interface 4 | 5 | To read log output using the web-interface, click **Status** and then 6 | **System Log** in the left menu. 7 | 8 | ## SSH 9 | 10 | To read log output using SSH, you need to use the `logread` utility. 11 | Examples: 12 | 13 | ```bash 14 | # Print log output 15 | logread 16 | 17 | # Get last 20 lines and follow log messages 18 | logread -n 20 -f 19 | ``` 20 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/use/subscribe-to-mqtt.md: -------------------------------------------------------------------------------- 1 | # Subscribe to MQTT 2 | 3 | The **Full** image comes with [Mosquitto](https://mosquitto.org/) as MQTT 4 | broker pre-installed. 5 | 6 | ## Subscribing 7 | 8 | You can use the following command to receive data: 9 | 10 | ```bash 11 | mosquitto_sub -h localhost -t "application/#" -v 12 | ``` 13 | 14 | If you are connecting from a different host, then you must change `localhost` 15 | to the IP address of your gateway. 16 | -------------------------------------------------------------------------------- /src/chirpstack/use/applications.md: -------------------------------------------------------------------------------- 1 | # Applications 2 | 3 | An application is a collection of devices with the same purpose / of the same type. 4 | Think of a weather station collecting data at different locations for example. 5 | 6 | ## Integrations 7 | 8 | For documentation on the available integrations, please refer to the 9 | **Integrations** section in the left menu. 10 | 11 | ## Devices 12 | 13 | Multiple [Devices](devices.md) can be added to an application. 14 | -------------------------------------------------------------------------------- /examples/chirpstack/api/csharp/ChirpstackApiExample.csproj: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Exe 5 | net8.0 6 | enable 7 | enable 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/use/software-update.md: -------------------------------------------------------------------------------- 1 | # Software updates 2 | 3 | ChirpStack Gateway OS can be upgraded using the web-interface (including 4 | switching between **Base** and **Full** images). In the web-interface, click 5 | **System** and then **Backup / Flash Firmware** in the left menu. Then click 6 | **Flash image...**. 7 | 8 | For more information on software upgrades, please refer to the 9 | [Upgrading OpenWrt firmware using LuCI and CLI](https://openwrt.org/docs/guide-user/installation/generic.sysupgrade). -------------------------------------------------------------------------------- /src/chirpstack/use/users.md: -------------------------------------------------------------------------------- 1 | # Users 2 | 3 | For authentication and authorization, users can be created in ChirpStack. 4 | An user itself can be a global admin or a regular user. 5 | 6 | ## Global admin user 7 | 8 | A global admin user is authorized to perform any action. It can for example 9 | manage gateways, users, create organizations, applications and nodes. 10 | 11 | ## Regular users 12 | 13 | A regular users has no permissions by default. However, it can be assigned to 14 | one or multiple organizations. 15 | -------------------------------------------------------------------------------- /examples/chirpstack/api/go/go.mod: -------------------------------------------------------------------------------- 1 | module example 2 | 3 | go 1.17 4 | 5 | require ( 6 | github.com/chirpstack/chirpstack/api/go/v4 v4.0.0-test.18 7 | google.golang.org/grpc v1.48.0 8 | ) 9 | 10 | require ( 11 | github.com/golang/protobuf v1.5.2 // indirect 12 | golang.org/x/net v0.0.0-20201021035429-f5854403a974 // indirect 13 | golang.org/x/sys v0.0.0-20210119212857-b64e53b001e4 // indirect 14 | golang.org/x/text v0.3.3 // indirect 15 | google.golang.org/genproto v0.0.0-20200526211855-cb27e3aa2013 // indirect 16 | google.golang.org/protobuf v1.28.0 // indirect 17 | ) 18 | -------------------------------------------------------------------------------- /src/chirpstack/api/js-examples.md: -------------------------------------------------------------------------------- 1 | # JavaScript examples 2 | 3 | * [gRPC documentation for Node](https://grpc.io/docs/languages/node/) 4 | 5 | ## Enqueue 6 | 7 | The example below demonstrates: 8 | 9 | * Configuration of gRPC _dial options_ including API token 10 | * Connect to a gRPC API 11 | * Define service client (in this case for the `DeviceService`) 12 | * Perform an API call for a service (in this case `Enqueue`) 13 | 14 | ### `enqueue_downlink.js` 15 | 16 | ```js 17 | {% raw %}{{#include ../../../examples/chirpstack/api/js/enqueue_downlink.js}}{%endraw %} 18 | ``` 19 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/downloads.md: -------------------------------------------------------------------------------- 1 | # Downloads 2 | 3 | ## Binaries 4 | 5 | | File name | Type | OS | Arch | 6 | | --------- | ---- | -- | ---- | 7 | | [chirpstack-gateway-mesh_{{gateway_mesh_version}}_linux_armv7hf.tar.gz](https://artifacts.chirpstack.io/downloads/chirpstack-gateway-mesh/chirpstack-gateway-mesh_{{gateway_mesh_version}}_linux_armv7hf.tar.gz) | .tar.gz | Linux | armv7 | 8 | | [chirpstack-gateway-mesh_{{gateway_mesh_version}}_linux_arm64.tar.gz](https://artifacts.chirpstack.io/downloads/chirpstack-gateway-mesh/chirpstack-gateway-mesh_{{gateway_mesh_version}}_linux_arm64.tar.gz) | .tar.gz | Linux | arm64 | 9 | -------------------------------------------------------------------------------- /src/v3-documentation.md: -------------------------------------------------------------------------------- 1 | # v3 documentation 2 | 3 | This site covers the ChirpStack v4 documentation. For ChirpStack v3 4 | documentation please refer to the following links: 5 | 6 | * [Getting started](https://www.chirpstack.io/project/) 7 | * [ChirpStack Gateway Bridge](https://www.chirpstack.io/gateway-bridge/) 8 | * [ChirpStack Network Server](https://www.chirpstack.io/network-server/) 9 | * [ChirpStack Application Server](https://www.chirpstack.io/application-server/) 10 | * [ChirpStack Concentratord](https://www.chirpstack.io/concentratord/) 11 | * [ChirpStack Gateway OS](https://www.chirpstack.io/gateway-os/) 12 | -------------------------------------------------------------------------------- /src/gateway-configuration/multitech.md: -------------------------------------------------------------------------------- 1 | # Multitech 2 | 3 | ## Multitech Conduit 4 | 5 | Please refer to the ChirpStack MQTT Forwarder [installation instructions](../chirpstack-mqtt-forwarder/install/multitech.md) 6 | for this gateway. 7 | 8 | 9 | ## Multitech Conduit AP 10 | 11 | Please refer to the ChirpStack MQTT Forwarder [installation instructions](../chirpstack-mqtt-forwarder/install/multitech.md) 12 | for this gateway. 13 | 14 | ## Multitech Conduit AP3 15 | 16 | Please refer to the ChirpStack MQTT Forwarder [installation instructions](../chirpstack-mqtt-forwarder/install/multitech.md) 17 | for this gateway. 18 | -------------------------------------------------------------------------------- /src/chirpstack/features/geolocation.md: -------------------------------------------------------------------------------- 1 | # Geolocation 2 | 3 | ChirpStack supports various forms of geolocation through the [LoRa Cloud](../integrations/loracloud.md) 4 | integration. As ChirpStack does expose meta-data like gateway location, RSSI, SNR 5 | and fine-timestamp (if supported by the gateway) in every uplink event, it is 6 | also possible to implement your own geolocation resolver. 7 | 8 | ## Requirements 9 | 10 | For TDOA (time difference of arrival) based geolocation, you must have a gateway 11 | that has support for the fine-timestamp. If applicable, the fine-timestamp must 12 | be encrypted by the packet-forwarder. 13 | -------------------------------------------------------------------------------- /src/chirpstack/use/login.md: -------------------------------------------------------------------------------- 1 | # Login 2 | 3 | If a TLS certificate has been configured (optional), use http**s://** 4 | else use the http:// option (default). 5 | 6 | * **http://** [http://localhost:8080/](http://localhost:8080/) 7 | * **https://** [https://localhost:8080/](https://localhost:8080/) 8 | 9 | 10 | When running ChirpStack locally, this means you should navigate to 11 | [http://localhost:8080/](http://localhost:8080) (in case of http://). 12 | 13 | After installing ChirpStack, you can login with the default credentials 14 | user: `admin`, password: `admin`. For security reasons, you should change 15 | this password as soon as possible. 16 | -------------------------------------------------------------------------------- /src/gateway-configuration/dragino.md: -------------------------------------------------------------------------------- 1 | # Dragino 2 | 3 | ## LPS8(N) Indoor LoRaWAN Gateway 4 | 5 | Please refer to the ChirpStack MQTT Forwarder [installation instructions](../chirpstack-mqtt-forwarder/install/dragino.md) 6 | for this gateway. 7 | 8 | ## LPS8V2 Indoor LoRaWAN Gateway 9 | 10 | Please refer to the ChirpStack MQTT Forwarder [installation instructions](../chirpstack-mqtt-forwarder/install/dragino.md) 11 | for this gateway. 12 | 13 | 14 | 15 | 16 | ## LG308(N) LoRaWAN Gateway 17 | 18 | Please refer to the ChirpStack MQTT Forwarder [installation instructions](../chirpstack-mqtt-forwarder/install/dragino.md) 19 | for this gateway. 20 | -------------------------------------------------------------------------------- /src/chirpstack/api/go-examples.md: -------------------------------------------------------------------------------- 1 | # Go examples 2 | 3 | * [Go gRPC reference](https://pkg.go.dev/google.golang.org/grpc) 4 | * [ChirpStack Go SDK reference](https://pkg.go.dev/github.com/chirpstack/chirpstack/api/go/v4) 5 | 6 | ## Enqueue downlink 7 | 8 | The example below demonstrates: 9 | 10 | * Configuration of gRPC _dial options_ including API token 11 | * Connect to a gRPC API 12 | * Define service client (in this case for the `DeviceService`) 13 | * Perform an API call for a service (in this case `Enqueue`) 14 | 15 | ### `main.go` 16 | 17 | ```go 18 | {% raw %}{{#include ../../../examples/chirpstack/api/go/enqueue_downlink.go}}{% endraw %} 19 | ``` 20 | -------------------------------------------------------------------------------- /src/chirpstack/contribute.md: -------------------------------------------------------------------------------- 1 | # Contribute & source 2 | 3 | ## Links 4 | 5 | - Community support: [https://support.chirpstack.io/](https://support.chirpstack.io/) 6 | - Source repository: [https://github.com/chirpstack/chirpstack](https://github.com/chirpstack/chirpstack) 7 | - Issue and bug reports: [https://github.com/chirpstack/chirpstack/issues](https://github.com/chirpstack/chirpstack/issues) 8 | 9 | ## Building from source 10 | 11 | For instructions on building the ChirpStack source-code from source, 12 | please refer to the `README.md` in the source repository: 13 | 14 | [https://github.com/chirpstack/chirpstack/](https://github.com/chirpstack/chirpstack/) 15 | -------------------------------------------------------------------------------- /src/chirpstack-concentratord/api/events.md: -------------------------------------------------------------------------------- 1 | # Events 2 | 3 | Events are published by Concentratord and can be received by creating a 4 | [ZeroMQ SUB](http://zguide.zeromq.org/page:all#toc49) socket. The first frame 5 | holds the event type (string), the second frame holds the event payload encoded 6 | using [Protobuf](https://developers.google.com/protocol-buffers) 7 | (see `api/proto/gw/gw.proto` in [chirpstack](https://github.com/chirpstack/chirpstack) 8 | for the Protobuf message definitions). 9 | 10 | ## `up` 11 | 12 | Uplink received by the gateway (`UplinkFrame` Protobuf message). 13 | 14 | ## `stats` 15 | 16 | Gateway statistics (`GatewayStats` Protobuf message). 17 | -------------------------------------------------------------------------------- /src/chirpstack/features/device-metrics.md: -------------------------------------------------------------------------------- 1 | # Device metrics 2 | 3 | ChirpStack can visualize measurements collected by devices in simple graphs. 4 | This makes testing and setting up proof of concepts really easy, as no external 5 | software or services are required to visualize collected data. 6 | 7 | In order to start visualizing collected measurements, you must configure the 8 | following: 9 | 10 | * Payload codec: As ChirpStack must decode the data in order to collect the measurements. 11 | * Measurements: The measurements that must be aggregated by ChirpStack. 12 | 13 | Both options can be found in the [Device Profile](../use/device-profiles.md) 14 | configuration. 15 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/pilot-things.md: -------------------------------------------------------------------------------- 1 | # Pilot Things 2 | 3 | If configured, the Pilot Things integration will send raw device data to the 4 | configured [Pilot Things](https://www.pilot-things.com/) instance. 5 | 6 | ## Requirements 7 | 8 | Pilot Things requires an _Authentication Token_. This token must be correctly 9 | set in the device integration for data submission to be successful. 10 | 11 | ## Attributes 12 | 13 | For each uplink message, ChirpStack will send Pilot Things 14 | the following data: 15 | 16 | * RSSI 17 | * LoRa SNR 18 | * RF chain 19 | * Antenna ID 20 | * Board ID 21 | * Device name 22 | * Raw message data 23 | * Device EUI 24 | * LoRa port 25 | * Device address 26 | * Frame count 27 | -------------------------------------------------------------------------------- /src/getting-started/raspberry-pi.md: -------------------------------------------------------------------------------- 1 | # Quickstart Raspberry Pi 2 | 3 | For getting started with a Raspberry Pi based LoRa gateway, ChirpStack 4 | provides the ChirpStack Gateway OS. This OS is an [OpenWrt](https://openwrt.org/) 5 | based image which comes in two flavors: 6 | 7 | * **Base:** Everything that is required to turn your Raspberry Pi into a 8 | LoRa gateway, which forwards its data to an external ChirpStack instance. 9 | * **Full:** This image includes the ChirpStack Network Server to use the 10 | Raspberry Pi both as gateway and as LoRaWAN Network Server. 11 | 12 | Please refer to the [ChirpStack Gateway OS documentation](../chirpstack-gateway-os/index.md) 13 | for installation and usage instructions. 14 | -------------------------------------------------------------------------------- /src/chirpstack/features/device-time.md: -------------------------------------------------------------------------------- 1 | # Device time 2 | 3 | ChirpStack supports the synchronization of the internal device clock with the 4 | network using the `DeviceTimeReq` mac-command. This is useful for devices that 5 | need to have an accurate time-source or devices implementing LoRaWAN® Class-B. 6 | 7 | If possible, ChirpStack uses the RX timestamp provided by the gateway which 8 | results in the most accurate time. When this timestamp is not available (e.g. the 9 | gateway is not time synchronized), it will use the current server time. Please 10 | note that in this case the returned timestamp is less accurate as ChirpStack 11 | is not aware of the latency between the gateway and the network-server. 12 | -------------------------------------------------------------------------------- /src/chirpstack/api/csharp-examples.md: -------------------------------------------------------------------------------- 1 | # C# examples 2 | 3 | * [Call gRPC services with the .NET client](https://learn.microsoft.com/en-us/aspnet/core/grpc/client?view=aspnetcore-8.0) 4 | 5 | ## Preparation 6 | 7 | Need to install several NuGet packages: 8 | 9 | * Chirpstack.Api 10 | * Grpc.Net.Client.Web 11 | 12 | ## Enqueue 13 | 14 | The example below demonstrates: 15 | 16 | * Configuration of gRPC _dial options_ including API token 17 | * Connect to a gRPC API 18 | * Define service client (in this case for the `DeviceService`) 19 | * Perform an API call for a service (in this case `Enqueue`) 20 | 21 | ### `Program.cs` 22 | 23 | ```csharp 24 | {% raw %}{{#include ../../../examples/chirpstack/api/csharp/Program.cs}}{%endraw %} 25 | ``` 26 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/use/node-red.md: -------------------------------------------------------------------------------- 1 | # Node-RED 2 | 3 | [Node-RED](https://nodered.org/) provides a browser-based flow editor that makes 4 | it easy to wire together flows using the wide range of nodes in the palette. 5 | 6 | If you have installed the **Full** image, then Node-RED is pre-installed, 7 | including the [node-red-contrib-chirpstack](https://github.com/brocaar/node-red-contrib-chirpstack/) 8 | package which provides several nodes to interact with ChirpStack. 9 | 10 | Links: 11 | 12 | * [Node-RED integration guide](../../guides/node-red-integration.md) 13 | 14 | ## Access Node-RED 15 | 16 | Node-RED can be opened from the web-interface, by clicking **Applications** 17 | in the left menu, and then clicking the **Node-RED** icon. 18 | -------------------------------------------------------------------------------- /src/chirpstack/api/python-examples.md: -------------------------------------------------------------------------------- 1 | # Python examples 2 | 3 | * [Python gRPC quickstart](https://grpc.io/docs/languages/python/quickstart/) 4 | * [`chirpstack-api` Python package](https://pypi.org/project/chirpstack-api/) 5 | 6 | ChirpStack provides a Python package `chirpstack-api` that can be installed 7 | using `pip`: 8 | 9 | ```bash 10 | pip install chirpstack-api 11 | ``` 12 | 13 | ## Enqueue downlink 14 | 15 | The example below demonstrates: 16 | 17 | * Connecting to a gRPC server 18 | * Defining a service client / stub 19 | * Performing an API call (in this case `Enqeue`) 20 | 21 | ### `enqueue_downlink.py` 22 | 23 | ```python 24 | {% raw %}{{#include ../../../examples/chirpstack/api/python/enqueue_downlink.py}}{% endraw %} 25 | ``` 26 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/backends/concentratord.md: -------------------------------------------------------------------------------- 1 | # ChirpStack Concentratord 2 | 3 | The Concentratord backend implements the ChirpStack Concentratord 4 | [ZeroMQ](https://zeromq.org/) based interface. 5 | 6 | ## Deployment 7 | 8 | The ChirpStack Gateway Bridge and the ChirpStack Concentratord must be deployed 9 | on the gateway. 10 | 11 | ## Prometheus metrics 12 | 13 | The ChirpStack Concentratord backend exposes several [Prometheus](https://prometheus.io/) 14 | metrics for monitoring. 15 | 16 | #### backend_concentratord_event_count 17 | 18 | The number of received events from Concentratord (per event type). 19 | 20 | #### backend_concentratord_command_count 21 | 22 | The number of commands sent to Concentratord (per command type). 23 | 24 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/index.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | ChirpStack Gateway OS is an open-source [OpenWrt](https://openwrt.org/) based 4 | embedded OS supporting Raspberry Pi and some off-the-shelf LoRa® 5 | gateways. It provides a web-interface with configuration options for most 6 | common LoRa concentrator shields (in case of Raspberry Pi gateways). 7 | 8 | The Raspberry Pi images come in two versions: 9 | 10 | * **Base**: Image containing containing all gateway components 11 | * **Full**: Base image + additional applications 12 | * ChirpStack Network Server 13 | * Node-RED 14 | 15 | For off-the-shelf gateways only a single version is provided, capabilities 16 | of the gateway. 17 | 18 | ![gateway-config](gateway-config.png) 19 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/configuration.md: -------------------------------------------------------------------------------- 1 | # Configuration 2 | 3 | To list all CLI options, start `chirpstack-gateway-mesh` with the `--help` 4 | flag. This will print: 5 | 6 | ```text 7 | ChirpStack Gateway Mesh 8 | 9 | Usage: chirpstack-gateway-mesh [OPTIONS] [COMMAND] 10 | 11 | Commands: 12 | configfile Print the configuration template 13 | help Print this message or the help of the given subcommand(s) 14 | 15 | Options: 16 | -c, --config 17 | -h, --help Print help 18 | -V, --version Print version 19 | ``` 20 | 21 | ## Configuration example 22 | 23 | Example `chirpstack-gateway-mesh.toml` configuration: 24 | 25 | ```toml 26 | {%raw-%} 27 | {{#include chirpstack-gateway-mesh.toml}} 28 | {%endraw-%} 29 | ``` 30 | -------------------------------------------------------------------------------- /src/chirpstack-mqtt-forwarder/contribute.md: -------------------------------------------------------------------------------- 1 | # Contribute & source 2 | 3 | ## Links 4 | 5 | - Community support: [https://support.chirpstack.io/](https://support.chirpstack.io/) 6 | - Source repository: [https://github.com/chirpstack/chirpstack-mqtt-forwarder](https://github.com/chirpstack/chirpstack-mqtt-forwarder) 7 | - Issue and bug reports: [https://github.com/chirpstack/chirpstack-mqtt-forwarder/issues](https://github.com/chirpstack/chirpstack-mqtt-forwarder/issues) 8 | 9 | ## Building from source 10 | 11 | For instructions on building the ChirpStack MQTT Forwarder source-code from source, 12 | please refer to the `README.md` in the source repository: 13 | 14 | [https://github.com/chirpstack/chirpstack-mqtt-forwarder/](https://github.com/chirpstack/chirpstack-mqtt-forwarder/) 15 | -------------------------------------------------------------------------------- /src/chirpstack-mqtt-forwarder/configuration.md: -------------------------------------------------------------------------------- 1 | # Configuration 2 | 3 | To list all CLI options, start `chirpstack-mqtt-forwarder` with the `--help` 4 | flag. This will print: 5 | 6 | ```text 7 | ChirpStack MQTT Forwarder 8 | 9 | Usage: chirpstack-mqtt-forwarder [OPTIONS] [COMMAND] 10 | 11 | Commands: 12 | configfile Print the configuration template 13 | help Print this message or the help of the given subcommand(s) 14 | 15 | Options: 16 | -c, --config 17 | -h, --help Print help information 18 | -V, --version Print version information 19 | ``` 20 | 21 | ## Configuration example 22 | 23 | Example `chirpstack-mqtt-forwarder.toml` configuration: 24 | 25 | ```toml 26 | {%raw%} 27 | {{#include chirpstack-mqtt-forwarder.toml}} 28 | {%endraw%} 29 | ``` 30 | -------------------------------------------------------------------------------- /src/chirpstack/api/rest.md: -------------------------------------------------------------------------------- 1 | # REST API 2 | 3 | With the introduction of ChirpStack v4, the REST API interface is no longer 4 | included. Historically it was included to serve the web-interface, as at 5 | that time, gRPC could not be used within the browser. The included REST 6 | interface internally translated REST requests into gRPC and back. 7 | 8 | It is recommended to use the gRPC if possible. However if a REST interface 9 | is required, please refer to [https://github.com/chirpstack/chirpstack-rest-api](https://github.com/chirpstack/chirpstack-rest-api). 10 | This component provides the same translation layer (using the [gRPC Gateway](https://github.com/grpc-ecosystem/grpc-gateway/) 11 | project), including a web-based interface of the API (using [Swagger UI](https://swagger.io/tools/swagger-ui/)). 12 | -------------------------------------------------------------------------------- /src/chirpstack/features/multicast.md: -------------------------------------------------------------------------------- 1 | # Multicast 2 | 3 | ChirpStack has support for creating multicast-groups to which devices can be 4 | assigned. When enqueueing a downlink payload for a multicast-group, ChirpStack 5 | will analyze which gateways must be used for broadcasting to cover the complete 6 | multicast-group. This means that potentially, a single multicast downlink 7 | payload will be emitted multiple times. To avoid collisions, ChirpStack will 8 | put a delay between multiple emissions. 9 | 10 | Multicast can be used for the following device-classes: 11 | 12 | * Class-B 13 | * Class-C 14 | 15 | The configuration of the multicast-groups at the device side happens out-of-band. 16 | This means that assigning a device to a device-group does not configure the 17 | device itself to be part of the multicast-group. 18 | -------------------------------------------------------------------------------- /src/chirpstack/use/multicast-groups.md: -------------------------------------------------------------------------------- 1 | # Multicast groups 2 | 3 | By creating a multicast-group, it is possible to send a single downlink payload 4 | to a group of devices (the multicast-group). All these devices share the same 5 | multicast-address, session-keys and frame-counter. 6 | 7 | After creating a multicast-group, it is possible to assign devices to the group. 8 | Please note that the device must already created (see [Devices](devices.md). 9 | 10 | ## Provisioning of the device 11 | 12 | The provisioning of the multicast-group on the device happens out-of-band. 13 | This means that after adding a device to a multicast-group, you must also 14 | configure the device with the multicast-address, session-keys etc... 15 | 16 | ## Sending data 17 | 18 | Sending data to the multicast-group is possible using the API. 19 | -------------------------------------------------------------------------------- /src/chirpstack/streams/metadata.md: -------------------------------------------------------------------------------- 1 | # Uplink / downlink metadata 2 | 3 | The uplink / downlink metadata stream exposes metadata that can be used for 4 | for example billing-purposes. 5 | 6 | ## Redis key 7 | 8 | This stream is published under the `stream:meta` Redis key. 9 | 10 | ## Data 11 | 12 | This stream exposes: 13 | 14 | * DevEUI 15 | * Message-type 16 | * RxInfo / TxInfo 17 | * PHYPayload size 18 | * MAC-command size 19 | * Application payload size 20 | 21 | See also [meta.proto](https://github.com/chirpstack/chirpstack/blob/master/api/proto/stream/meta.proto). 22 | 23 | ## Example code 24 | 25 | Example code can be found in the [examples](https://github.com/chirpstack/chirpstack/tree/master/examples) 26 | directory of the [https://github.com/chirpstack/chirpstack](https://github.com/chirpstack/chirpstack) 27 | repository. -------------------------------------------------------------------------------- /src/chirpstack/use/frame-log.md: -------------------------------------------------------------------------------- 1 | # Frame log 2 | 3 | For debugging purposes, ChirpStack keeps a log of the last LoRaWAN frames that 4 | are exposed through the available integrations. This feature is available both 5 | for gateways and devices. 6 | 7 | ### Gateway frame logs 8 | 9 | The **LoRaWAN frames** tab on the gateway detail page will display all frames 10 | sent and received by the selected gateway. This includes frames received from 11 | unknown devices. 12 | 13 | ### Device frame logs 14 | 15 | The **LoRaWAN frames** tab on the device detail page will display all frames 16 | which have been authenticated with the (session)keys of the device. This means 17 | that in case your device is experiencing MIC calculation issues, you will see 18 | the uplink frame under the gateway frame logs, but not under the device frame 19 | logs. 20 | -------------------------------------------------------------------------------- /book.toml: -------------------------------------------------------------------------------- 1 | [book] 2 | title = "ChirpStack open-source LoRaWAN® Network Server documentation" 3 | authors = [] 4 | language = "en" 5 | multilingual = false 6 | src = "src" 7 | 8 | [output.html] 9 | no-section-label = true 10 | additional-css = ["theme/css/chirpstack.css"] 11 | git-repository-url = "https://github.com/chirpstack/chirpstack-docs" 12 | git-repository-icon = "fa-github" 13 | edit-url-template = "https://github.com/chirpstack/chirpstack-docs/edit/master/{path}" 14 | 15 | [output.html.print] 16 | enable = false 17 | 18 | [output.html.fold] 19 | enable = true 20 | level = 0 21 | 22 | [preprocessor.tera] 23 | command = "mdbook-tera --json ./src/context.json" 24 | 25 | [preprocessor.graphviz] 26 | command = "mdbook-graphviz" 27 | 28 | [preprocessor.toc] 29 | command = "mdbook-toc" 30 | renderer = ["html"] 31 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/payloads/states.md: -------------------------------------------------------------------------------- 1 | # States 2 | 3 | States are generated by the ChirpStack Gateway Bridge and forwarded to the configured 4 | integration as retained messages. Depending the `marshaler` configuration, these 5 | are sent as: 6 | 7 | * JSON: JSON based on the Protobuf Buffers JSON mapping (for debugging) 8 | * Protobuf: Protocol Buffers binary encoding (recommended) 9 | 10 | For the [Protobuf](https://developers.google.com/protocol-buffers/) 11 | message definitions, please refer to [gw.proto](https://github.com/chirpstack/chirpstack/blob/master/api/proto/gw/gw.proto). 12 | 13 | ## State types 14 | 15 | ### `conn` - Gateway connection state 16 | 17 | Defined by the `ConnState` Protobuf message. 18 | 19 | 20 | JSON example: 21 | 22 | ```json 23 | { 24 | "gatewayId": "0016c001f153a14c", 25 | "state": "ONLINE" 26 | } 27 | ``` 28 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/index.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | ChirpStack Gateway Bridge is a service which converts LoRa® Packet Forwarder protocols 4 | into a ChirpStack [common data-format](https://github.com/chirpstack/chirpstack/blob/master/api/proto/gw/gw.proto). 5 | 6 | ## Backends 7 | 8 | The following Packet Forwarder backends are provided: 9 | 10 | * [ChirpStack Concentratord](../chirpstack-concentratord/index.md) 11 | * [Semtech UDP Packet Forwarder](https://github.com/Lora-net/packet_forwarder) 12 | * [Basic Station Packet Forwarder](https://github.com/lorabasics/basicstation) 13 | 14 | ## Integrations 15 | 16 | The following integrations are provided: 17 | 18 | * Generic MQTT broker 19 | * [GCP Cloud IoT Core MQTT Bridge](https://cloud.google.com/iot-core/) 20 | * [Azure IoT Hub MQTT Bridge](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support) 21 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/use/modifying-files.md: -------------------------------------------------------------------------------- 1 | # Modifying files 2 | 3 | ChirpStack Gateway OS uses an [OverlayFS](https://en.wikipedia.org/wiki/OverlayFS) 4 | on top of the read-only root filesystem. This means you can make modifications that 5 | are persisted even after a software update as these changes are written to a 6 | different data partition. 7 | 8 | ## Important 9 | 10 | Before performing a backup or upgrade, please make sure that the directories / 11 | files are listed in the files that must be included during a sysupgrade. This 12 | list can be configured in the web-interface by clicking the **System**, then 13 | **Backup / Flash Firmware** in the left menu and then clicking the 14 | **Configuration** tab. 15 | 16 | ## Reset 17 | 18 | To perform a factory reset using the web-interface, click **System**, then 19 | **Backup / Flash Firmware** in the left menu. Then click **Perform reset**. 20 | -------------------------------------------------------------------------------- /src/chirpstack/features/rx-parameters-configuration.md: -------------------------------------------------------------------------------- 1 | # RX parameters (re)configuration 2 | 3 | ChirpStack supports the (re)configuration of the following RX parameters: 4 | 5 | * **RX delay** the delay between the end of TX and the first reception slot. 6 | * **RX1 data-rate offset** the offset used to calculate the RX1 data-rate, 7 | based on the uplink data-rate. 8 | * **RX2 data-rate** the data-rate used for the RX2 receive-window. 9 | * **RX2 frequency** the frequency used for the RX2 receive-window. 10 | 11 | The first three parameters are sent to the device as part of the OTAA join-accept 12 | frame. The RX2 frequency parameter is pushed to the device using the 13 | `RXParamSetupReq` mac-command. 14 | 15 | **Note:** on a ChirpStack configuration change, the new parameters will be 16 | pushed to the device using the `RXParamSetupReq` or `RXTimingSetupReq` 17 | mac-commands at the first opportunity. 18 | -------------------------------------------------------------------------------- /src/chirpstack/streams/api-requests.md: -------------------------------------------------------------------------------- 1 | # API requests 2 | 3 | The API requests stream exposes meta-data about [API](../api/index.md) requests 4 | being made by the web-interface and / or external API clients. 5 | 6 | ## Redis key 7 | 8 | This stream is published under the `api:stream:request` Redis key. 9 | 10 | ## Data 11 | 12 | This stream exposes: 13 | 14 | * gRPC API service (e.g. `DeviceService`) 15 | * gRPC API method (e.g. `Create`) 16 | * Metadata (e.g. the identifier of the created / updated / deleted object) 17 | 18 | See also [api_request.proto](https://github.com/chirpstack/chirpstack/blob/master/api/proto/stream/api_request.proto). 19 | 20 | ## Example code 21 | 22 | Example code can be found in the [examples](https://github.com/chirpstack/chirpstack/tree/master/examples) 23 | directory of the [https://github.com/chirpstack/chirpstack](https://github.com/chirpstack/chirpstack) 24 | repository. -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/metrics.md: -------------------------------------------------------------------------------- 1 | # Prometheus metrics 2 | 3 | Independent from the chosen MQTT authentication type, the MQTT integration 4 | exposes the following [Prometheus](https://prometheus.io/) metrics for monitoring. 5 | 6 | #### integration_mqtt_event_count 7 | 8 | The number of gateway events published by the MQTT integration (per event). 9 | 10 | #### integration_mqtt_command_count 11 | 12 | The number of commands received by the MQTT integration (per command). 13 | 14 | #### integration_mqtt_connect_count 15 | 16 | The number of times the integration connected to the MQTT broker. 17 | 18 | #### integration_mqtt_disconnect_count 19 | 20 | The number of times the integration disconnected from the MQTT broker. 21 | 22 | #### integration_mqtt_reconnect_count 23 | 24 | The number of times the integration reconnected to the MQTT broker (this also increments the disconnect and connect counters). 25 | -------------------------------------------------------------------------------- /theme/header.hbs: -------------------------------------------------------------------------------- 1 |
2 | 6 |
7 | Sponsor 9 | Star 11 |
12 | 13 | Home | Documentation (v4) | Documentation (v3) | Community support 16 | 17 |
18 | -------------------------------------------------------------------------------- /src/chirpstack/features/device-status.md: -------------------------------------------------------------------------------- 1 | # Device status 2 | 3 | ChirpStack supports periodically requesting the Device Status, using the 4 | `DevStatusReq` mac-command specified by the LoRaWAN® protocol. 5 | A device will respond to this request by sending its battery status 6 | (if available) and its demodulation signal-to-noise ratio in dB 7 | for the last successfully received request. 8 | 9 | When the device status is available, it will be exposed through the configured 10 | integrations. 11 | 12 | ## Exposed information 13 | 14 | * **Margin**: the demodulation signal-to-noise ratio in dB rounded to the nearest 15 | integer value for the last successfully received DevStatusReq command. 16 | * **External power source**: if the device was powered by an external power-source. 17 | * **Battery level unavailable**: if this is set to true, no battery level 18 | is available. 19 | * **Battery level**: battery level as percentage. 20 | 21 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/contribute.md: -------------------------------------------------------------------------------- 1 | # Contribute & source 2 | 3 | ## Links 4 | 5 | - Community support: [https://support.chirpstack.io/](https://support.chirpstack.io/) 6 | - Source repository: [https://github.com/chirpstack/chirpstack-gateway-mesh](https://github.com/chirpstack/chirpstack-gateway-mesh) 7 | - Issue and bug reports: [https://github.com/chirpstack/chirpstack-gateway-mesh/issues](https://github.com/chirpstack/chirpstack-gateway-mesh/issues) 8 | - [RAKwireless Gateway Mesh quickstart documentation](https://learn.rakwireless.com/hc/en-us/articles/26826770321559-How-To-Set-Up-Gateway-Mesh-Quick-Start-Using-ChirpStackOS-on-RAK-Gateways) 9 | 10 | ## Building from source 11 | 12 | For instructions on building the ChirpStack Gateway Mesh source-code from source, 13 | please refer to the `README.md` in the source repository: 14 | 15 | [https://github.com/chirpstack/chirpstack-gateway-mesh/](https://github.com/chirpstack/chirpstack-gateway-mesh/) 16 | -------------------------------------------------------------------------------- /src/chirpstack/streams/events.md: -------------------------------------------------------------------------------- 1 | # Integration events 2 | 3 | The events stream exposes [Integration Events](../integrations/events.md). 4 | This stream can be used to build external integrations, for example using the 5 | [chirpstack_integration](https://crates.io/crates/chirpstack-integration) crate. 6 | 7 | ## Redis keys 8 | 9 | This stream is published under the following Redis keys: 10 | 11 | * `device:[DEV_EUI]:stream:event` (per DevEUI stream) 12 | * `device:stream:event` (global stream) 13 | 14 | ## Data 15 | 16 | This stream exposes all [Integration Events](../integrations/events.md). 17 | 18 | See also [integration.proto](https://github.com/chirpstack/chirpstack/blob/master/api/proto/integration/integration.proto). 19 | 20 | ## Example code 21 | 22 | Example code can be found in the [examples](https://github.com/chirpstack/chirpstack/tree/master/examples) 23 | directory of the [https://github.com/chirpstack/chirpstack](https://github.com/chirpstack/chirpstack) 24 | repository. 25 | -------------------------------------------------------------------------------- /src/chirpstack-concentratord/contribute.md: -------------------------------------------------------------------------------- 1 | # Contribute & source 2 | 3 | ## Links 4 | 5 | - Community support: [https://support.chirpstack.io/](https://support.chirpstack.io/) 6 | - Source repository: [https://github.com/chirpstack/chirpstack-concentratord](https://github.com/chirpstack/chirpstack-concentratord) 7 | - Issue and bug reports: [https://github.com/chirpstack/chirpstack-concentratord/issues](https://github.com/chirpstack/chirpstack/issues) 8 | 9 | ## Building from source 10 | 11 | The easiest way to get started is by using the provided 12 | [docker-compose](https://docs.docker.com/compose/) environment. This environment 13 | comes with all dependencies pre-installed. To start a bash shell within the 14 | docker-compose environment, execute the following command from the root of 15 | this project: 16 | 17 | ```bash 18 | make devshell 19 | ``` 20 | 21 | For a list of available make commands that can be executed, please consult 22 | the `Makefile` that can be found in the root of each component. 23 | -------------------------------------------------------------------------------- /src/chirpstack/features/rejoin.md: -------------------------------------------------------------------------------- 1 | # Rejoin configuration 2 | 3 | ChirpStack supports the handling and configuration of rejoin-requests for 4 | LoRaWAN® 1.1.x devices. 5 | Using a rejoin-request, a device is able to request the network-server to 6 | re-activate, without being 'disconnected' until receiving the activation. 7 | In other words, when it doesn't receive a new activation, the device will 8 | continue to use the old security context. 9 | 10 | With the rejoin-request, it is possible to reset the device context 11 | including all radio parameters (device address, frame counters, session-keys, 12 | radio parameters, ...) restore a lost session context or rekey a device 13 | (device address, session-keys and frame-counters). 14 | 15 | ## Rejoin interval 16 | 17 | ChirpStack supports configuring devices so that they will send a rejoin-request 18 | based on a time and / or frame-counter based interval. 19 | 20 | For more details on rejoin-requests, please refer to the LoRaWAN specification. 21 | -------------------------------------------------------------------------------- /src/chirpstack/streams/backend-interfaces.md: -------------------------------------------------------------------------------- 1 | # Backend Interfaces API 2 | 3 | The Backend Interfaces API stream exposes the Backend Interfaces requests 4 | and responses (both from and to an external server). This includes: 5 | 6 | * Passive Roaming related API calls 7 | * Join Server related API calls 8 | 9 | ## Redis key 10 | 11 | This stream is published under the `backend_interfaces:stream:request` Redis key. 12 | 13 | ## Data 14 | 15 | This stream exposes: 16 | 17 | * Sender / Receiver ID 18 | * Timestamp 19 | * Transaction ID 20 | * Message-type 21 | * Result code 22 | * Request and response body 23 | * Request error 24 | 25 | See also [backend_interfaces.proto](https://github.com/chirpstack/chirpstack/blob/master/api/proto/stream/backend_interfaces.proto). 26 | 27 | ## Example code 28 | 29 | Example code can be found in the [examples](https://github.com/chirpstack/chirpstack/tree/master/examples) 30 | directory of the [https://github.com/chirpstack/chirpstack](https://github.com/chirpstack/chirpstack) 31 | repository. -------------------------------------------------------------------------------- /src/chirpstack-mqtt-forwarder/downloads.md: -------------------------------------------------------------------------------- 1 | # Downloads 2 | 3 | For gateway specific packages, please refer to the [Installation](./install/index.md) 4 | instructions for your gateway model. 5 | 6 | ## Binaries 7 | 8 | | File name | Type | OS | Arch | 9 | | --------- | ---- | -- | ---- | 10 | | [chirpstack-mqtt-forwarder_{{mqtt_forwarder_version}}_linux_amd64.tar.gz](https://artifacts.chirpstack.io/downloads/chirpstack-mqtt-forwarder/chirpstack-mqtt-forwarder_{{mqtt_forwarder_version}}_linux_amd64.tar.gz) | .tar.gz | Linux | amd64 | 11 | | [chirpstack-mqtt-forwarder_{{mqtt_forwarder_version}}_linux_armv7hf.tar.gz](https://artifacts.chirpstack.io/downloads/chirpstack-mqtt-forwarder/chirpstack-mqtt-forwarder_{{mqtt_forwarder_version}}_linux_armv7hf.tar.gz) | .tar.gz | Linux | armv7 | 12 | | [chirpstack-mqtt-forwarder_{{mqtt_forwarder_version}}_linux_arm64.tar.gz](https://artifacts.chirpstack.io/downloads/chirpstack-mqtt-forwarder/chirpstack-mqtt-forwarder_{{mqtt_forwarder_version}}_linux_arm64.tar.gz) | .tar.gz | Linux | arm64 | 13 | -------------------------------------------------------------------------------- /landing/css/style.css: -------------------------------------------------------------------------------- 1 | #chirpstack-header { 2 | position: fixed; 3 | top: 0; 4 | left: 0; 5 | width: 100%; 6 | height: 64px; 7 | box-shadow: 0 0 10px 0 #ccc; 8 | padding: 16px; 9 | z-index: 2; 10 | background: white; 11 | } 12 | 13 | .chirpstack-logo { 14 | float: left; 15 | height: 32px; 16 | } 17 | 18 | .chirpstack-links { 19 | margin-top: 7px; 20 | font-size: 16px; 21 | float: right; 22 | font-family: "Open Sans", sans-serif; 23 | } 24 | 25 | .chirpstack-buttons { 26 | margin-top: 5px; 27 | float: right; 28 | margin-left: 32px; 29 | } 30 | 31 | .chirpstack-links a { 32 | color: black; 33 | text-decoration: none; 34 | } 35 | 36 | .chirpstack-links a:hover { 37 | text-decoration: underline; 38 | } 39 | 40 | .container { 41 | padding-top: 128px; 42 | z-index: 0; 43 | padding-bottom: 64px; 44 | } 45 | 46 | .row { 47 | margin-top: 32px; 48 | } 49 | 50 | h2 { 51 | margin-top: 32px; 52 | } 53 | 54 | h3 { 55 | margin-top: 32px; 56 | } 57 | 58 | .chirpstack-supported-by img { 59 | max-height: 135px; 60 | max-width: 350px; 61 | } -------------------------------------------------------------------------------- /src/chirpstack/features/gateway-management.md: -------------------------------------------------------------------------------- 1 | # Gateway management 2 | 3 | ChirpStack has support for managing gateways. Gateways can be created in the web-interface or 4 | using the API. 5 | 6 | ## Gateway location 7 | 8 | The (last known) location of the gateway will be stored in the database. If 9 | the gateway is equipped with a GPS, its location will be automatically updated 10 | after every stats update in case it has changed. Else, it can be manually set 11 | when creating or updating the gateway. 12 | 13 | ## Gateway re-configuration 14 | 15 | If the [Concentratord](../../chirpstack-concentratord/index.md) is installed on the gateway 16 | as packet-forwarder, ChirpStack will automatically configure the channel-plan 17 | of the gateway and will keep it up-to-date with the gateway channels as configured 18 | in the ChirpStack region configuration (please refer to the `[[regions.gateways.channels]]` 19 | configuration option). See [region_eu868.toml](https://github.com/chirpstack/chirpstack/blob/master/chirpstack/configuration/region_eu868.toml) 20 | as example. 21 | -------------------------------------------------------------------------------- /src/chirpstack/features/device-activation.md: -------------------------------------------------------------------------------- 1 | # Device activation 2 | 3 | ## Over The Air Activation (OTAA) 4 | 5 | For OTAA devices, it is possible to configure the root-keys within ChirpStack 6 | or use an external join-server. In the latter case, you must configure the 7 | join-server(s) in the ChirpStack [Configuration](../configuration.md) file. 8 | 9 | If ChirpStack receives an OTAA join-request with a JoinEUI that is configured 10 | in the configuration file, it will forward the join-request to this join-server. 11 | In the other case ChirpStack will use the root-keys that are configured within 12 | ChirpStack, or raise an error if no keys have been configured. 13 | 14 | The Join Server API is specified by the [LoRaWAN Backend Interfaces](https://www.lora-alliance.org/lorawan-for-developers) 15 | 16 | ## Activation By Personalization (ABP) 17 | 18 | ChirpStack also support ABP devices. In this case devices must be activated 19 | through the web-interface or API by entering the session-keys. Once activated, 20 | ChirpStack will handle these devices the same as OTAA activated devices. 21 | -------------------------------------------------------------------------------- /examples/chirpstack/api/python/enqueue_downlink.py: -------------------------------------------------------------------------------- 1 | import os 2 | import sys 3 | 4 | import grpc 5 | from chirpstack_api import api 6 | 7 | # Configuration. 8 | 9 | # This must point to the API interface. 10 | server = "localhost:8080" 11 | 12 | # The DevEUI for which you want to enqueue the downlink. 13 | dev_eui = "0101010101010101" 14 | 15 | # The API token (retrieved using the web-interface). 16 | api_token = "..." 17 | 18 | if __name__ == "__main__": 19 | # Connect without using TLS. 20 | channel = grpc.insecure_channel(server) 21 | 22 | # Device-queue API client. 23 | client = api.DeviceServiceStub(channel) 24 | 25 | # Define the API key meta-data. 26 | auth_token = [("authorization", "Bearer %s" % api_token)] 27 | 28 | # Construct request. 29 | req = api.EnqueueDeviceQueueItemRequest() 30 | req.queue_item.confirmed = False 31 | req.queue_item.data = bytes([0x01, 0x02, 0x03]) 32 | req.queue_item.dev_eui = dev_eui 33 | req.queue_item.f_port = 10 34 | 35 | resp = client.Enqueue(req, metadata=auth_token) 36 | 37 | # Print the downlink id 38 | print(resp.id) 39 | -------------------------------------------------------------------------------- /src/chirpstack-concentratord/api/commands.md: -------------------------------------------------------------------------------- 1 | # Commands 2 | 3 | Commands can be sent to Concentratord using a [ZeroMQ REQ](http://zguide.zeromq.org/page:all#toc52) 4 | socket. The first data-frame holds the command type (string), the second 5 | data-frame holds the command payload encoded using Protobuf. 6 | 7 | ## `gateway_id` 8 | 9 | Request the Gateway ID (the data-frame is empty). The response is the 8byte 10 | Gateway ID. 11 | 12 | ## `down` 13 | 14 | Request to enqueue the given frame for downlink (`DownlinkFrame` Protobuf 15 | message). A downlink command is responded by a `DownlinkTXAck` message. 16 | 17 | ## `config` 18 | 19 | Request to re-configure the channel-configuration (`GatewayConfiguration` 20 | Protobuf message). The response is empty. 21 | 22 | The re-configuration happens in-memory only. This means that when 23 | Concentratord is restarted, it will revert to the configuration as specified 24 | in the configuration file. This allows for restarting Concentratord in case of 25 | a re-configuration error (in which case the process will terminate) and 26 | reverting back to the original configuration. 27 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/integrations/mqtt.md: -------------------------------------------------------------------------------- 1 | # MQTT 2 | 3 | The Generic MQTT authentication type provides a generic MQTT client where most 4 | of the connection parameters can be configured using the 5 | [Configuration file](../configuration.md). This is the 6 | recommended authentication type for most MQTT brokers. 7 | 8 | ## Consuming data 9 | 10 | To receive events from your gateways, you need to subscribe to its MQTT topic(s). 11 | For debugging, you can use a (command-line) tool like `mosquitto_sub` 12 | which is part of the [Mosquitto](http://mosquitto.org/) MQTT broker. 13 | 14 | Use ``+`` for a single-level wildcard, ``#`` for a multi-level wildcard. 15 | Examples: 16 | 17 | ```bash 18 | # show data from all gateways 19 | mosquitto_sub -t "+/gateway/#" -v 20 | 21 | # show all events and commands for the given gateway ID 22 | mosquitto_sub -t "+/gateway/0101010101010101/#" -v 23 | 24 | # show all events for the given gateway ID 25 | mosquitto_sub -t "+/gateway/0101010101010101/event/+" -v 26 | 27 | # show all commands for the given gateway ID 28 | mosquitto_sub -t "+/gateway/0101010101010101/command/+" -v 29 | ``` 30 | -------------------------------------------------------------------------------- /src/index.md: -------------------------------------------------------------------------------- 1 | # The ChirpStack project 2 | 3 | ChirpStack is an open-source LoRaWAN Network Server which can be used to 4 | setup private or public LoRaWAN networks. ChirpStack provides a web-interface 5 | for the management of gateways, devices and tenants as well to setup data 6 | integrations with the major cloud providers, databases and services commonly 7 | used for handling device data. ChirpStack provides a gRPC based API that can 8 | be used to integrate or extend ChirpStack. 9 | 10 | ### Supported regions 11 | 12 | - [x] AS923, AS923-2, AS923-3, AS923-4 13 | - [x] AU915 14 | - [x] CN470 15 | - [x] CN779 16 | - [x] EU433 17 | - [x] EU868 18 | - [x] IN865 19 | - [x] KR920 20 | - [x] RU864 21 | - [x] US915 22 | - [x] ISM2400 (LoRaWAN 2.4 GHz) 23 | 24 | ### Device classes 25 | 26 | - [x] Class A 27 | - [x] Class B unicast & multicast 28 | - [x] Class C unicast & multicast 29 | 30 | ### LoRaWAN versions 31 | 32 | - [x] LoRaWAN 1.0.0 33 | - [x] LoRaWAN 1.0.1 34 | - [x] LoRaWAN 1.0.2 35 | - [x] LoRaWAN 1.0.3 36 | - [x] LoRaWAN 1.0.4 37 | - [x] LoRaWAN 1.1.0 38 | 39 | ### Regional parameter revisions 40 | 41 | - [x] RP002-1.0.0 42 | - [x] RP002-1.0.1 43 | - [x] RP002-1.0.2 44 | - [x] RP002-1.0.3 45 | -------------------------------------------------------------------------------- /examples/chirpstack/integrations/azure-service-bus/go/go.mod: -------------------------------------------------------------------------------- 1 | module example 2 | 3 | go 1.17 4 | 5 | require ( 6 | github.com/Azure/azure-service-bus-go v0.11.5 7 | github.com/chirpstack/chirpstack/api/go/v4 v4.0.0-test.18 8 | google.golang.org/protobuf v1.28.1 9 | ) 10 | 11 | require ( 12 | github.com/Azure/azure-amqp-common-go/v3 v3.2.1 // indirect 13 | github.com/Azure/go-amqp v0.16.4 // indirect 14 | github.com/Azure/go-autorest v14.2.0+incompatible // indirect 15 | github.com/Azure/go-autorest/autorest v0.11.18 // indirect 16 | github.com/Azure/go-autorest/autorest/adal v0.9.13 // indirect 17 | github.com/Azure/go-autorest/autorest/date v0.3.0 // indirect 18 | github.com/Azure/go-autorest/autorest/to v0.4.0 // indirect 19 | github.com/Azure/go-autorest/logger v0.2.1 // indirect 20 | github.com/Azure/go-autorest/tracing v0.6.0 // indirect 21 | github.com/devigned/tab v0.1.1 // indirect 22 | github.com/form3tech-oss/jwt-go v3.2.2+incompatible // indirect 23 | github.com/klauspost/compress v1.10.3 // indirect 24 | github.com/mitchellh/mapstructure v1.3.3 // indirect 25 | golang.org/x/crypto v0.0.0-20211115234514-b4de73f9ece8 // indirect 26 | nhooyr.io/websocket v1.8.7 // indirect 27 | ) 28 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/install/debian-ubuntu.md: -------------------------------------------------------------------------------- 1 | # Debian / Ubuntu 2 | 3 | ## ChirpStack Debian / Ubuntu repository 4 | 5 | Please see the [Downloads](../downloads.md) page for information on how to 6 | activate the Debian / Ubuntu package repository. 7 | 8 | ## Install ChirpStack Gateway Bridge 9 | 10 | In order to install ChirpStack Gateway Bridge, execute the following command: 11 | 12 | ```bash 13 | sudo apt install chirpstack-gateway-bridge 14 | ``` 15 | 16 | This will setup an user and group, create start scripts for systemd or init.d 17 | (this depends on your version of Debian / Ubuntu). The configuration file is 18 | located at `/etc/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml`. 19 | 20 | ## Starting ChirpStack Gateway Bridge 21 | 22 | ```bash 23 | sudo systemctl [start|stop|restart|status] chirpstack-gateway-bridge 24 | ``` 25 | 26 | ## ChirpStack Gateway Bridge log output 27 | 28 | Now you've setup ChirpStack Gateway Bridge and your gateway is configured to forward 29 | it's data to it, it is a good time to verify that data is being received. 30 | To view the ChirpStack Gateway Bridge logs, execute the following command: 31 | 32 | ```bash 33 | journalctl -u chirpstack-gateway-bridge -f -n 50 34 | ``` 35 | -------------------------------------------------------------------------------- /src/chirpstack/streams/frames.md: -------------------------------------------------------------------------------- 1 | # LoRaWAN frames 2 | 3 | The frames stream exposes the raw LoRaWAN® payloads. 4 | This stream can be used for monitoring purposes. **Note:** this stream 5 | should never be used for building application-integrations. For this 6 | you should always use the [Events stream](./events.md). 7 | 8 | ## Redis keys 9 | 10 | This stream is published under the following Redis keys: 11 | 12 | * Frames received / sent by the gateways: 13 | * `gw:[GATEWAY_ID]:stream:frame` (per Gateway ID stream) 14 | * `gw:stream:frame` (global stream) 15 | * Authenticated frames: 16 | * `device:[DEV_EUI]:stream:frame` (per DevEUI stream) 17 | * `device:stream:frame` (global stream) 18 | 19 | ## Data 20 | 21 | This stream exposes the [UplinkFrame](https://github.com/chirpstack/chirpstack/blob/master/api/proto/gw/gw.proto#L473) 22 | and [DownlinkFrame](https://github.com/chirpstack/chirpstack/blob/master/api/proto/gw/gw.proto#L501) 23 | messages. 24 | 25 | ## Example code 26 | 27 | Example code can be found in the [examples](https://github.com/chirpstack/chirpstack/tree/master/examples) 28 | directory of the [https://github.com/chirpstack/chirpstack](https://github.com/chirpstack/chirpstack) 29 | repository. 30 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/amqp.md: -------------------------------------------------------------------------------- 1 | # AMQP / RabbitMQ 2 | 3 | The [AMQP](https://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol) / 4 | [RabbitMQ](https://www.rabbitmq.com/) integration publishes events to an AMQP 5 | routing-key. By creating one or multiple bindings to one or multiple queues, 6 | it is possible to subscribe to all data, or just a sub-set. 7 | 8 | ## Activating integration 9 | 10 | This integration must be configured in the [Configuration](../configuration.md) file. 11 | 12 | ### Enable integration 13 | 14 | In the configuration file: 15 | 16 | ```toml 17 | [integration] 18 | enabled = [ 19 | "mqtt", 20 | ] 21 | ``` 22 | 23 | Your enabled line may look slightly different. Add `"amqp"`` to the list. In 24 | this case, the modified line should appear as enabled=["mqtt", "amqp"]. 25 | 26 | ### Configuration 27 | 28 | You must also add / update the `[integration.amqp]` section with the URL of 29 | the AMQP broker URL and the routing-key. Example: 30 | 31 | ```toml 32 | # AMQP / RabbitMQ integration configuration. 33 | {%raw %}[integration.amqp] 34 | url="amqp://guest:guest@localhost:5672" 35 | event_routing_key="application.{{application_id}}.device.{{dev_eui}}.event.{{event}}" 36 | json=true{% endraw %} 37 | ``` 38 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/image-types.md: -------------------------------------------------------------------------------- 1 | # Image types 2 | 3 | ## Raspberry Pi 4 | 5 | ### Base 6 | 7 | The ChirpStack Gateway OS **Base** image provides all the components to use 8 | the hardware has a LoRa® gateway. This includes: 9 | 10 | - [ChirpStack Concentratord](../chirpstack-concentratord/index.md) 11 | - [ChirpStack MQTT Forwarder](../chirpstack-mqtt-forwarder/index.md) 12 | - [ChirpStack UDP Forwarder](https://github.com/chirpstack/chirpstack-udp-forwarder/) 13 | 14 | The **Base** image provides a web-interface for configuring all ChirpStack 15 | components, network (Wi-Fi, ethernet, firewall, ...) and system settings. 16 | 17 | ![gateway-config](gateway-config.png) 18 | 19 | ### Full 20 | 21 | The ChirpStack Gateway OS **Full** image contains everything that is included 22 | with the **Base** image, but is also bundled with: 23 | 24 | * [ChirpStack LoRaWAN Network Server](../chirpstack/index.md) 25 | * *[NodeRED](https://nodered.org/) 26 | 27 | This image is intended to provide an easy-to-setup Gateway + Network Server 28 | solution for prototyping and testing. 29 | 30 | ![applications](applications.png) 31 | 32 | ## Other targets 33 | 34 | For other targets, only a single ChirpStack Gateway OS image exists matching 35 | the gateway architecture. 36 | -------------------------------------------------------------------------------- /src/chirpstack/use/gateways.md: -------------------------------------------------------------------------------- 1 | # Gateways 2 | 3 | A tenant is able to manage its own set of gateways. Please note that 4 | this feature might be unavailable when the tenant is configured without 5 | gateway support. 6 | 7 | That a gateway belongs to a given tenant does not mean that the usage 8 | of a gateway is limited to the tenant. Every device in the whole network 9 | will be able to communicate using the gateway. The tenant will be 10 | responsible however for managing the gateway details (e.g. name, location) 11 | and will be able to see its statistics. 12 | 13 | ## Statistics 14 | 15 | Gateway statistics are based on the aggregated values sent by the gateway / 16 | packet-forwarder. In case no statistics are visible, it could mean that the 17 | gateway is incorrectly configured. 18 | 19 | The statistics grahps display the following values over the past month: 20 | * __Received__ displays the number of Rx packets received from LoRa devices by the gateway. 21 | * __Transmitted__ shows how many Tx packets have been sent from the gateway over LoRa. 22 | * The __/frequency__ graphs display the distribution of packets on each frequency (Hz). 23 | * The __/DR__ graphs show the distribution of packets for each data rate. 24 | * __TX packets / status__ shows the distribution of the Tx packets' status. 25 | -------------------------------------------------------------------------------- /examples/chirpstack/integrations/gcp-pub-sub/go/go.mod: -------------------------------------------------------------------------------- 1 | module example 2 | 3 | go 1.17 4 | 5 | require ( 6 | cloud.google.com/go/pubsub v1.24.0 7 | github.com/chirpstack/chirpstack/api/go/v4 v4.0.0-test.18 8 | google.golang.org/api v0.92.0 9 | google.golang.org/protobuf v1.28.1 10 | ) 11 | 12 | require ( 13 | cloud.google.com/go v0.102.1 // indirect 14 | cloud.google.com/go/compute v1.7.0 // indirect 15 | cloud.google.com/go/iam v0.3.0 // indirect 16 | github.com/golang/groupcache v0.0.0-20200121045136-8c9f03a8e57e // indirect 17 | github.com/golang/protobuf v1.5.2 // indirect 18 | github.com/google/go-cmp v0.5.8 // indirect 19 | github.com/googleapis/enterprise-certificate-proxy v0.1.0 // indirect 20 | github.com/googleapis/gax-go/v2 v2.4.0 // indirect 21 | go.opencensus.io v0.23.0 // indirect 22 | golang.org/x/net v0.0.0-20220624214902-1bab6f366d9e // indirect 23 | golang.org/x/oauth2 v0.0.0-20220622183110-fd043fe589d2 // indirect 24 | golang.org/x/sync v0.0.0-20220601150217-0de741cfad7f // indirect 25 | golang.org/x/sys v0.0.0-20220624220833-87e55d714810 // indirect 26 | golang.org/x/text v0.3.7 // indirect 27 | google.golang.org/appengine v1.6.7 // indirect 28 | google.golang.org/genproto v0.0.0-20220624142145-8cd45d7dbd1f // indirect 29 | google.golang.org/grpc v1.47.0 // indirect 30 | ) 31 | -------------------------------------------------------------------------------- /src/gateway-configuration/matchx.md: -------------------------------------------------------------------------------- 1 | # MatchX 2 | 3 | ## Matchbox gateway 4 | 5 | * [Product detail page](https://www.matchx.io/hardware/) 6 | 7 | The MatchX Matchbox is an OpenWRT / Lede 8 | base LoRa® gateway, which by default sends its data to the MatchX hosted network-server 9 | (which is based on the ChirpStack open-source LoRaWAN® Network Server Stack). 10 | By default it connects to the MatchX backend over a VPN connection. 11 | 12 | To connect the gateway to your own environment: 13 | 14 | * Power on the gateway and follow the MatchX provided manual to setup the 15 | wifi connection (in case needed). 16 | 17 | * Create a MatchX account and register the gateway. 18 | 19 | * On the page with the gateway details is a button **Global LoRa Config: [Edit Config]**. 20 | click on this button and scroll down to the bottom where you find the 21 | `server_address` setting. Change this to the IP or hostname on which 22 | your ChirpStack Gateway Bridge instance is listening for UDP packets. 23 | 24 | **Note:** Running the ChirpStack Gateway Bridge on the gateway itself will probably 25 | not work without re-compiling the kernel with FPU emulation. This has not been 26 | tested. In order to get `root` access, you need to contact the MatchX support 27 | for getting the password. 28 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/azure-service-bus.md: -------------------------------------------------------------------------------- 1 | # Azure Service-Bus 2 | 3 | The [Azure Service Bus](https://azure.microsoft.com/en-us/services/service-bus/) 4 | integration publishes all the events to a Service Bus [Topic or Queue](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-messaging-overview) 5 | to which applications can subscribe. 6 | 7 | ## Events 8 | 9 | The Azure Service Bus integration exposes all events as documented by [Event types](events.md). 10 | 11 | ### User properties 12 | 13 | The following user properties are added to each published message: 14 | 15 | * `event` - the event type 16 | * `dev_eui` - the device EUI 17 | * `application_id` - the ChirpStack Application Server application ID 18 | 19 | ## Example code 20 | 21 | The following code example demonstrates how to consume integration events using 22 | an [Azure Service-Bus Queue](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-queues-topics-subscriptions). 23 | 24 | ### Go 25 | 26 | `main.go`: 27 | 28 | ```go 29 | {% raw %}{{#include ../../../examples/chirpstack/integrations/azure-service-bus/go/main.go}}{% endraw %} 30 | ``` 31 | 32 | ### Python 33 | 34 | `main.py`: 35 | 36 | ```python 37 | {% raw %}{{#include ../../../examples/chirpstack/integrations/azure-service-bus/python/main.py}}{% endraw %} 38 | ``` 39 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/use/configuration.md: -------------------------------------------------------------------------------- 1 | # Configuration 2 | 3 | ## Web-interface 4 | 5 | ChirpStack Gateway OS can be configured using the provided web-interface. 6 | To access the web-interface, enter `http://GATEWAY-IP-ADDRESS/` in your 7 | browser. For example if the IP address of your gateway is `192.168.0.1`, 8 | then you need to enter `http://192.168.0.1`. 9 | 10 | The default credentials are: 11 | 12 | * Username: `root` 13 | * Password: _(not set)_ 14 | 15 | ## SSH 16 | 17 | It is also possible to configure the ChirpStack Gateway OS using a CLI 18 | over SSH. Use the following command to SSH into the gateway: 19 | 20 | ``` 21 | ssh root@GATEWAY-IP-ADDRESS 22 | ``` 23 | 24 | ChirpStack Gateway OS uses the OpenWrt [UCI system](https://openwrt.org/docs/guide-user/base-system/uci) for handling configuration. 25 | 26 | To show the current ChirpStack configurations: 27 | 28 | ```bash 29 | uci show chirpstack-concentratord 30 | uci show chirpstack-mqtt-forwarder 31 | uci show chirpstack-udp-forwarder 32 | 33 | # Only for Full images 34 | uci show chirpstack 35 | ``` 36 | 37 | Please refer to the [UCI system](https://openwrt.org/docs/guide-user/base-system/uci) 38 | guide for information about using the UCI configuration system. After modifying 39 | ChirpStack configuration and a `uci commit`, the updated services will be 40 | automatically restarted. 41 | -------------------------------------------------------------------------------- /examples/chirpstack/api/js/enqueue_downlink.js: -------------------------------------------------------------------------------- 1 | const grpc = require("@grpc/grpc-js"); 2 | const device_grpc = require("@chirpstack/chirpstack-api/api/device_grpc_pb"); 3 | const device_pb = require("@chirpstack/chirpstack-api/api/device_pb"); 4 | 5 | // This must point to the ChirpStack API interface. 6 | const server = "localhost:8080"; 7 | 8 | // The DevEUI for which we want to enqueue the downlink. 9 | const devEui = "0101010101010101"; 10 | 11 | // The API token (can be obtained through the ChirpStack web-interface). 12 | const apiToken = "..."; 13 | 14 | 15 | // Create the client for the DeviceService. 16 | const deviceService = new device_grpc.DeviceServiceClient( 17 | server, 18 | grpc.credentials.createInsecure(), 19 | ); 20 | 21 | // Create the Metadata object. 22 | const metadata = new grpc.Metadata(); 23 | metadata.set("authorization", "Bearer " + apiToken); 24 | 25 | // Enqueue downlink. 26 | const item = new device_pb.DeviceQueueItem(); 27 | item.setDevEui(devEui); 28 | item.setFPort(10); 29 | item.setConfirmed(false); 30 | item.setData(new Uint8Array([1, 2, 3])); 31 | 32 | const enqueueReq = new device_pb.EnqueueDeviceQueueItemRequest(); 33 | enqueueReq.setQueueItem(item); 34 | 35 | deviceService.enqueue(enqueueReq, metadata, (err, resp) => { 36 | if (err !== null) { 37 | console.log(err); 38 | return; 39 | } 40 | 41 | console.log("Downlink has been enqueued with id: " + resp.getId()); 42 | }); 43 | -------------------------------------------------------------------------------- /examples/chirpstack/api/csharp/Program.cs: -------------------------------------------------------------------------------- 1 | using Chirpstack.Api; 2 | using Google.Protobuf; 3 | using Grpc.Core; 4 | using Grpc.Net.Client; 5 | using Grpc.Net.Client.Web; 6 | 7 | // Configuration. 8 | 9 | // This must point to the API interface. 10 | var server = "localhost:8080"; 11 | 12 | // The DevEUI for which you want to enqueue the downlink. 13 | var devEui = "0101010101010101"; 14 | 15 | // The API token (retrieved using the web-interface). 16 | var apiToken = "..."; 17 | 18 | // Connect without using TLS. 19 | using var channel = GrpcChannel.ForAddress( 20 | address: server, 21 | channelOptions: new GrpcChannelOptions() 22 | { 23 | HttpHandler = new GrpcWebHandler(new HttpClientHandler()), 24 | Credentials = ChannelCredentials.Insecure, 25 | } 26 | ); 27 | 28 | // Device-queue API client. 29 | var client = new DeviceService.DeviceServiceClient(channel); 30 | 31 | // Define the API key meta-data. 32 | var authToken = new Metadata 33 | { 34 | { "Authorization", "Bearer " + apiToken }, 35 | }; 36 | 37 | // Construct request. 38 | var req = new EnqueueDeviceQueueItemRequest() 39 | { 40 | QueueItem = new DeviceQueueItem() 41 | { 42 | Confirmed = false, 43 | Data = ByteString.CopyFrom(0x01, 0x02, 0x03), 44 | DevEui = devEui, 45 | FPort = 10, 46 | }, 47 | }; 48 | 49 | var resp = await client.EnqueueAsync(req, headers: authToken); 50 | 51 | // Print the downlink id. 52 | Console.WriteLine(resp.Id); 53 | Console.ReadKey(); 54 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/aws-sns.md: -------------------------------------------------------------------------------- 1 | # AWS SNS 2 | 3 | The [Simple Notification Service (SNS)](https://aws.amazon.com/sns/) integration 4 | publishes all the events to a SNS Topic to which other applications or AWS 5 | services can subscribe for further processing. 6 | 7 | ## Events 8 | 9 | The AWS Simple Notification Service integration exposes all events as 10 | documented by [Event types](events.md). 11 | 12 | ### Message attributes 13 | 14 | The following message attributes are added to each published message: 15 | 16 | * `event` - the event type 17 | * `dev_eui` - the device EUI 18 | * `application_id` - the ChirpStack Application Server application ID 19 | 20 | ## Example code 21 | 22 | The following code example demonstrates how to consume integration events using 23 | an [AWS SQS](https://aws.amazon.com/sqs/) subscription. 24 | 25 | !!! important 26 | Make sure the _Enable raw message delivery_ option is enabled on the subscription. 27 | If not enabled, the SQS messages will not have the expected attributes. 28 | 29 | ### Go 30 | 31 | `main.go`: 32 | 33 | ```go 34 | {% raw %}{{#include ../../../examples/chirpstack/integrations/aws-sns/go/main.go}}{% endraw %} 35 | ``` 36 | 37 | ### Python 38 | 39 | Please refer to the [Boto3 Configuration](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) 40 | for setting up the API credentials. 41 | 42 | `main.py`: 43 | 44 | ```python 45 | {% raw %}{{#include ../../../examples/chirpstack/integrations/aws-sns/python/main.py}}{% endraw %} 46 | ``` 47 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/gcp-pub-sub.md: -------------------------------------------------------------------------------- 1 | # GCP Pub/Sub 2 | 3 | The [Google Cloud Platform](https://cloud.google.com/) [Pub/Sub](https://cloud.google.com/pubsub/) 4 | integration publishes all the events to a configurable GCP Pub/Sub topic. 5 | Using the GCP console (or APIs) you are able to create one or multiple Pub/Sub 6 | subscriptions, for integrating this with your application(s) or store the data 7 | in one of the storage options provided by the Google Cloud Platform. 8 | 9 | ## Events 10 | 11 | The GCP Pub/Sub integration exposes all events as documented by [Event types](events.md). 12 | 13 | ### Attributes 14 | 15 | The following attributes are added to each Pub/Sub message: 16 | 17 | * `event`: the event type 18 | * `devEui`: the device EUI to which the event relates 19 | 20 | ## Example code 21 | 22 | The following code example demonstrates how to consume integration events using 23 | a [GCP Pub/Sub Subscription](https://cloud.google.com/pubsub/docs/overview). 24 | 25 | ### Go 26 | 27 | `main.go`: 28 | 29 | ```go 30 | {% raw %}{{#include ../../../examples/chirpstack/integrations/gcp-pub-sub/go/main.go}}{% endraw %} 31 | ``` 32 | 33 | ### Python 34 | 35 | Please refer to the [Setting up authentication](https://cloud.google.com/pubsub/docs/reference/libraries#client-libraries-install-python) 36 | section for creating a service-account and setting up the credentials. 37 | 38 | `main.py`: 39 | 40 | ```python 41 | {% raw %}{{#include ../../../examples/chirpstack/integrations/gcp-pub-sub/python/main.py}}{% endraw %} 42 | ``` 43 | -------------------------------------------------------------------------------- /theme/css/chirpstack.css: -------------------------------------------------------------------------------- 1 | @media only screen and (max-width: 768px) { 2 | .chirpstack-header { 3 | display: none; 4 | } 5 | } 6 | 7 | @media only screen and (min-width: 768px) { 8 | .chirpstack-header { 9 | position: fixed; 10 | top: 0; 11 | left: 0; 12 | width: 100%; 13 | height: 32px; 14 | background-color: white; 15 | box-shadow: 0 0 10px 0 #ccc; 16 | padding: 16px; 17 | z-index: 999; 18 | } 19 | 20 | .chirpstack-logo { 21 | float: left; 22 | height: 32px; 23 | } 24 | 25 | .chirpstack-links { 26 | margin-top: 7px; 27 | font-size: 16px; 28 | margin-right: 32px; 29 | float: right; 30 | } 31 | 32 | .chirpstack-buttons { 33 | margin-top: 5px; 34 | float: right; 35 | margin-right: 32px; 36 | } 37 | 38 | .sidebar { 39 | margin-top: 64px; 40 | } 41 | 42 | .page-wrapper { 43 | margin-top: 64px; 44 | } 45 | 46 | .nav-chapters { 47 | top: 64px; 48 | } 49 | 50 | .chirpstack-links a { 51 | color: black; 52 | text-decoration: none; 53 | } 54 | 55 | .chirpstack-links a:hover { 56 | text-decoration: underline; 57 | } 58 | 59 | #menu-bar.sticky, 60 | .js #menu-bar-hover-placeholder:hover+#menu-bar, 61 | .js #menu-bar:hover, 62 | .js.sidebar-visible #menu-bar { 63 | top: 64px !important; 64 | } 65 | 66 | #menu-bar-hover-placeholder { 67 | top: 64px; 68 | } 69 | 70 | html { 71 | scroll-padding: 64px; 72 | } 73 | } 74 | 75 | #theme-toggle { 76 | display: none; 77 | } 78 | 79 | .sponsors img { 80 | max-height: 135px; 81 | max-width: 300px; 82 | margin-left: 25px; 83 | margin-right: 25px; 84 | } 85 | -------------------------------------------------------------------------------- /src/guides/pilot-things.md: -------------------------------------------------------------------------------- 1 | # Pilot Things integration 2 | 3 | [Pilot Things](https://www.pilot-things.com/) is a platform to manage, visualize, 4 | automate and integrate your IoT device fleet. After following this guide, ChirpStack 5 | will be setup to forward device data to [Pilot Things](https://www.pilot-things.com/). 6 | 7 | ## Integrate with Pilot Things 8 | 9 | ### Get Auth Token 10 | 11 | In order to let ChirpStack push data to your Pilot Things server, you need 12 | to obtain a Pilot Things _Authentication Token_. To obtain an authentication 13 | token, send an email to [contact@pilot-things.com](mailto:contact@pilot-things.com). 14 | 15 | ### Setup Pilot Things integration 16 | 17 | In the ChirpStack web-interface, navigate to the Application you want to add 18 | the integration. Find the Pilot Things integration under **Integration**, 19 | then click **Add**. Fill in the two required fields: 20 | 21 | * Pilot Things server: This is the URL you normally would use to access the Pilot Things user interface. For example, https://kerlink.pilot-things.com/. 22 | * Authentication token: This is the token you got in the previous step 23 | 24 | ## Validate integration 25 | 26 | If you completed all the steps, then Pilot Things is ready to receive uplink 27 | data and ChirpStack is configured to forward data for your Device, using th 28 | _Authorization Token_ for authentication. 29 | 30 | The last step is to let your device send some data and validate that this data 31 | is received by Pilot Things. You will find this data under the _Activity_ tab 32 | when navigating to the Device within Pilot Things. 33 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/integrations/azure-iot-hub.md: -------------------------------------------------------------------------------- 1 | # Azure IoT Hub 2 | 3 | The Azure [IoT Hub](https://azure.microsoft.com/en-us/services/iot-hub/) 4 | authentication thype must be used when connecting with the 5 | [IoT Hub MQTT interface](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-mqtt-support). 6 | 7 | ## Limitations 8 | 9 | * As you need to setup the device ID (in this case the device is the gateway) 10 | when provisioning the device (LoRa® Gateway) in Cloud IoT Core, 11 | this does not allow to connect multiple LoRa Gateways to a single ChirpStack Gateway 12 | Bridge instance. 13 | 14 | ## Conventions 15 | 16 | ### Device ID naming 17 | 18 | The IoT Hub Device ID must match the Gateway ID (e.g. `0102030405060708`). 19 | It must be entered in lowercase (the IoT Hub Device ID is case-sensitive). 20 | 21 | ### MQTT topics 22 | 23 | When the Azure IoT Hub authentication type has been configured, ChirpStack Gateway 24 | Bridge will use MQTT topics which are expected by Azure IoT Hub and will 25 | ignore the MQTT topic configuration from the `chirpstack-gateway-bridge.toml` 26 | configuration file. 27 | 28 | #### Uplink topics 29 | 30 | * `devices/[GATEWAY_ID]/messages/events/up`: uplink frame 31 | * `devices/[GATEWAY_ID]/messages/events/stats`: gateway statistics 32 | * `devices/[GATEWAY_ID]/messages/events/ack`: downlink frame acknowledgements (scheduling) 33 | 34 | #### Downlink topics 35 | 36 | * `devices/[GATEWAY_ID]/messages/devicebound/down`: scheduling downlink frame transmission 37 | * `devices/[GATEWAY_ID]/messages/devicebound/config`: gateway configuration 38 | -------------------------------------------------------------------------------- /src/chirpstack/backends/mqtt.md: -------------------------------------------------------------------------------- 1 | # MQTT 2 | 3 | The MQTT backend is the default backend to communicate with the LoRa® 4 | gateways. If supported by the MQTT broker, it is recommended to make use of a 5 | shared subscription, such that in case of multiple ChirpStack instances, each 6 | gateway event message is delivered to only one ChirpStack instance instead of 7 | all instances. In case this is not supported, please note that the ChirpStack 8 | de-duplication handler will make sure that duplicates are handled correctly. 9 | 10 | ## Architecture 11 | 12 | ```dot process 13 | digraph G { 14 | fontsize=10; 15 | style=filled; 16 | color="#bbdefb"; 17 | node [shape=record, style=filled, color="#e3f2fd", fontsize=10]; 18 | edge [fontsize=9]; 19 | 20 | subgraph cluster_0 { 21 | label="LoRa® Gateway"; 22 | 23 | "chirpstack-gateway-bridge-gw" [label="Packet Forwarder +\nChirpStack Gateway Bridge"]; 24 | } 25 | 26 | subgraph cluster_1 { 27 | label="Cloud / server / VM"; 28 | 29 | "mqtt" [label="MQTT broker"]; 30 | "chirpstack" [label="ChirpStack"]; 31 | } 32 | 33 | 34 | "chirpstack-gateway-bridge-gw" -> "mqtt" [label="REGION/gateway/ID/event/EVENT"]; 35 | "mqtt" -> "chirpstack-gateway-bridge-gw" [label="REGION/gateway/ID/command/COMMAND"]; 36 | 37 | "chirpstack" -> "mqtt" [label="REGION/gateway/ID/command/COMMAND"]; 38 | "mqtt" -> "chirpstack" [label="REGION/gateway/ID/event/EVENT"]; 39 | } 40 | ``` 41 | 42 | **Note:** In the graph above, the ChirpStack Gateway Bridge is 43 | installed on the gateway. It is also possible to install the ChirpStack 44 | Gateway Bridge in the cloud. 45 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/http.md: -------------------------------------------------------------------------------- 1 | # HTTP 2 | 3 | If configured, the HTTP integration will make `POST` requests to the 4 | configured event endpoint or endpoints (multiple URLs can be configured, comma 5 | separated). The `event` URL query parameter indicates the type of the event. 6 | 7 | ## Events 8 | 9 | The HTTP integration exposes all events as documented by [Event types](events.md). 10 | 11 | ## Example code 12 | 13 | The following code examples are for demonstration purposes only to 14 | demonstrate how integration events can be decoded it the most simple way 15 | without taking performance or security in mind. Additional code might be 16 | required for production usage. 17 | 18 | ### Go 19 | 20 | The following code example demonstrates how to implement an HTTP endpoint using 21 | [Go](https://golang.org/) which decodes either a Protobuf or JSON payload. If 22 | you run this example on the same host as ChirpStack, then 23 | the endpoint for the HTTP integration is `http://localhost:8090`. 24 | 25 | `main.go`: 26 | 27 | ```go 28 | {% raw %}{{#include ../../../examples/chirpstack/integrations/http/go/main.go}}{% endraw %} 29 | ``` 30 | 31 | ### Python 32 | 33 | The following code example demonstrates how to implement an HTTP endpoint using 34 | [Python 3](https://www.python.org/) which decodes either a Protobuf or JSON 35 | payload. If you run this example on the same host as ChirpStack, 36 | then the endpoint for the HTTP integration is `http://localhost:8090`. 37 | 38 | `main.py`: 39 | 40 | ```python 41 | {% raw %}{{#include ../../../examples/chirpstack/integrations/http/python/main.py}}{% endraw %} 42 | ``` 43 | -------------------------------------------------------------------------------- /examples/chirpstack/integrations/http/python/main.py: -------------------------------------------------------------------------------- 1 | from http.server import HTTPServer, BaseHTTPRequestHandler 2 | from urllib.parse import urlparse, parse_qs 3 | 4 | from chirpstack_api import integration 5 | from google.protobuf.json_format import Parse 6 | 7 | 8 | class Handler(BaseHTTPRequestHandler): 9 | # True - JSON marshaler 10 | # False - Protobuf marshaler (binary) 11 | json = False 12 | 13 | def do_POST(self): 14 | self.send_response(200) 15 | self.end_headers() 16 | query_args = parse_qs(urlparse(self.path).query) 17 | 18 | content_len = int(self.headers.get('Content-Length', 0)) 19 | body = self.rfile.read(content_len) 20 | 21 | if query_args["event"][0] == "up": 22 | self.up(body) 23 | 24 | elif query_args["event"][0] == "join": 25 | self.join(body) 26 | 27 | else: 28 | print("handler for event %s is not implemented" % query_args["event"][0]) 29 | 30 | def up(self, body): 31 | up = self.unmarshal(body, integration.UplinkEvent()) 32 | print("Uplink received from: %s with payload: %s" % (up.device_info.dev_eui, up.data.hex())) 33 | 34 | def join(self, body): 35 | join = self.unmarshal(body, integration.JoinEvent()) 36 | print("Device: %s joined with DevAddr: %s" % (join.device_info.dev_eui, join.dev_addr)) 37 | 38 | def unmarshal(self, body, pl): 39 | if self.json: 40 | return Parse(body, pl) 41 | 42 | pl.ParseFromString(body) 43 | return pl 44 | 45 | httpd = HTTPServer(('', 8090), Handler) 46 | httpd.serve_forever() 47 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/contribute.md: -------------------------------------------------------------------------------- 1 | # Contribute & source 2 | 3 | ## Links 4 | 5 | - Community support: [https://support.chirpstack.io/](https://support.chirpstack.io/) 6 | - Source repository: [https://github.com/chirpstack/chirpstack-gateway-bridge](https://github.com/chirpstack/chirpstack-gateway-bridge) 7 | - Issue and bug reports: [https://github.com/chirpstack/chirpstack-gateway-bridge/issues](https://github.com/chirpstack/chirpstack-gateway-bridge/issues) 8 | 9 | ## Building from source 10 | 11 | ### With Docker 12 | 13 | The easiest way to get started is by using the provided 14 | [docker-compose](https://docs.docker.com/compose/) environment. To start a bash 15 | shell within the docker-compose environment, execute the following command from 16 | the root of this project: 17 | 18 | ```bash 19 | docker-compose run --rm chirpstack-gateway-bridge bash 20 | ``` 21 | 22 | ### Without Docker 23 | 24 | It is possible to build ChirpStack Gateway Bridge without Docker. However this requires 25 | to install a couple of dependencies (depending your platform, there might be 26 | pre-compiled packages available): 27 | 28 | #### Go 29 | 30 | Make sure you have [Go](https://golang.org/) installed (1.11+). As 31 | ChirpStack Gateway Bridge, the repository must be cloned outside the `$GOPATH`. 32 | 33 | ### Example commands 34 | 35 | A few example commands that you can run: 36 | 37 | ```bash 38 | # install development requirements 39 | make dev-requirements 40 | 41 | # run the tests 42 | make test 43 | 44 | # compile 45 | make build 46 | 47 | # compile snapshot for supported architectures (using goreleaser) 48 | make snapshot 49 | ``` 50 | -------------------------------------------------------------------------------- /src/getting-started/ansible-vagrant.md: -------------------------------------------------------------------------------- 1 | # Ansible and Vagrant 2 | 3 | [Ansible](https://docs.ansible.com/) is an open-source tool for automating 4 | deployment and server-management related steps. ChirpStack provides a so-called 5 | Ansible Playbook which can be used to deploy and configure ChirpStack and 6 | optionally setup TLS certificates. The source of this Playbook, including 7 | additional documentation, can be found at [https://github.com/chirpstack/chirpstack-ansible-playbook](https://github.com/chirpstack/chirpstack-ansible-playbook). 8 | 9 | ## Local VM deployment using Vagrant 10 | 11 | [Vagrant](https://www.vagrantup.com/) is a tool for automating the creation 12 | of virtual machines. It can integrate with Ansible so that it not only create 13 | the VM for you, but also will install and configure ChirpStack. 14 | 15 | After following the instructions documented in the [chirpstack-ansible-playbook](https://github.com/chirpstack/chirpstack-ansible-playbook) 16 | repository, you can create a local test environment running inside a VM using 17 | the following command: 18 | 19 | ```bash 20 | vagrant up 21 | ``` 22 | 23 | As this is using exactly the same Ansible Playbook as for remote deployments, 24 | this can also be used for testing before doing a remote deployment, e.g. 25 | when making modifications to the playbook. 26 | 27 | ## Remote deployment 28 | 29 | Ansible can also be used to perform remote deployments. After following the 30 | steps documented in [chirpstack-ansible-playbook](https://github.com/chirpstack/chirpstack-ansible-playbook), 31 | the following will perform a remote deployment: 32 | 33 | ```bash 34 | ansible-playbook -i inventory deploy.yml 35 | ``` 36 | -------------------------------------------------------------------------------- /src/chirpstack/use/tenants.md: -------------------------------------------------------------------------------- 1 | # Tenants 2 | 3 | A tenant can be used to let organizations or teams manage their 4 | own applications and optionally their own gateways. 5 | 6 | An tenant can have: 7 | 8 | * Device profiles 9 | * Gateways (if allowed) 10 | * Applications and devices 11 | * Users 12 | 13 | ## Device Profiles 14 | 15 | [Device profiles](device-profiles.md) can be created by (tenant) admin users 16 | and can be assigned when creating a [Device](devices.md). 17 | 18 | ## Gateways 19 | 20 | An tenant can manage its own set of gateways. Note that when an tenant 21 | is created by a global administrator, it can decide that an tenant can not 22 | have any gateways. In this case, the gateway option is not available to an 23 | tenant. 24 | 25 | That an tenant is able to manage its own set of gateways does not mean 26 | that the coverage is limited to this set of gateways. Gateways connectivity 27 | will be shared across the whole network. 28 | 29 | ## Applications 30 | 31 | [Applications](applications.md) can be created by (tenant) 32 | admin users and define a group of devices with the same purpose. 33 | 34 | ## Users 35 | 36 | Users can be assigned to a tenant to grant them access to the 37 | tenant. Within the context of that assignment, an user can be an 38 | tenant administrator or a regular user. Please note that only existing users 39 | can be assigned to a tenant. 40 | 41 | ### Tenant administrator 42 | 43 | An tenant administrator is authorized to manage the users assigned 44 | with the tenant and manage the gateways, applications and devices. 45 | 46 | ### Regular user 47 | 48 | Regular users are able to see all data, but are not able to make any 49 | modifications. 50 | -------------------------------------------------------------------------------- /examples/chirpstack/api/go/enqueue_downlink.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "context" 5 | "fmt" 6 | 7 | "github.com/chirpstack/chirpstack/api/go/v4/api" 8 | "google.golang.org/grpc" 9 | ) 10 | 11 | // configuration 12 | var ( 13 | // This must point to the API interface 14 | server = "localhost:8080" 15 | 16 | // The DevEUI for which we want to enqueue the downlink 17 | devEUI = "0101010101010101" 18 | 19 | // The API token (retrieved using the web-interface) 20 | apiToken = "..." 21 | ) 22 | 23 | type APIToken string 24 | 25 | func (a APIToken) GetRequestMetadata(ctx context.Context, url ...string) (map[string]string, error) { 26 | return map[string]string{ 27 | "authorization": fmt.Sprintf("Bearer %s", a), 28 | }, nil 29 | } 30 | 31 | func (a APIToken) RequireTransportSecurity() bool { 32 | return false 33 | } 34 | 35 | func main() { 36 | // define gRPC dial options 37 | dialOpts := []grpc.DialOption{ 38 | grpc.WithBlock(), 39 | grpc.WithPerRPCCredentials(APIToken(apiToken)), 40 | grpc.WithInsecure(), // remove this when using TLS 41 | } 42 | 43 | // connect to the gRPC server 44 | conn, err := grpc.Dial(server, dialOpts...) 45 | if err != nil { 46 | panic(err) 47 | } 48 | 49 | // define the DeviceService client 50 | deviceClient := api.NewDeviceServiceClient(conn) 51 | 52 | // make an Enqueue api call 53 | resp, err := deviceClient.Enqueue(context.Background(), &api.EnqueueDeviceQueueItemRequest{ 54 | QueueItem: &api.DeviceQueueItem{ 55 | DevEui: devEUI, 56 | FPort: 10, 57 | Confirmed: false, 58 | Data: []byte{0x01, 0x02, 0x03}, 59 | }, 60 | }) 61 | if err != nil { 62 | panic(err) 63 | } 64 | 65 | fmt.Printf("The downlink has been enqueued with id: %s\n", resp.Id) 66 | } 67 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/protocol/tlv-payloads.md: -------------------------------------------------------------------------------- 1 | # TLV payloads 2 | 3 | 4 | 5 | | Type | Event / Command | Length | Name | 6 | | ----------- | --------------- | -------- | --------------- | 7 | | 0x00 | Event | Variable | Heartbeat | 8 | | 0x80 - 0xff | Event / Command | Proprietary payloads | 9 | 10 | ## Heartbeat 11 | 12 | Periodically, each Relay Gateway will send a heartbeat message to indicate that 13 | that it is still online. Each Relay Gateway relaying this heartbeat payload will 14 | add its own Relay ID to the path, such that after the Border Gateway has 15 | receive the payload, the full path from sending Relay Gateway to Border Gateway 16 | can be obtained. 17 | 18 | As the payload size is variable and will increment each time it is relayed, caution 19 | must be taken when mixing this event with other events. 20 | 21 | Bytes: 22 | 23 | | 0 - 28 bytes | 24 | | --------------------- | 25 | | Relay path (repeated) | 26 | 27 | ### Relay path 28 | 29 | Bytes (repeated): 30 | 31 | | 4 bytes | 1 byte | 1 byte | 32 | | -------- | ------ | ------ | 33 | | Relay ID | RSSI | SNR | 34 | 35 | Each Relay Gateway relaying the heartbeat payload adds its Relay ID, and the 36 | RSSI and SNR of the received heartbeat payload to the end of the Relay path field. 37 | Initially this field is empty. If the heartbeat payload is not relayed by any 38 | other Relay Gateway, then this field remains empty. 39 | 40 | #### RSSI 41 | 42 | Encoded as RSSIdBm = `-1 x RSSI` 43 | 44 | #### SNR 45 | 46 | Bits: 47 | 48 | | 7..6 | 5..0 | 49 | | ---- | ---- | 50 | | RFU | SNR | 51 | 52 | SNR is a signed integer with a minimum value of `-32` and a maximum value of 53 | `31`. 54 | -------------------------------------------------------------------------------- /src/chirpstack/features/channel-configuration.md: -------------------------------------------------------------------------------- 1 | # Channel (re)configuration 2 | 3 | ChirpStack supports the (re)configuration of the channels used by the device 4 | for uplink transmissions. This feature can be used to configure additional 5 | uplink channels (e.g. for the EU ISM band), or to enable only a sub-set of 6 | the uplink channels specified by the [LoRaWAN® Regional Parameters](https://www.lora-alliance.org/lorawan-for-developers). 7 | 8 | ## Additional channels 9 | 10 | For certain regions, ChirpStack supports configuring additional channels 11 | Please consult the [LoRaWAN Regional Parameters](https://www.lora-alliance.org/lorawan-for-developers) 12 | to find out for which regions this applies. 13 | 14 | If extra channels are configured, ChirpStack will configure the first 5 15 | channels by using the OTAA join-accept `CFList` field. Additional channels 16 | will be configured using the `NewChannelReq` mac-command. This mac-command 17 | will also be used to push new or updated channel configuration to already 18 | activated devices and to (re)configure the min/max data-rate range for these 19 | extra channels. 20 | 21 | ## Enable sub-band 22 | 23 | ChirpStack will by default assume that all available uplink channels specified 24 | by the LoRaWAN Regional Parameters are active after an over-the-air activation. 25 | As certain regions have more uplink channels than supported by most gateways, 26 | it is possible to configure ChirpStack so that it will only enable a sub-set 27 | of the available uplink-channels. Using the `LinkADRReq` mac-command it will 28 | then update the channelmask of the device. 29 | 30 | **Note:** after changing this setting, ChirpStack will push these changes at 31 | the first opportunity to the already activated devices. 32 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/contribute.md: -------------------------------------------------------------------------------- 1 | # Contribute 2 | 3 | ## Links 4 | 5 | * Community support: [https://support.chirpstack.io/](https://support.chirpstack.io/) 6 | * ChirpStack Gateway OS build environment scripts: 7 | * [https://github.com/chirpstack/chirpstack-gateway-os](https://github.com/chirpstack/chirpstack-gateway-os) 8 | * Issue and bug reports [https://github.com/chirpstack/chirpstack-gateway-os/issues](https://github.com/chirpstack/chirpstack-gateway-os/issues) 9 | * OpenWrt configuration for ChirpStack Gateway OS: 10 | * [https://github.com/chirpstack/chirpstack-openwrt-config](https://github.com/chirpstack/chirpstack-openwrt-config) 11 | * Issue and bug reports: [https://github.com/chirpstack/chirpstack-openwrt-config/issues](https://github.com/chirpstack/chirpstack-openwrt-config/issues) 12 | * ChirpStack packages for OpenWrt: 13 | * [https://github.com/chirpstack/chirpstack-openwrt-feed](https://github.com/chirpstack/chirpstack-openwrt-feed) 14 | * Issue and bug reports: [https://github.com/chirpstack/chirpstack-openwrt-feed/issues](https://github.com/chirpstack/chirpstack-openwrt-feed/issues) 15 | 16 | 17 | ## Building from source 18 | 19 | For instructions on building the ChirpStack Gateway OS from source, please 20 | refer to the `README.md` in the: 21 | 22 | [https://github.com/chirpstack/chirpstack-gateway-os](https://github.com/chirpstack/chirpstack-gateway-os/) 23 | 24 | ## ChirpStack OpenWrt feed 25 | 26 | If you would like to include one or multiple ChirpStack components in your own 27 | OpenWrt based project, then please refer to the following repository which 28 | contains the `Makefiles` for the ChirpStack components: 29 | 30 | [https://github.com/chirpstack/chirpstack-openwrt-feed](https://github.com/chirpstack/chirpstack-openwrt-feed) 31 | -------------------------------------------------------------------------------- /src/chirpstack-concentratord/downloads.md: -------------------------------------------------------------------------------- 1 | # Downloads 2 | 3 | For gateway specific packages, please refer to the [Installation](./install/index.md) 4 | instructions for your gateway model. 5 | 6 | ## Binaries 7 | 8 | | File name | HAL | Type | OS | Arch | 9 | | --------- | --- | ---- | -- | ---- | 10 | | [chirpstack-concentratord-sx1301_{{concentratord_version}}_linux_armv7hf.tar.gz](https://artifacts.chirpstack.io/downloads/chirpstack-concentratord/chirpstack-concentratord-sx1301_{{concentratord_version}}_linux_armv7hf.tar.gz) | SX1301 | .tar.gz | Linux | armv7 | 11 | | [chirpstack-concentratord-sx1302_{{concentratord_version}}_linux_armv7hf.tar.gz](https://artifacts.chirpstack.io/downloads/chirpstack-concentratord/chirpstack-concentratord-sx1302_{{concentratord_version}}_linux_armv7hf.tar.gz) | SX1302 | .tar.gz | Linux | armv7 | 12 | | [chirpstack-concentratord-2g4_{{concentratord_version}}_linux_armv7hf.tar.gz](https://artifacts.chirpstack.io/downloads/chirpstack-concentratord/chirpstack-concentratord-2g4_{{concentratord_version}}_linux_armv7hf.tar.gz) | 2G4 | .tar.gz | Linux | armv7 | 13 | | [chirpstack-concentratord-sx1301_{{concentratord_version}}_linux_arm64.tar.gz](https://artifacts.chirpstack.io/downloads/chirpstack-concentratord/chirpstack-concentratord-sx1301_{{concentratord_version}}_linux_arm64.tar.gz) | SX1301 | .tar.gz | Linux | arm64 | 14 | | [chirpstack-concentratord-sx1302_{{concentratord_version}}_linux_arm64.tar.gz](https://artifacts.chirpstack.io/downloads/chirpstack-concentratord/chirpstack-concentratord-sx1302_{{concentratord_version}}_linux_arm64.tar.gz) | SX1302 | .tar.gz | Linux | arm64 | 15 | | [chirpstack-concentratord-2g4_{{concentratord_version}}_linux_arm64.tar.gz](https://artifacts.chirpstack.io/downloads/chirpstack-concentratord/chirpstack-concentratord-2g4_{{concentratord_version}}_linux_arm64.tar.gz) | 2G4 | .tar.gz | Linux | arm64 | 16 | -------------------------------------------------------------------------------- /src/sponsors.md: -------------------------------------------------------------------------------- 1 | # Sponsors 2 | 3 | ## GitHub sponsors 4 | 5 | The development of the ChirpStack is supported by the following companies 6 | through [GitHub Sponsors](https://github.com/sponsors/chirpstack): 7 | 8 |
9 | 10 | [![RAK](./sponsors/rak.png)](https://www.rakwireless.com/en-us) 11 | [![Project-Q](./sponsors/project_q.png)](https://project-q.ai/) 12 | 13 | [![Dragino](./sponsors/dragino.png)](https://www.dragino.com) 14 | [![Milesight](./sponsors/milesight.png)](https://www.milesight.com) 15 | 16 | [![Smart Parks](./sponsors/smartparks.png)](http://www.smartparks.org) 17 | [![Reese](./sponsors/reese.jpg)](https://reesesystems.com) 18 | 19 | [![Pollex](./sponsors/pollex.png)](https://pollex.nl/) 20 | [![myDevices](./sponsors/my_devices.png)](https://www.mydevices.com) 21 | 22 | [![Browan](./sponsors/browan.png)](https://browan.com) 23 | [![Kerlink](./sponsors/kerlink.png)](https://www.kerlink.com) 24 | 25 | [![Object Spectrum](./sponsors/objectspectrum.png)](https://objectspectrum.com/) 26 | 27 | 28 |
29 | 30 | ## Feature sponsors 31 | 32 | The following companies have sponsored the development of one or more 33 | significant ChirpStack feature: 34 | 35 |
36 | 37 | [![RAK](./sponsors/rak.png)](https://www.rakwireless.com/en-us) 38 | [![Afnic](./sponsors/afnic.jpg)](https://www.afnic.fr/) 39 | 40 | [![Miitors](./sponsors/miitors.png)](https://www.miitors.com/) 41 | [![Wifx](./sponsors/wifx.png)](https://www.lorixone.io/) 42 | 43 | [![Thingstream](./sponsors/thingstream.png)](https://thingstream.io/) 44 | [![F3 Wireless](./sponsors/f3.png)](http://f3wireless.com/) 45 | 46 | [![TWTG](./sponsors/twtg.png)](https://www.twtg.io/) 47 | [![CableLabs](./sponsors/cablelabs.png)](https://www.cablelabs.com/) 48 | 49 | [![SIDN Fonds](./sponsors/sidn_fonds.png)](https://www.sidnfonds.nl/) 50 | 51 |
52 | -------------------------------------------------------------------------------- /src/chirpstack/api/grpc.md: -------------------------------------------------------------------------------- 1 | # gRPC 2 | 3 | ChirpStack provides a gRPC API interface which can be used to integrate ChirpStack 4 | with external application and / or to integrate ChirpStack into other platforms. 5 | 6 | ## gRPC 7 | 8 | [gRPC](https://grpc.io/) is a high-performance, open-source universal RPC 9 | framework. [Protocol Buffers](https://developers.google.com/protocol-buffers) 10 | definitions are used to define this API. All definitions are hosted in the 11 | [chirpstack](https://github.com/chirpstack/chirpstack/tree/master/api/proto) repository. 12 | 13 | Using the gRPC toolsets, it is possible to generate API clients for various 14 | programming languages. The following languages are officially supported by 15 | gRPC but there are additional community-based implementations: 16 | 17 | * C++ 18 | * Go 19 | * Node.js 20 | * Java 21 | * Ruby 22 | * Android Java 23 | * PHP 24 | * Python 25 | * C# 26 | * Objective-C 27 | 28 | ### Authentication 29 | 30 | In order to use the gRPC API methods, you must provide per-RPC credentials. 31 | The key for this metadata is `authorization`, the value `Bearer ` 32 | (replace **<API TOKEN>** with the API TOKEN obtained using the web-interface). 33 | 34 | ### ChirpStack SDKs 35 | 36 | The ChirpStack project provides SDKs for the following programming languages: 37 | 38 | * [Go](https://pkg.go.dev/github.com/chirpstack/chirpstack/api/go/v4) 39 | * [Python](https://pypi.org/project/chirpstack-api/) 40 | * [JavaScript](https://www.npmjs.com/package/@chirpstack/chirpstack-api) 41 | * [Rust](https://crates.io/crates/chirpstack_api) 42 | 43 | ### API console / UI 44 | 45 | ChirpStack itself does not provide an API console / UI interface, but it is 46 | compatible third-party gRPC GUI applications. See for example: 47 | 48 | * [BloomRPC](https://github.com/bloomrpc/bloomrpc) 49 | * [gRPC UI](https://github.com/fullstorydev/grpcui) 50 | -------------------------------------------------------------------------------- /src/chirpstack/use/device-profile-templates.md: -------------------------------------------------------------------------------- 1 | # Device-profile templates 2 | 3 | Device-profile templates can be created by ChirpStack admin users and can be used 4 | by ChirpStack users as templates to create new device profiles. Device-profile 5 | templates can be created using the web-interface, API or from the command-line 6 | to import from external repositories (read below). 7 | 8 | **Note**: As creating device profiles based on these templates copies the 9 | template values, changing or deleting the device-profile templates will not 10 | affect the created device profiles. 11 | 12 | ## Import device repository 13 | 14 | ChirpStack supports importing the [device repository](https://github.com/TheThingsNetwork/lorawan-devices) 15 | as device-profile templates by executing the following commands from the 16 | Linux command-line. Depending the filesystem permissions, you might need 17 | `sudo` to perform these steps. 18 | 19 | ### Cloning the device repository 20 | 21 | First you need to clone the device repository. In this case, we will clone the 22 | repository to `/opt/lorawan-devices`: 23 | 24 | ```bash 25 | git clone https://github.com/brocaar/lorawan-devices /opt/lorawan-devices 26 | ``` 27 | 28 | **Note:** an older snapshot of the `lorawan-devices` repository is cloned as the 29 | latest revision no longer contains a `LICENSE` file. 30 | 31 | ### Import into ChirpStack 32 | 33 | Once the repository is cloned, you need to import it into ChirpStack. Please 34 | note that this command can be executed multiple times. For example, you could 35 | periodically pull the latest changes from the `lorawan-devices` repository and 36 | re-run this command to update existing templates / create new templates for 37 | devices that have been added to the repository. 38 | 39 | ``` 40 | chirpstack -c /etc/chirpstack import-legacy-lorawan-devices-repository -d /opt/lorawan-devices 41 | ``` 42 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/chirpstack-pulsar-integration.toml: -------------------------------------------------------------------------------- 1 | [logging] 2 | # Log level. 3 | level="info" 4 | 5 | [redis] 6 | # Server address or addresses. 7 | # 8 | # Use rediss:// in case of a TLS secured connection. 9 | # 10 | # Example formats: 11 | # redis://127.0.0.1:6379 12 | # rediss://127.0.0.1:6379 13 | # redis://:password@127.0.0.1:6379 14 | # redis://username:password@127.0.0.1:6379 15 | # 16 | # Set multiple addresses when connecting to a cluster. 17 | servers=[ 18 | "redis://127.0.0.1/", 19 | ] 20 | 21 | # Redis Cluster. 22 | # 23 | # Set this to true when the provided URLs are pointing to a Redis Cluster 24 | # instance. 25 | cluster=false 26 | 27 | # Key prefix. 28 | # 29 | # A key prefix can be used to avoid key collisions when multiple deployments 30 | # are using the same Redis database and it is not possible to separate 31 | # keys by database index (e.g. when using Redis Cluster, which does not 32 | # support multiple databases). 33 | key_prefix="" 34 | 35 | # Consumer and consumer group name. 36 | # 37 | # This integration reads the events directly from the Redis event stream. 38 | # 39 | # If you are running multiple instances of this integration and you would 40 | # like to avoid receiving duplicated events, then all instances must share 41 | # the same consumer-group, each with an unique consumer name. For more 42 | # information about Redis Streams, see: 43 | # https://redis.io/docs/data-types/streams/#consumer-groups 44 | consumer_group="integration_pulsar" 45 | 46 | # Consumer name. 47 | consumer_name="main" 48 | 49 | [pulsar] 50 | # Pulsar server URL. 51 | server="pulsar://127.0.0.1:6650" 52 | 53 | # Event topic. 54 | event_topic="application.{{application_id}}.device.{{dev_eui}}.event.{{event}}" 55 | 56 | # Authentication token (JWT). 57 | auth_token="" 58 | 59 | # Publish events as JSON instead of Protobuf (binary). 60 | json=true -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/install/wifx.md: -------------------------------------------------------------------------------- 1 | # Wifx 2 | 3 | LORIX OS, running on Wifx gateways, provides built-in support for ChirpStack Gateway Bridge for all Wifx gateway models. 4 | 5 | ## Gateway Compatibility 6 | 7 | ### Supported Gateways 8 | 9 | The following Wifx gateways have native support of the ChirpStack Gateway Bridge: 10 | 11 | #### Wifx L1 12 | 13 | - **Platform**: LORIX OS 14 | - **Gateway Bridge Backend**: ChirpStack Concentratord 15 | - **Connectivity**: Ethernet 16 | - **Product Information**: [Wifx L1 product page](https://iot.wifx.net/en/products/wifx-l1/) 17 | - **Product Documentation**: [Wifx L1 documentation](https://iot.wifx.net/docs/wifx-l1) 18 | 19 | #### Wifx L1 4G 20 | 21 | - **Platform**: LORIX OS 22 | - **Gateway Bridge Backend**: ChirpStack Concentratord 23 | - **Connectivity**: Ethernet + 4G/LTE cellular 24 | - **Product Information**: [Wifx L1 4G product page](https://iot.wifx.net/en/products/wifx-l1-4g/) 25 | - **Product Documentation**: [Wifx L1 4G documentation](https://iot.wifx.net/docs/wifx-l1-4g) 26 | 27 | #### LORIX One 28 | 29 | - **Platform**: LORIX OS 30 | - **Gateway Bridge Backend**: Semtech UDP Packet Forwarder 31 | - **Product Information**: [Wifx LORIX One product page](https://iot.wifx.net/en/products/lorix-one/) 32 | - **Product Documentation**: [Wifx LORIX One documentation](https://iot.wifx.net/docs/lorix-one) 33 | 34 | ## Setup 35 | 36 | Please refer to the [ChirStack page in the LORIX OS documentation](https://iot.wifx.net/docs/lorix-os/latest/wifx-l1/user-s-guide/lorawan/lorawan-networks/chirpstack) 37 | for more information. 38 | 39 | ![ChirpStack Gateway Bridge configuration page in LORIX OS](wifx-lorix-os-chirpstack-gateway-bridge.png "ChirpStack Gateway Bridge configuration page") 40 | 41 | ## Additional Resources 42 | 43 | - [Wifx IoT website](https://iot.wifx.net/) 44 | - [LORIX OS Documentation](https://iot.wifx.net/docs/lorix-os/) 45 | - [Wifx IoT Support Portal](https://iot.wifx.net/support/) 46 | -------------------------------------------------------------------------------- /src/gateway-configuration/laird.md: -------------------------------------------------------------------------------- 1 | # Laird 2 | 3 | ## Sentrius RG1XX LoRa® gateway 4 | 5 | * [Product detail page](https://www.lairdtech.com/products/rg1xx-lora-gateway) 6 | 7 | The Laird gateway can be configured in two ways: 8 | 9 | * MQTT Forwarder 10 | * Semtech Forwarder 11 | 12 | **Note:** The first option is not (yet) compatible with ChirpStack Network Server v3 as 13 | the Laird gateway comes with ChirpStack Gateway Bridge v2. In case you would like to 14 | use this gateway with ChirpStack Network Server v3, use the second option. 15 | 16 | ### MQTT Forwarder 17 | 18 | **Note:** The ChirpStack Gateway Bridge v2 component comes pre-installed since firmware version 19 | [93.7.2.9](https://assets.lairdtech.com/home/brandworld/files/CONN-RN-RG1xx-laird-93_7_2_9.pdf). 20 | If your gateway is running an older version, please update it first. 21 | 22 | The pre-installed ChirpStack Gateway Bridge can be configured through the gateway 23 | web-interface using the following steps: 24 | 25 | * Login into the gateway web-interface. 26 | * In the top navigation bar, click on **LoRa**. 27 | * In the left navigation menu, click **Forwarder**. 28 | * From the *Mode* dropdown, select **MQTT Forwarder**. 29 | * Enter your MQTT **Server Address** and optionally the MQTT **Username** and **Password**. 30 | 31 | ### Semtech Forwarder 32 | 33 | For this option you need to install the ChirpStack Gateway Bridge component first on 34 | a server. See the [Install Documentation](../chirpstack-gateway-bridge/install/index.md) for 35 | more information. 36 | 37 | The Semtech (UDP) Forwarder can be configured through the gateway 38 | web-interface using the following steps: 39 | 40 | * Login into the gateway web-interface. 41 | * In the top navigation bar, click on **LoRa**. 42 | * In the left navigation menu, click **Forwarder**. 43 | * Fromt he *Mode* dropdown, select **Semtech Forwarder**. 44 | * As **Network Server Address** enter the address of your ChirpStack Gateway Bridge instance. 45 | -------------------------------------------------------------------------------- /examples/chirpstack/integrations/http/go/main.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "encoding/hex" 5 | "io/ioutil" 6 | "log" 7 | "net/http" 8 | 9 | "google.golang.org/protobuf/encoding/protojson" 10 | "google.golang.org/protobuf/proto" 11 | 12 | "github.com/chirpstack/chirpstack/api/go/v4/integration" 13 | ) 14 | 15 | type handler struct { 16 | json bool 17 | } 18 | 19 | func (h *handler) ServeHTTP(w http.ResponseWriter, r *http.Request) { 20 | b, err := ioutil.ReadAll(r.Body) 21 | if err != nil { 22 | panic(err) 23 | } 24 | 25 | event := r.URL.Query().Get("event") 26 | 27 | switch event { 28 | case "up": 29 | err = h.up(b) 30 | case "join": 31 | err = h.join(b) 32 | default: 33 | log.Printf("handler for event %s is not implemented", event) 34 | return 35 | } 36 | 37 | if err != nil { 38 | log.Printf("handling event '%s' returned error: %s", event, err) 39 | } 40 | } 41 | 42 | func (h *handler) up(b []byte) error { 43 | var up integration.UplinkEvent 44 | if err := h.unmarshal(b, &up); err != nil { 45 | return err 46 | } 47 | log.Printf("Uplink received from %s with payload: %s", up.GetDeviceInfo().DevEui, hex.EncodeToString(up.Data)) 48 | return nil 49 | } 50 | 51 | func (h *handler) join(b []byte) error { 52 | var join integration.JoinEvent 53 | if err := h.unmarshal(b, &join); err != nil { 54 | return err 55 | } 56 | log.Printf("Device %s joined with DevAddr %s", join.GetDeviceInfo().DevEui, join.DevAddr) 57 | return nil 58 | } 59 | 60 | func (h *handler) unmarshal(b []byte, v proto.Message) error { 61 | if h.json { 62 | return protojson.UnmarshalOptions{ 63 | DiscardUnknown: true, 64 | AllowPartial: true, 65 | }.Unmarshal(b, v) 66 | } 67 | return proto.Unmarshal(b, v) 68 | } 69 | 70 | func main() { 71 | // json: false - to handle Protobuf payloads (binary) 72 | // json: true - to handle JSON payloads (Protobuf JSON mapping) 73 | http.Handle("/", &handler{json: false}) 74 | log.Fatal(http.ListenAndServe(":8090", nil)) 75 | } 76 | -------------------------------------------------------------------------------- /src/chirpstack-concentratord/installation/wifx.md: -------------------------------------------------------------------------------- 1 | # Wifx 2 | 3 | LORIX OS, running on Wifx gateways, provides built-in support for ChirpStack Concentratord on modern Wifx gateway models. 4 | 5 | ## Gateway Compatibility 6 | 7 | ### Supported Gateways 8 | 9 | The following Wifx gateways have native support of the ChirpStack Concentratord: 10 | 11 | #### Wifx L1 12 | 13 | - **Platform**: LORIX OS 14 | - **Gateway Bridge Backend**: ChirpStack Concentratord 15 | - **Connectivity**: Ethernet 16 | - **Product Information**: [Wifx L1 product page](https://iot.wifx.net/en/products/wifx-l1/) 17 | - **Product Documentation**: [Wifx L1 documentation](https://iot.wifx.net/docs/wifx-l1) 18 | 19 | #### Wifx L1 4G 20 | 21 | - **Platform**: LORIX OS 22 | - **Gateway Bridge Backend**: ChirpStack Concentratord 23 | - **Connectivity**: Ethernet + 4G/LTE cellular 24 | - **Product Information**: [Wifx L1 4G product page](https://iot.wifx.net/en/products/wifx-l1-4g/) 25 | - **Product Documentation**: [Wifx L1 4G documentation](https://iot.wifx.net/docs/wifx-l1-4g) 26 | 27 | ### Legacy Gateways 28 | 29 | #### LORIX One 30 | 31 | - **Platform**: LORIX OS 32 | - **Gateway Bridge Backend**: Semtech UDP Packet Forwarder 33 | 34 | ## Configuration 35 | 36 | For detailed configuration instructions and setup procedures, please refer to the [ChirpStack Gateway Bridge configuration guide](https://iot.wifx.net/docs/lorix-os/latest/wifx-l1/user-s-guide/lorawan/packet-forwarders/chirpstack-gateway-bridge) in the official LORIX OS documentation. 37 | 38 | The LORIX OS documentation provides comprehensive guidance on: 39 | 40 | - Initial gateway setup and network configuration 41 | - ChirpStack Concentratord service configuration 42 | - Network server connection settings 43 | - Troubleshooting and monitoring 44 | 45 | ## Additional Resources 46 | 47 | - [Wifx IoT website](https://iot.wifx.net/) 48 | - [LORIX OS Documentation](https://iot.wifx.net/docs/lorix-os/) 49 | - [Wifx IoT Support Portal](https://iot.wifx.net/support/) 50 | -------------------------------------------------------------------------------- /examples/chirpstack/integrations/gcp-pub-sub/python/main.py: -------------------------------------------------------------------------------- 1 | from chirpstack_api import integration 2 | from google.cloud import pubsub_v1 3 | from google.protobuf.json_format import Parse 4 | 5 | 6 | class Handler: 7 | def __init__(self, json, project_id, subscription_name): 8 | self.json = json 9 | self.project_id = project_id 10 | self.subscription_name = subscription_name 11 | 12 | def receive(self): 13 | subscriber = pubsub_v1.SubscriberClient() 14 | sub_path = subscriber.subscription_path(self.project_id, self.subscription_name) 15 | 16 | while True: 17 | resp = subscriber.pull(sub_path, max_messages=10) 18 | for msg in resp.received_messages: 19 | event = msg.message.attributes['event'] 20 | subscriber.acknowledge(sub_path, [msg.ack_id]) 21 | 22 | if event == 'up': 23 | self.up(msg.message.data) 24 | elif event == 'join': 25 | self.join(msg.message.data) 26 | else: 27 | print('handler for event %s is not implemented' % event) 28 | 29 | def up(self, body): 30 | up = self.unmarshal(body, integration.UplinkEvent()) 31 | print('Uplink received from: %s with payload: %s' % (up.dev_eui.hex(), up.data.hex())) 32 | 33 | def join(self, body): 34 | join = self.unmarshal(body, integration.JoinEvent()) 35 | print('Device: %s joined with DevAddr: %s' % (join.dev_eui.hex(), join.dev_addr.hex())) 36 | 37 | def unmarshal(self, body, pl): 38 | if self.json: 39 | return Parse(body, pl) 40 | 41 | pl.ParseFromString(body) 42 | return pl 43 | 44 | 45 | h = Handler( 46 | # True - JSON marshaler 47 | # False - Protobuf marshaler (binary) 48 | False, 49 | 50 | # GCP Project ID 51 | "project-id", 52 | 53 | # GCP Pub/Sub Subsciption name 54 | "subscription-name", 55 | ) 56 | h.receive() 57 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/ifttt.md: -------------------------------------------------------------------------------- 1 | # IFTTT 2 | 3 | If configured, the IFTTT integration will forward device measurements to 4 | the [IFTTT](https://ifttt.com/) [Webhooks](https://ifttt.com/maker_webhooks). 5 | For this ChirpStack uses the event trigger with 3 JSON values format. The first 6 | value contains the device DevEUI, the other two values can be freely assigned. 7 | 8 | ## Preparation 9 | 10 | ### Key 11 | 12 | Before you can setup the IFTTT integration, you must obtain the key to 13 | authenticate with the IFTTT API. Please refer to the [Webhooks](https://ifttt.com/maker_webhooks) 14 | documentation. On top of the documentation page, you will find _Your key is:_ .... 15 | 16 | ### Codec 17 | 18 | You must configure a payload codec in the device-profile in order to use the 19 | IFTTT integration. See also [Device profiles](../use/device-profiles.md). 20 | 21 | 22 | ## Configuration 23 | 24 | * **Key**: Please use the key obtained in the previous step. 25 | * **Value 1 & 2 keys**: This must map to the measurement keys in the decoded 26 | payload. Please note that ChirpStack will automatically detect these when 27 | an uplink is received, and will store these under **Measurements** in the 28 | device-profile. 29 | 30 | ## IFTTT usage example 31 | 32 | The following example demonstrates how the selected two values can be sent 33 | to an e-mail address on uplink. 34 | 35 | * Click the _Create_ button within the IFTTT web-interface 36 | * Click the _Add_ button next to _If This_ 37 | * Search for **Webhooks** 38 | * Select _Receive a web request_ 39 | * As _Event Name_ enter **up** 40 | * Click the _Create trigger_ button 41 | * Click the _Add_ button next to _Then That_ 42 | * Search for **Email** 43 | * Select _Send me an email_ 44 | * Edit the _Subject_ and _Body_ as desired, note that you can use the _Add ingredient_ button to select the available values 45 | * Click the _Create action_ button 46 | 47 | If everything is configured correctly, you should receive an email on every 48 | uplink event. 49 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/postgresql.md: -------------------------------------------------------------------------------- 1 | # PostgreSQL 2 | 3 | If configured, the PostgreSQL integration will write device data into an 4 | [PostgreSQL](https://www.postgresql.org/) database. 5 | 6 | ## Creating database 7 | 8 | You must create a separate database for using the PostgreSQL integration. 9 | To enter the command line utility for PostgreSQL: 10 | 11 | ```bash 12 | sudo -u postgres psql 13 | ``` 14 | 15 | Inside this prompt, execute the following queries to setup the 16 | `chirpstack_integration` database. It is recommended to use a different 17 | username (role) and password. 18 | 19 | ```sql 20 | -- create role for authentication 21 | create role chirpstack_integration with login password 'chirpstack_integration'; 22 | 23 | -- create database 24 | create database chirpstack_integration with owner chirpstack_integration; 25 | 26 | -- exit psql 27 | \q 28 | ``` 29 | 30 | ## Activating integration 31 | 32 | This integration must be configured in the [Configuration](../configuration.md) 33 | file. 34 | 35 | ### Enable integration 36 | 37 | In the configuration file: 38 | 39 | ```toml 40 | [integration] 41 | enabled = [ 42 | "mqtt", 43 | ] 44 | ``` 45 | 46 | Your `enabled` line may look slightly different. Add `"postgresql"` to the list. 47 | In this case, the modified line should appear as enabled=["mqtt", "postgresql"]. 48 | 49 | ### Configuration 50 | 51 | You must also add / update the `[integration.postgresql]` section with the 52 | hostname, username, password and the name of the database. Example: 53 | 54 | ```toml 55 | [integration.postgresql] 56 | dsn="postgres://:@/?sslmode=disable" 57 | ``` 58 | 59 | In the dns= line, modify ``, ``, ``, and `` 60 | with your appropriate credentials and targets. If you followed the example above, 61 | you would use chirpstack_integration as your username and target database. If 62 | your target Postgres database is on the same machine as ChirpStack, use 63 | localhost as your host. 64 | -------------------------------------------------------------------------------- /examples/chirpstack/integrations/azure-service-bus/python/main.py: -------------------------------------------------------------------------------- 1 | from azure.servicebus import ServiceBusClient 2 | from chirpstack_api import integration 3 | from google.protobuf.json_format import Parse 4 | 5 | 6 | class Handler: 7 | def __init__(self, json, connection_string, queue_name): 8 | self.json = json 9 | self.connection_string = connection_string 10 | self.queue_name = queue_name 11 | 12 | def receive(self): 13 | client = ServiceBusClient.from_connection_string(self.connection_string) 14 | queue_client = client.get_queue(self.queue_name) 15 | messages = queue_client.get_receiver() 16 | 17 | for message in messages: 18 | message.complete() 19 | body = b''.join(message.body) 20 | 21 | event = message.user_properties[b'Event'] 22 | 23 | if event == b'up': 24 | self.up(body) 25 | elif event == b'join': 26 | self.join(body) 27 | else: 28 | print('handler for event %s is not implemented' % event) 29 | 30 | def up(self, body): 31 | up = self.unmarshal(body, integration.UplinkEvent()) 32 | print('Uplink received from: %s with payload: %s' % (up.device_info.dev_eui, up.data.hex())) 33 | 34 | def join(self, body): 35 | join = self.unmarshal(body, integration.JoinEvent()) 36 | print('Device: %s joined with DevAddr: %s' % (join.device_info.dev_eui.hex, join.dev_addr)) 37 | 38 | def unmarshal(self, body, pl): 39 | if self.json: 40 | return Parse(body, pl) 41 | 42 | pl.ParseFromString(body) 43 | return pl 44 | 45 | 46 | h = Handler( 47 | # True - JSON marshaler 48 | # False - Protobuf marshaler (binary) 49 | False, 50 | 51 | # Service-Bus connection string 52 | 'Endpoint=sb://example.servicebus.windows.net/;SharedAccessKeyName=example-policy;SharedAccessKey=...', 53 | 54 | # Service-Bus queue name 55 | 'events', 56 | ) 57 | h.receive() 58 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/protocol/stored-context.md: -------------------------------------------------------------------------------- 1 | # Stored context 2 | 3 | This section describes which context must be known at the different components 4 | in the Mesh architecture. Unless otherwise specified, this context must be 5 | known at both the Relay Gateway and Border Gateway. 6 | 7 | ## Mesh root-key 8 | 9 | An AES128 key which is used to add a message integrity code to each mesh 10 | packet. In case of events and commands packets, it is also used for 11 | encryption / decryption. Each Relay and Border gateway must be configured 12 | with this same key. 13 | 14 | ### MIC key 15 | 16 | The MIC key is generated as follow: 17 | 18 | ``` 19 | MIC key = aes128_encrypt(Mesh Root Key, 0x00 | pad16) 20 | ``` 21 | 22 | ### Encryption key 23 | 24 | The encryption key is generated as follow: 25 | 26 | ``` 27 | Encryption key = aes128_encrypt(Mesh Root Key, 0x01 | pad16) 28 | ``` 29 | 30 | ## TX Power table 31 | 32 | A TX Power table, which maps the (downlink) TX Power to an integer (0 - 15) 33 | and back. Ideally this matches the TX Power table of the Concentratord 34 | configuration (if there is no exact match, the Concentratord will use the 35 | highest value, that is less than the requested TX Power). 36 | 37 | ## Data-rate table 38 | 39 | A data-rate table, which maps the data-rate parameters to an integer value 40 | (and back). There is no requirement that this follows the data-rate indices 41 | as specified in RP002. 42 | 43 | ## Uplink channel index table 44 | 45 | An uplink channel table, which maps an uplink channel to an integer value 46 | (and back). There is no requirement that this follows the channel indices as 47 | specified in RP002. 48 | 49 | ## Uplink table 50 | 51 | The Relay Gateway stores a list of Uplink IDs (integer value) mapped to data 52 | required to transmit a downlink. Typically the Uplink ID maps to the 53 | concentrator counter value of the received uplink. On Class-A downlink to the 54 | same device, the Relay Gateway will receive the Uplink ID + a relative delay 55 | to the Uplink ID. 56 | -------------------------------------------------------------------------------- /src/chirpstack/features/multi-region.md: -------------------------------------------------------------------------------- 1 | # Multi-region 2 | 3 | ChirpStack supports multiple regions simultaneously, without the need to start 4 | multiple ChirpStack instances (like it was needed in ChirpStack v3). It is also 5 | possible to configure the same region more than once, to support for example a 6 | mix of 8-channel and 16-channel gateways. 7 | 8 | There are two terms that are important: 9 | 10 | * **Region name**, which is a user-defined name for a region configuration, this can be anything. 11 | * **Region common name**, which is the region common name as defined by the LoRa Alliance. 12 | 13 | In the ChirpStack configuration examples, you will find for example region name 14 | `us915_0` for the channels 0 - 7 configuration, `us915_1` for the channels 15 | 8 - 15 configuration etc... 16 | 17 | Each region configuration contains its own gateway backend configuration. 18 | Either a single MQTT broker can be used for all different regions, or multiple 19 | MQTT brokers can be used (e.g. for each region a separate MQTT broker). 20 | 21 | ChirpStack will automatically assign the _region name_ and _region common name_ 22 | to each gateway, based on the receiving gateway backend. 23 | 24 | ## Single MQTT broker 25 | 26 | The advantage of a single MQTT broker is the ease of setup. Adding a new 27 | region is changing the ChirpStack configuration and there is no need to deploy 28 | new MQTT brokers. 29 | 30 | However, it is important that each region uses its own MQTT topic prefix, to 31 | separate the MQTT message flows between regions. It is a good practice to use 32 | the _region name_ as topic prefix for the gateway. 33 | 34 | ## Multiple MQTT brokers 35 | 36 | The advantage of multiple MQTT brokers can be scalability. Each region 37 | configuration can have its own MQTT broker, and therefore the load of one 38 | region does not impact the load of an other region (MQTT broker). 39 | 40 | As message flows for the different region configurations is separated by MQTT 41 | broker instance, there is no need to add a region specific topic prefix. 42 | -------------------------------------------------------------------------------- /src/chirpstack-concentratord/index.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | ChirpStack Concentratord is an open-source LoRa(WAN) concentrator daemon built 4 | on top of the Semtech hardware abstraction layers. It exposes a [ZeroMQ](https://zeromq.org/) 5 | based API that can be used by one or multiple applications to interact with 6 | gateway hardware. By implementing and abstracting the the hardware specifics 7 | in a separate daemon and exposing this over a ZeroMQ based API, packet forwarding 8 | applications can be completely decoupled from the gateway hardware. 9 | It also makes it possible to let multiple applications interact simultaneously 10 | with the gateway hardware. For example multiple packet forwarders could forward 11 | data to different LoRaWAN network servers. 12 | 13 | ## HAL support 14 | 15 | ChirpStack Concentratord provides an unified ZeroMQ API for the following 16 | Semtech HALs: 17 | 18 | * [SX1301](https://github.com/Lora-net/lora_gateway) 19 | * [SX1302/3](https://github.com/Lora-net/sx1302_hal/) 20 | * [2g4](https://github.com/Lora-net/gateway_2g4_hal) 21 | 22 | ## Architecture example 23 | 24 | ```dot process 25 | digraph G { 26 | node [shape=record,fontsize="10"]; 27 | edge [fontsize="10"]; 28 | fontsize="10"; 29 | 30 | subgraph cluster_0 { 31 | style=filled; 32 | color="#bbdefb"; 33 | node [style=filled,color="#e3f2fd"]; 34 | label = "LoRa® Gateway"; 35 | 36 | "chirpstack-concentratord" -> "concentrator" [dir="both", label="Semtech HAL"]; 37 | "chirpstack-mqtt-forwarder" -> "chirpstack-concentratord" [dir="both", label="ZeroMQ"]; 38 | "chirpstack-udp-forwarder" -> "chirpstack-concentratord" [dir="both", label="ZeroMQ"]; 39 | "monitoring" -> "chirpstack-concentratord" [dir="both", label="ZeroMQ"]; 40 | 41 | "concentrator" [label="SX1301 / SX1302 / 2G4"]; 42 | "chirpstack-concentratord" [label="ChirpStack Concentratord"]; 43 | "chirpstack-mqtt-forwarder" [label="ChirpStack MQTT Forwarder"]; 44 | "chirpstack-udp-forwarder" [label="ChirpStack UDP Forwarder"]; 45 | "monitoring" [label="Third-party monitoring app"]; 46 | } 47 | 48 | } 49 | ``` 50 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/building-new-integrations.md: -------------------------------------------------------------------------------- 1 | # Building new integrations 2 | 3 | ChirpStack provides three kinds of integrations. 4 | 5 | * Per application integrations 6 | * Global integrations 7 | * Standalone integrations 8 | 9 | ## Per application integrations 10 | 11 | These integrations can be configured per application through the ChirpStack 12 | web-interface. As these are user-configurable, this kind of integration 13 | is stateless thus it does not maintain a connection to the integration. 14 | Adding such integration requires implementing the integration, adding API 15 | methods and modifying the ChirpStack UI. 16 | 17 | ## Global integrations 18 | 19 | These integrations are provided by ChirpStack and once configured, will be 20 | globally enabled. An example is the [MQTT](./mqtt.md) integration. Adding 21 | such integration requires implementing the integration. No API or UI changes 22 | are required. 23 | 24 | ## Standalone integrations 25 | 26 | Standalone integrations operate independent from ChirpStack, that means no 27 | ChirpStack changes will be required to add a new integration of this kind. 28 | These integrations will subscribe to a [Redis Stream](https://redis.io/docs/data-types/streams/) 29 | to which ChirpStack publishes integration events. Please see the 30 | `device_frame_log_max_history` setting in the [ChirpStack Configuration](../configuration.md) 31 | to enable this feature. 32 | 33 | ```dot process 34 | digraph G { 35 | node [shape=record,fontsize="10"]; 36 | edge [fontsize="10"]; 37 | fontsize="10"; 38 | node [style=filled,color="#e3f2fd"]; 39 | 40 | "ChirpStack" -> "Redis Stream"; 41 | "Redis Stream" -> "Integration 1"; 42 | "Redis Stream" -> "Integration 2"; 43 | "Redis Stream" -> "Integration ..."; 44 | } 45 | ``` 46 | 47 | ChirpStack provides a [`chirpstack-intergration`](https://crates.io/crates/chirpstack-integration) 48 | crate which provides the Redis Stream interface and a framework to easily build 49 | integrations. The [Apache Pulsar](./pulsar.md) integration can be used as an 50 | example implementation. 51 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/thingsboard.md: -------------------------------------------------------------------------------- 1 | # ThingsBoard 2 | 3 | If configured, the ThingsBoard integration will send device attributes 4 | and telemetry to the configured [ThingsBoard](https://thingsboard.io/) instance. 5 | 6 | * [ThingsBoard guides](https://thingsboard.io/docs/guides/) 7 | 8 | ## Requirements 9 | 10 | Before this integration is able to write data to ThingsBoard, the uplink 11 | payloads must be decoded. The payload codec can be configured per 12 | [Device Profile](../use/device-profiles.md). To validate that the uplink 13 | payloads are decoded, you can use the [live device event-log](../use/event-logging.md) 14 | feature. Decoded payload data will be available under the `object` key in 15 | the JSON object. 16 | 17 | ThingsBoard will generate a _Access Token_ per device. This token must be 18 | configured as a [device variable](../use/devices.md) in ChirpStack. 19 | The variable must be named **ThingsBoardAccessToken**. 20 | 21 | ## Attributes 22 | 23 | For each event, ChirpStack will update the ThingsBoard device with the 24 | following attributes: 25 | 26 | * `application_id` 27 | * `application_name` 28 | * `dev_eui` 29 | * `device_name` 30 | 31 | In case any [device tags](../use/devices.md) are configured for the 32 | device in ChirpStack, these will also be added to the attributes. 33 | 34 | ## Telemetry 35 | 36 | ### Uplink 37 | 38 | The following metrics are recorded for every uplink: 39 | 40 | * `dr` 41 | * `fcnt` 42 | * `fport` 43 | * `rssi` 44 | * `snr` 45 | 46 | Decoded uplink data is prefixed with the **data_** prefix. Make sure to 47 | configure a coded in the [Device Profile](../use/device-profiles.md). 48 | 49 | ### Device-status 50 | 51 | Device-status is prefixed with the **status_** prefix. The interval of the 52 | device-status requests can be configured through the [Device Profile](../use/device-profiles.md). 53 | 54 | ### Location 55 | 56 | Location data is prefixed with the **location_** prefix. Please note that this 57 | is **only** available in case geolocation capable gateways are being used and 58 | ChirpStack is configured with geolocation support. 59 | -------------------------------------------------------------------------------- /src/chirpstack/features/join-server.md: -------------------------------------------------------------------------------- 1 | # Join server 2 | 3 | ChirpStack supports the activation of devices through an 4 | external Join Server, using the API as specified in the LoRaWAN Backend 5 | Interfaces specification. In this case the session-keys will not be derived by 6 | ChirpStack and there is no need to configure the `AppKey` (and `NwkKey` in case 7 | of a LoRaWAN 1.1 device). 8 | 9 | Routing a join-request to a Join Server is based on the `JoinEUI` which is part 10 | of the LoRaWAN join-request. If ChirpStack finds a server matching 11 | the `JoinEUI`, then it will forward the join-request to this server. In any other 12 | case, ChirpStack will handle the join-request. 13 | 14 | ## Configuration 15 | 16 | ### Semtech LoRa Cloud Join Server 17 | 18 | To configure the Semtech LoRa Cloud Join Server with ChirpStack obtain the TLS 19 | certificates that you must use from the LoRa Cloud web-interface. 20 | 21 | * Under **Your network servers** click **Add Server** 22 | * Then click download credentials 23 | 24 | Within the obtained credentials archive you will find three files that you need 25 | to configure within the ChirpStack configuration: 26 | 27 | * `.trust`: must be configured as `ca_cert` 28 | * `.crt`: must be configured as `tls_cert` 29 | * `.key`: must be configured as `tls_key` 30 | 31 | **Note:** While the web-interface indicates that `https://js.loracloud.com:7009` 32 | is the **LoRa Cloud Join Server**, this is not the endpoint that must be 33 | configured as `server` within the ChirpStack configuration. The 34 | correct endpoint is `https://js.loracloud.com:7009/api/v1/rens/rens-XYZ/lbi`. 35 | You have to replace `rens-XYZ` with the actual Rens ID, you will find this value 36 | in the LoRa Cloud web-interface. 37 | 38 | 39 | Example configuration: 40 | 41 | ```toml 42 | [[join_server.servers]] 43 | join_eui="0016c001fffe0001" 44 | server="https://js.loracloud.com:7009/api/v1/rens/rens-123/lbi" 45 | ca_cert="/etc/chirpstack-network-server/certs/acct.trust" 46 | tls_cert="/etc/chirpstack-network-server/certs/acct.crt" 47 | tls_key="/etc/chirpstack-network-server/certs/acct.key" 48 | ``` 49 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/backends/semtech-udp.md: -------------------------------------------------------------------------------- 1 | # Semtech UDP packet-forwarder 2 | 3 | The [Semtech UDP packet-forwarder](https://github.com/lora-net/packet_forwarder) 4 | backend abstracts the [UDP protocol](https://github.com/Lora-net/packet_forwarder/blob/master/PROTOCOL.TXT). 5 | 6 | It is compatible with: 7 | 8 | * v1 of the protocol 9 | * v2 of the protocol 10 | * Modified format used by the [Kerlink iBTS](https://www.kerlink.com/product/wirnet-ibts/) 11 | containing the (encrypted) fine-timestamp 12 | 13 | ## Configuration 14 | 15 | When the `semtech_udp` backend has been enabled, make sure your packet-forwarder 16 | `global_conf.json` or `local_conf.json` is configured correctly, under `gateway_conf`, 17 | the `server_address`, `serv_port_up` and `serv_port_down` must be configured so 18 | that data is forwarded to the ChirpStack Gateway Bridge instance. 19 | 20 | ```json 21 | "gateway_conf": { 22 | "gateway_ID": "AA555A0000000000", 23 | "server_address": "localhost", 24 | "serv_port_up": 1700, 25 | "serv_port_down": 1700, 26 | ... 27 | } 28 | ``` 29 | 30 | ## Deployment 31 | 32 | The ChirpStack Gateway Bridge can be deployed either on the gateway (recommended) 33 | and "in the cloud". In the latter case, multiple gateways can connect to the 34 | same ChirpStack Gateway Bridge instance. 35 | 36 | When the ChirpStack Gateway Bridge is deployed on the gateway, you will benefit from 37 | the MQTT authentication / authorization layer and optional TLS. 38 | 39 | ## Prometheus metrics 40 | 41 | The Semtech UDP packet-forwarder backend exposes several [Prometheus](https://prometheus.io/) 42 | metrics for monitoring. 43 | 44 | #### backend_semtechudp_udp_sent_count 45 | 46 | The number of UDP packets sent by the backend (per packet_type). 47 | 48 | 49 | #### backend_semtechudp_udp_received_count 50 | 51 | The number of UDP packets received by the backend (per packet_type). 52 | 53 | #### backend_semtechudp_gateway_connect_count 54 | 55 | The number of gateway connections received by the backend. 56 | 57 | #### backend_semtechudp_gateway_disconnect_count 58 | 59 | The number of gateways that disconnected from the backend. 60 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/install/index.md: -------------------------------------------------------------------------------- 1 | # Installation 2 | 3 | ## Deployment strategies 4 | 5 | There are multiple ways that you can deploy the ChirpStack Gateway Bridge: 6 | 7 | ## Single instance 8 | 9 | The most basic strategy is to connect all your gateways to a single instance 10 | of the ChirpStack Gateway Bridge. This is the easiest option, as installing the 11 | ChirpStack Gateway Bridge on the gateway might involve some additional steps. 12 | Please note that from a security perspective, it is the least secure option. 13 | The UDP protocol implemented by most gateways don't support any 14 | form of authorization and checks that the received data is authentic. It is 15 | however an easy way to get started. 16 | 17 | ## Multiple instances 18 | 19 | For performance and to make the ChirpStack Gateway Bridge highly available, you 20 | can run ChirpStack Gateway Bridge on multiple servers, each connecting to the same 21 | MQTT broker. 22 | 23 | **Important:** In case you put a load-balancer in front of the ChirpStack Gateway 24 | Bridge cluster, make sure that each gateway connection is always routed to the 25 | same instance! This is especially important when load-balancing UDP connections. 26 | 27 | ## On each gateway 28 | 29 | Depending on the capabilities of your gateway, you can install the ChirpStack Gateway 30 | Bridge on each of your gateways. This might require a few additional steps in 31 | the setup, but has the following advantages: 32 | 33 | ### MQTT (using TCP) instead of UDP 34 | 35 | By using MQTT (which uses TCP) instead of UDP when using the Semtech UDP packet-forwarder 36 | backend, the connection becomes more reliable in case packetloss is common. 37 | 38 | ### Authentication 39 | 40 | It is possible to setup credentials for each gateway, so that only gateways with 41 | valid credentials are able to ingest data. 42 | 43 | ### SSL/TLS 44 | 45 | The MQTT protocol supports SSL/TLS meaning that you are able to setup a secure 46 | connection between your gateways and your MQTT broker. This not only means that 47 | other people are not able to intercept any data, it also means nobody is able 48 | to tamper with your data. 49 | -------------------------------------------------------------------------------- /examples/chirpstack/integrations/aws-sns/python/main.py: -------------------------------------------------------------------------------- 1 | import boto3 2 | from chirpstack_api import integration 3 | from google.protobuf.json_format import Parse 4 | 5 | 6 | class Handler: 7 | def __init__(self, json, queue_url): 8 | self.json = json 9 | self.queue_url = queue_url 10 | 11 | def receive(self): 12 | sqs = boto3.client('sqs') 13 | 14 | while True: 15 | resp = sqs.receive_message( 16 | QueueUrl=self.queue_url, 17 | MessageAttributeNames=[ 18 | 'All', 19 | ], 20 | MaxNumberOfMessages=1, 21 | WaitTimeSeconds=10, 22 | ) 23 | 24 | if not 'Messages' in resp: 25 | continue 26 | 27 | msg = resp['Messages'][0] 28 | receipt_handle = msg['ReceiptHandle'] 29 | 30 | sqs.delete_message( 31 | QueueUrl=self.queue_url, 32 | ReceiptHandle=receipt_handle, 33 | ) 34 | 35 | event = msg['MessageAttributes']['event']['StringValue'] 36 | 37 | if event == "up": 38 | self.up(msg['Body']) 39 | elif event == "join": 40 | self.join(msg['Body']) 41 | else: 42 | print('handler for event %s is not implemented' % event) 43 | 44 | def up(self, body): 45 | up = self.unmarshal(body, integration.UplinkEvent()) 46 | print('Uplink received from: %s with payload: %s' % (up.device_info.dev_eui, up.data.hex())) 47 | 48 | def join(self, body): 49 | join = self.unmarshal(body, integration.JoinEvent()) 50 | print('Device: %s joined with DevAddr: %s' % (join.device_info.dev_eui, join.dev_addr)) 51 | 52 | def unmarshal(self, body, pl): 53 | if self.json: 54 | return Parse(body, pl) 55 | 56 | pl.ParseFromString(body) 57 | return pl 58 | 59 | 60 | h = Handler( 61 | # True - JSON marshaler 62 | # False - Protobuf marshaler (binary) 63 | False, 64 | 65 | # SQS queue url 66 | 'https://sqs....', 67 | ) 68 | h.receive() 69 | -------------------------------------------------------------------------------- /src/chirpstack/integrations/mqtt.md: -------------------------------------------------------------------------------- 1 | # MQTT 2 | 3 | The MQTT integration publishes all the data it receives from the devices 4 | as JSON over MQTT. To receive data from your device, you therefore 5 | need to subscribe to its MQTT topic. For debugging, you could use a 6 | (command-line) tool like `mosquitto_sub` which is part of the 7 | [Mosquitto](http://mosquitto.org/) MQTT broker. 8 | 9 | ### MQTT quickstart 10 | 11 | Use `+` for a single-level wildcard, `#` for a multi-level wildcard. 12 | Examples: 13 | 14 | ```bash 15 | mosquitto_sub -t "application/APPLICATION_ID/#" -v # display everything for the given APPLICATION_ID 16 | mosquitto_sub -t "application/APPLICATION_ID/device/+/event/up" -v # display only the uplink payloads for the given APPLICATION_ID 17 | ``` 18 | 19 | Note: 20 | 21 | * MQTT topics are case-sensitive 22 | * The `APPLICATION_ID` can be retrieved using the API or using the web-interface, 23 | this is not the same as the `AppEUI` / `JoinEUI`! 24 | 25 | ## Events 26 | 27 | The MQTT integration exposes all events as documented by [Event types](events.md). 28 | The default event topic is: `application/APPLICATION_ID/device/DEV_EUI/event/EVENT`. 29 | 30 | ## Scheduling a downlink 31 | 32 | The default topic for scheduling downlink payloads is: `application/APPLICATION_ID/device/DEV_EUI/command/down`. 33 | 34 | The Application ID and DevEUI of the device will be taken from the topic. 35 | 36 | Example payload: 37 | 38 | ```json 39 | { 40 | "devEui": "0102030405060708", // this must match the DEV_EUI of the MQTT topic 41 | "confirmed": true, // whether the payload must be sent as confirmed data down or not 42 | "fPort": 10, // FPort to use (must be > 0) 43 | "data": "...." // base64 encoded data (plaintext, will be encrypted by ChirpStack) 44 | "object": { // decoded object (when application coded has been configured) 45 | "temperatureSensor": {"1": 25}, // when providing the 'object', you can omit 'data' 46 | "humiditySensor": {"1": 32} 47 | } 48 | } 49 | ``` 50 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/changelog.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## v4.1.1 4 | 5 | ### Improvements 6 | 7 | * Update internal dependencies and tune feature flags. 8 | 9 | ### Bugfixes 10 | 11 | * Fix uplink filters and add missing filter configuration to config template. 12 | 13 | ## v4.1.0 14 | 15 | ### Features 16 | 17 | #### Events / commands 18 | 19 | ##### Refactor Mesh heartbeat 20 | 21 | This refactors the Gateway Mesh heartbeat payload into a more generic Mesh Event 22 | payload, which can be used by both "known" and "proprietary" event types. The 23 | first implemented "known" type is the heartbeat. While this refactor is not 24 | backwards compatible and requires [ChirpStack MQTT Forwarder](https://www.chirpstack.io/docs/chirpstack-mqtt-forwarder/) 25 | v4.4+, the backwards incompatibility does not affect the functioning of the 26 | Gateway Mesh itself. 27 | 28 | ##### Proprietary events 29 | 30 | This release adds configuration options to periodically send Relay events. 31 | These events can generated by commands that are periodically executed. See 32 | the configuration section for more information. 33 | 34 | ##### Proprietary commands 35 | 36 | Next to events, this release also makes it possible to remotely execute 37 | commands on the Relay gateways, by using MQTT. See the configuration section 38 | for more information. 39 | 40 | #### ZMQ API 41 | 42 | This aligns the Concentratord ZMQ API interface with the ChirpStack 43 | Concentratord v4.5+. Please make sure to update to this Concentratord 44 | version or later. For Border Gateways, please make sure to also update the 45 | ChirpStack MQTT Forwarder to v4.4 or later. 46 | 47 | ### Improvements 48 | 49 | * Make Relay ID configurable. 50 | 51 | ### Bugfixes 52 | 53 | * Add `tx_power` to AU915 (`region_au915.toml`) configuration example. ([#67](https://github.com/chirpstack/chirpstack-gateway-mesh/pull/67)) 54 | 55 | ## v4.0.1 56 | 57 | ### Improvements 58 | 59 | * Update internal dependencies. 60 | * Add FSK channel to EU868 configuration example. 61 | * Add AS923, IN868, KR920, RU864 and AU915 configuration examples. 62 | 63 | ## v4.0.0 64 | 65 | Initial release. This component has been developed in collaboration with [RAK](https://www.rakwireless.com/en-us). 66 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/protocol/events.md: -------------------------------------------------------------------------------- 1 | # Relay event payload 2 | 3 | 4 | 5 | The Relay event payload allows a Relay Gateway to broadcast data like a heartbeat, 6 | location information, battery status, ... The event payloads are encoded as [TLV](https://en.wikipedia.org/wiki/Type%E2%80%93length%E2%80%93value) 7 | such that the event payload can contain data for known and unknown (proprietary) 8 | event types. 9 | 10 | Bytes: 11 | 12 | | 1 byte | 4 bytes | 4 bytes | n bytes | 4 bytes | 13 | | ---------- | --------- | -------- | ----------------------- | ------- | 14 | | Event MHDR | Timestamp | Relay ID | TLV payload (encrypted) | MIC | 15 | 16 | 17 | ## Event MHDR 18 | 19 | Bits: 20 | 21 | | 7..5 | 4..3 | 2..0 | 22 | | ----- | -------------| --------- | 23 | | MType | Payload type | Hop count | 24 | 25 | * MType = `111` (= Proprietary LoRaWAN MType) 26 | * Payload type = `10` (= Relay event) 27 | * Hop count = `000` = 1, ... `111` = 8 28 | 29 | **Note:** The hop count is incremented each time the event payload is relayed 30 | by an other Relay Gateway. The MIC must be re-calcalculated on each relay. 31 | 32 | ## Timestamp 33 | 34 | Unix timestamp (seconds). 35 | 36 | ### Relay ID 37 | 38 | The Relay ID of the Relay Gateway sending the event payload. 39 | 40 | ## TLV payload 41 | 42 | Bytes: 43 | 44 | | 1 byte | 1 byte | n bytes | 45 | | ------ | ------ | ------- | 46 | | Type | Length | Payload | 47 | 48 | Please see the [TLV payloads](./tlv-payloads.md) page for the known payload types. 49 | 50 | ### Encryption 51 | 52 | The TLV payload is encrypted using the same encryption scheme as the 53 | LoRaWAN FrmPayload (see section 4.3.3 of the LoRaWAN 1.0.4 specs). For the 54 | encryption the block Ai is defined as follow: 55 | 56 | Octets: 57 | 58 | | 1 | 4 | 1 | 4 | 4 | 1 | 1 | 59 | | ---- | -------- | ---- | -------- | --------- | ---- | - | 60 | | 0x01 | 4 x 0x00 | 0x00 | Relay ID | Timestamp | 0x00 | i | 61 | 62 | 63 | ## MIC 64 | 65 | Message integrity code, used by other Relay and Border gateways to check the 66 | data integrity of the packet. This is obtained by calculating the CMAC over 67 | the event payload (- MIC bytes), and using the first 4 bytes of the calculated 68 | CMAC as MIC. **Note:** The MIC must be calculated after encrypting the TLV payload! 69 | -------------------------------------------------------------------------------- /src/chirpstack-concentratord/installation/kerlink.md: -------------------------------------------------------------------------------- 1 | # Kerlink 2 | 3 | 4 | 5 | ## Kerlink iFemtoCell 6 | 7 | * [Product detail page](https://www.kerlink.com/product/wirnet-ifemtocell/) 8 | * [Product documentation page](https://wikikerlink.fr/) 9 | 10 | **Note:** This was tested with the following firmware version: `5.5.4`. 11 | 12 | ### SSH into the gateway 13 | 14 | The first step is to log in into the gateway using ssh: 15 | 16 | ```bash 17 | ssh root@GATEWAY-IP-ADDRESS 18 | ``` 19 | 20 | Please refer to the [Kerlink wiki](http://wikikerlink.fr/wirnet-productline) 21 | for login instructions. 22 | 23 | ### Disable Kerlink CPF 24 | 25 | Before you can install the ChirpStack Concentratord, you must disable the 26 | Kerlink CPF services (`lorad` and `lorafwd`). 27 | 28 | Disable `lorad`: 29 | 30 | Edit `/etc/default/lorad` and change `DISABLE_LORAD="no"` to `DISABLE_LORAD="yes"`. 31 | 32 | Disable `lorafwd`: 33 | 34 | Edit `/etc/default/lorafwd` and change `DISABLE_LORAFWD="no"` to `DISABLE_LORAFWD="yes"`. 35 | 36 | ### Download IPK 37 | 38 | Use the following commands to download the latest version of the 39 | `chirpstack-concentratord` package: 40 | 41 | ```bash 42 | cd /user/.updates 43 | wget https://artifacts.chirpstack.io/downloads/chirpstack-concentratord/vendor/kerlink/ifemtocell/chirpstack-concentratord_{{concentratord_version}}-r1_klkgw.ipk 44 | ``` 45 | 46 | ### Install IPK 47 | 48 | Run the following command to install the IPK package: 49 | 50 | ```bash 51 | sync 52 | kerosd -u 53 | reboot 54 | ``` 55 | 56 | ### Configuration 57 | 58 | Configuration files can be found at: 59 | 60 | * `/etc/chirpstack-concentratord/concentratord.toml` - Concentratord configuration 61 | * `/etc/chirpstack-concentratord/channels.toml` - Channel configuration 62 | 63 | #### (Re)start and stop commands 64 | 65 | Use the following commands to (re)start and stop the ChirpStack Concentratord 66 | service: 67 | 68 | ```bash 69 | # Status 70 | sudo monit summary 71 | 72 | # start 73 | monit start chirpstack-concentratord 74 | 75 | # stop 76 | monit stop chirpstack-concentratord 77 | 78 | # restart 79 | monit restart chirpstack-concentratord 80 | ``` 81 | 82 | #### Log output 83 | 84 | To view the ChirpStack Concentratord log output, use the following command: 85 | 86 | ```bash 87 | tail -f -n 100 /var/log/messages |grep chirpstack-concentratord 88 | ``` 89 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/comparison.md: -------------------------------------------------------------------------------- 1 | # Comparison 2 | 3 | The ChirpStack Gateway Mesh and the LoRa Alliance Relay Specification each have 4 | their own benefits. Depending the use-case one or the other might provide a 5 | better solution. To understand which solution might be better, this page 6 | highlights the main differences between the two. 7 | 8 | ## Implementation 9 | 10 | * **Gateway Mesh**: Does not require changes to LoRaWAN end-devices. The Gateway 11 | Mesh protocol only needs to be implemented by the LoRa Gateway. Border Gateway 12 | to ChirpStack communication is the same as a regular LoRa Gateway communicating 13 | to ChirpStack. 14 | * **Relay Specification**: Requires implementation by the LoRaWAN Network Server 15 | and the LoRaWAN end-device. ChirpStack does implement the Relay Specification. 16 | 17 | ## Security 18 | 19 | * **Gateway Mesh**: Can filter received data based on NetID and JoinEUI. Is not 20 | LoRaWAN end-device aware, and forwards all data passing the configured 21 | filters. The Mesh protocol uses signing key to protect against spoofing of 22 | Mesh payloads. 23 | * **Relay Specification**: Can filter received data based on JoinEUI + DevEUI. 24 | is LoRaWAN end-device aware and only forwards data for these Devices 25 | (trusted end-device list). 26 | 27 | ## Capacity 28 | 29 | * **Gateway Mesh**: Relay Gateway limitations are defined by max. throughput of 30 | LoRa concentrator. Mesh communication can optionally use LoRaWAN 2.4 GHz to 31 | increase throughput. 32 | * **Relay Sepcification**: The trusted end-device list of the Relay device 33 | can store max. 16 end-devices. The Relay device uses the same band as the 34 | end-devices. 35 | 36 | ## Mobility 37 | 38 | * **Gateway Mesh**: Relay Gateways within the Mesh are not end-device 39 | aware, devices can move freely without re-synchronizing between ChirpStack 40 | and the Relay Gateways. 41 | * **Relay Specification**: If an end-device moves from one Relay device to 42 | an other Relay, then ChirpStack must re-synchronize the trusted end-device 43 | list (removing the end-device from on list, adding it to the other). 44 | 45 | ## Hardware 46 | 47 | * **Gateway Mesh**: Gateway Mesh functionality is a software layer on top of 48 | LoRa Gateway hardware. 49 | * **Relay Specification**: Relay devices are technically LoRaWAN end-devices. 50 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/protocol/commands.md: -------------------------------------------------------------------------------- 1 | # Relay command payload 2 | 3 | 4 | 5 | The Relay command payload allows for executing one or multiple (pre-configured) 6 | commands on the gateway. The command payloads are encoded as [TLV](https://en.wikipedia.org/wiki/Type%E2%80%93length%E2%80%93value) 7 | (like the event payloads), such that the command payloads can contain data for 8 | known and unknown (proprietary) command types. 9 | 10 | Bytes: 11 | 12 | | 1 byte | 4 bytes | 4 bytes | n bytes | 4 bytes | 13 | | ------------ | --------- | -------- | ----------------------- | ------- | 14 | | Command MHDR | Timestamp | Relay ID | TLV payload (encrypted) | MIC | 15 | 16 | ## Command MHDR 17 | 18 | Bits: 19 | 20 | | 7..5 | 4..3 | 2..0 | 21 | | ----- | -------------| --------- | 22 | | MType | Payload type | Hop count | 23 | 24 | * MType = `111` (= Proprietary LoRaWAN MType) 25 | * Payload type = `11` (= Relay command) 26 | * Hop count = `000` = 1, ... `111` = 8 27 | 28 | **Note:** The hop count is incremented each time the command payload is relayed 29 | by an other Relay Gateway. The MIC must be re-calculated on each relay. 30 | 31 | ## Timestamp 32 | 33 | Unix timestamp (seconds). 34 | 35 | ### Relay ID 36 | 37 | The Relay ID of the Relay Gateway that must execute the command(s). 38 | 39 | ## TLV payload 40 | 41 | Bytes: 42 | 43 | | 1 byte | 1 byte | n bytes | 44 | | ------ | ------ | ------- | 45 | | Type | Length | Payload | 46 | 47 | Please see the [TLV payloads](./tlv-payloads.md) page for the known payload types. 48 | 49 | ### Encryption 50 | 51 | The TLV payload is encrypted using the same encryption scheme as the 52 | LoRaWAN FrmPayload (see section 4.3.3 of the LoRaWAN 1.0.4 specs). For the 53 | encryption the block Ai is defined as follow: 54 | 55 | Octets: 56 | 57 | | 1 | 4 | 1 | 4 | 4 | 1 | 1 | 58 | | ---- | -------- | ---- | -------- | --------- | ---- | - | 59 | | 0x01 | 4 x 0x00 | 0x01 | Relay ID | Timestamp | 0x00 | i | 60 | 61 | 62 | ## MIC 63 | 64 | Message integrity code, used by other Relay and Border gateways to check the 65 | data integrity of the packet. This is obtained by calculating the CMAC over 66 | the command payload (- MIC bytes), and using the first 4 bytes of the calculated 67 | CMAC as MIC. **Note:** The MIC must be calculated after encrypting the TLV payload! 68 | -------------------------------------------------------------------------------- /src/chirpstack-mqtt-forwarder/index.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | ChirpStack MQTT Forwarder is a MQTT packet forwarder for LoRa gateways. 4 | By default it forwards packets in [Protobuf](https://developers.google.com/protocol-buffers) 5 | binary format, optionally it can be configured to use JSON encoding for 6 | debugging. In contrast to the [ChirpStack Gateway Bridge](../chirpstack-gateway-bridge/index.md), 7 | this component must always be installed on the gateway. 8 | 9 | ## Backends 10 | 11 | The following backends are provided: 12 | 13 | * [ChirpStack Concentratord](../chirpstack-concentratord/index.md) 14 | * [Semtech UDP Packet Forwarder](https://github.com/Lora-net/packet_forwarder) 15 | 16 | ### ChirpStack Concentratord 17 | 18 | ```dot process 19 | digraph G { 20 | node [shape=record,fontsize="10"]; 21 | edge [fontsize="10"]; 22 | fontsize="10"; 23 | 24 | subgraph cluster_0 { 25 | style=filled; 26 | color="#bbdefb"; 27 | node [style=filled,color="#e3f2fd"]; 28 | label="LoRa® Gateway"; 29 | 30 | "chirpstack-mqtt-forwarder" -> "chirpstack-concentratord" [dir="both" label="ZeroMQ"]; 31 | 32 | "chirpstack-concentratord" [label="ChirpStack Concentratord"]; 33 | "chirpstack-mqtt-forwarder" [label="ChirpStack MQTT Forwarder"]; 34 | 35 | } 36 | 37 | subgraph cluster_1 { 38 | style=filled; 39 | color="#bbdefb"; 40 | node [style=filled,color="#e3f2fd"]; 41 | label="Cloud / server / VM"; 42 | 43 | "mqtt-broker" [label="MQTT broker"]; 44 | } 45 | 46 | "chirpstack-mqtt-forwarder" -> "mqtt-broker" [dir="both" label="MQTT"]; 47 | } 48 | ``` 49 | 50 | ### Semtech UDP Packet Forwarder 51 | 52 | ```dot process 53 | digraph G { 54 | node [shape=record,fontsize="10"]; 55 | edge [fontsize="10"]; 56 | fontsize="10"; 57 | 58 | subgraph cluster_0 { 59 | style=filled; 60 | color="#bbdefb"; 61 | node [style=filled,color="#e3f2fd"]; 62 | label="LoRa® Gateway"; 63 | 64 | "chirpstack-mqtt-forwarder" -> "semtech-udp-packet-forwarder" [dir="both" label="UDP"]; 65 | 66 | "semtech-udp-packet-forwarder" [label="Semtech UDP Packet Forwarder"]; 67 | "chirpstack-mqtt-forwarder" [label="ChirpStack MQTT Forwarder"]; 68 | 69 | } 70 | 71 | subgraph cluster_1 { 72 | style=filled; 73 | color="#bbdefb"; 74 | node [style=filled,color="#e3f2fd"]; 75 | label="Cloud / server / VM"; 76 | 77 | "mqtt-broker" [label="MQTT broker"]; 78 | } 79 | 80 | "chirpstack-mqtt-forwarder" -> "mqtt-broker" [dir="both" label="MQTT"]; 81 | } 82 | ``` 83 | -------------------------------------------------------------------------------- /src/chirpstack/features/frame-logging.md: -------------------------------------------------------------------------------- 1 | # Frame logging 2 | 3 | ChirpStack provides an option to log all uplink and downlink 4 | frames to a Redis stream, which can be consumed by external application(s) 5 | for monitoring or logging purposes. 6 | 7 | There are two streams that can be configured: 8 | 9 | 1. Frames received and sent by all gateways 10 | 2. Frames received from and sent to devices 11 | 12 | The difference between these two is that in case of 1., it will include 13 | **all** frames, thus also frames from devices from neighboring networks and 14 | frames which did not pass the frame-counter and MIC checks (and thus could 15 | have been replay-attacks). As in case of 2. the device is known, ChirpStack 16 | Network Server will always decrypt the mac-commands before logging the frame 17 | to the Redis stream in case this is needed. 18 | 19 | ## Configuration 20 | 21 | Please refer to the `monitoring.device_frame_log_max_history` and 22 | `monitoring.gateway_frame_log_max_history` [Configuration](../configuration.md) 23 | options. 24 | 25 | ## Redis keys 26 | 27 | The following Redis keys are used: 28 | 29 | * `gw:stream:frame`: for all gateway uplink and downlink frames 30 | * `device:stream:frame`: for all device uplink and downlink frames 31 | 32 | ## Message content 33 | 34 | ### Uplink 35 | 36 | Uplink frames are published under the `up` field of the Redis Stream. The content 37 | of this frame is a [Protobuf](https://developers.google.com/protocol-buffers/) 38 | encoded payload. The description of the `UplinkFrameLog` message can be found 39 | in the [frame.proto](https://github.com/chirpstack/chirpstack/blob/master/api/proto/stream/frame.proto) 40 | file. 41 | 42 | ### Downlink 43 | 44 | Downlink frames are published under the `down` field of the Redis Stream. The 45 | content of this frame is a [Protobuf](https://developers.google.com/protocol-buffers/) 46 | encoded payload. The description of the `DownlinkFrameLog` message can be found 47 | in the [frame.proto](https://github.com/chirpstack/chirpstack/blob/master/api/proto/stream/frame.proto) 48 | file. 49 | 50 | ## Redis Streams 51 | 52 | Redis Streams is a feature of [Redis](https://redis.io/) which provides a 53 | log data structure. It makes it possible to write and persist a configurable 54 | amount of uplink / downlink frames, which can be consumed by one or multiple 55 | consumers part of a consumer group. Refer to [https://redis.io/topics/streams-intro](https://redis.io/topics/streams-intro) 56 | for an introduction and examples how this feature can be used. 57 | -------------------------------------------------------------------------------- /src/chirpstack-concentratord/chirpstack-concentratord-2g4.toml: -------------------------------------------------------------------------------- 1 | 2 | # Concentratord configuration. 3 | [concentratord] 4 | # Log level. 5 | # 6 | # Valid options are: 7 | # * TRACE 8 | # * DEBUG 9 | # * INFO 10 | # * WARN 11 | # * ERROR 12 | # * OFF 13 | log_level="INFO" 14 | 15 | # Log to syslog. 16 | # 17 | # When set to true, log messages are being written to syslog instead of stdout. 18 | log_to_syslog=false 19 | 20 | # Statistics interval. 21 | stats_interval="30s" 22 | 23 | # Disable CRC status filter. 24 | # 25 | # By default, the Concentratord will ignore received frames which do not have 26 | # a valid CRC. This option makes it possible to disable this filter such that 27 | # received frames without (valid) CRC can be analyzed. 28 | disable_crc_filter=false 29 | 30 | # Configuration for the (ZeroMQ based) API. 31 | [concentratord.api] 32 | # Event PUB socket bind. 33 | event_bind="ipc:///tmp/concentratord_event" 34 | 35 | # Command REP socket bind. 36 | command_bind="ipc:///tmp/concentratord_command" 37 | 38 | 39 | # LoRa gateway configuration. 40 | [gateway] 41 | # Antenna gain (dB). 42 | antenna_gain=0 43 | 44 | # Public LoRaWAN network. 45 | lorawan_public=true 46 | 47 | # Gateway vendor / model. 48 | # 49 | # This configures various vendor and model specific settings like the min / max 50 | # frequency and TX gain table. 51 | model="semtech_sx1280z3dsfgw1" 52 | 53 | # Time fallback. 54 | # 55 | # In case the gateway does not have a GNSS module or is unable to aquire a 56 | # GNSS fix, use the system-time for setting the 'time' field on RX. 57 | time_fallback_enabled=false 58 | 59 | 60 | # LoRa concentrator configuration. 61 | [gateway.concentrator] 62 | [[gateway.concentrator.channels]] 63 | frequency=2403000000 64 | bandwidth=812000 65 | spreading_factor=12 66 | rssi_offset=0.0 67 | [[gateway.concentrator.channels]] 68 | frequency=2479000000 69 | bandwidth=812000 70 | spreading_factor=12 71 | rssi_offset=0.0 72 | [[gateway.concentrator.channels]] 73 | frequency=2425000000 74 | bandwidth=812000 75 | spreading_factor=12 76 | rssi_offset=0.0 77 | 78 | 79 | # Static gateway location. 80 | [gateway.location] 81 | # If set to non-zero values, the static gateway location will be reported 82 | # when the gateway does not have a GNSS module or when no GNSS location fix 83 | # is available. 84 | latitude=0.0 85 | longitude=0.0 86 | altitude=0 87 | 88 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/protocol/uplink.md: -------------------------------------------------------------------------------- 1 | # Uplink payload format 2 | 3 | 4 | 5 | On receiving an uplink, the Relay creates and re-transmits a Relay encapsulated 6 | LoRaWAN payload. The Relay encapsulation overhead is 14 bytes. 7 | 8 | Bytes: 9 | 10 | | 1 byte | 5 bytes | 4 bytes | n bytes | 4 bytes | 11 | | ----------- | --------------- | -------- | ------------------ | ------- | 12 | | Uplink MHDR | Uplink Metadata | Relay ID | LoRaWAN PHYPayload | MIC | 13 | 14 | 15 | ## Uplink MHDR 16 | 17 | Bits: 18 | 19 | | 7..5 | 4..3 | 2..0 | 20 | | ----- | -------------| --------- | 21 | | MType | Payload type | Hop count | 22 | 23 | * MType = `111` (= Proprietary LoRaWAN MType) 24 | * Payload type = `00` (= Relayed uplink) 25 | * Hop count = `000` = 1, ... `111` = 8 26 | 27 | **Note:** The hop count is incremented each time the uplink payload is relayed 28 | by an other Relay Gateway. As this changes the uplink payload, the MIC must be 29 | re-calculated. 30 | 31 | ## Uplink Metadata 32 | 33 | Bytes: 34 | 35 | | 2 bytes | 1 byte | 1 byte | 1 byte | 36 | | --------------------- | ------ | ------ | ------- | 37 | | Uplink ID + Data-rate | RSSI | SNR | Channel | 38 | 39 | ### Uplink ID + Data-rate 40 | 41 | Bits: 42 | 43 | | 15..4 | 3..0 | 44 | | --------- | --------- | 45 | | Uplink ID | Data-rate | 46 | 47 | #### Uplink ID 48 | 49 | Unique identifier (to the Relay Gateway) identifying the received uplink. 50 | Internally the Relay Gateway must temporarily store this in the Uplink table. 51 | 52 | #### Data-rate 53 | 54 | Uplink data-rate, unsigned integer with a minimum value of `0` and a maximum 55 | value of `15`. 56 | 57 | ### RSSI 58 | 59 | Encoded as RSSIdBm = `-1 x RSSI` 60 | 61 | ### SNR 62 | 63 | Bits: 64 | 65 | | 7..6 | 5..0 | 66 | | ---- | ---- | 67 | | RFU | SNR | 68 | 69 | SNR is a signed integer with a minimum value of `-32` and a maximum value of 70 | `31`. 71 | 72 | ### Channel 73 | 74 | Uplink channel, unsigned integer. 75 | 76 | ## Relay ID 77 | 78 | This contains the Relay ID which received the uplink from the End Device. 79 | 80 | Bytes: 81 | 82 | | 4 bytes | 83 | | -------- | 84 | | Relay ID | 85 | 86 | ## LoRaWAN PHYPayload 87 | 88 | The received LoRaWAN PHYPayload. 89 | 90 | ## MIC 91 | 92 | Message integrity code, used by other Relay and Border gateways to check the 93 | data integrity of the packet. This is obtained by calculating the CMAC over 94 | the uplink payload (- MIC bytes), and using the first 4 bytes of the calculated 95 | CMAC as MIC. 96 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/backends/basics-station.md: -------------------------------------------------------------------------------- 1 | # Semtech Basics Station 2 | 3 | The [Semtech Basics Station](https://doc.sm.tc/station/) backend implements 4 | the [LNS protocol](https://doc.sm.tc/station/tcproto.html). It exposes a 5 | websocket handler to which Basic Station powered gateways can connect. 6 | 7 | ## Authentication modes 8 | 9 | ### No Authentication 10 | 11 | The ChirpStack Gateway Bridge will not perform any authentication or authorization 12 | and all connections are accepted. 13 | 14 | ### TLS Server Authentication 15 | 16 | The `basic_station` backend [Configuration](../configuration.md) must 17 | be configured with a `tls_cert` and `tls_key`. The CA certificate used to sign 18 | the server TLS certificates must be provided to the Basic Station so that the 19 | gateway is able to authenticate the ChirpStack Gateway Bridge. 20 | 21 | ### TLS Server and Client Authentication 22 | 23 | Added to the _TLS Server Authentication_, the `basic_station` backend [Configuration](../configuration.md) 24 | must be configured with the `ca_cert` used to sign the used Basic Station 25 | client certificates. 26 | 27 | **Important:** The _Common Name (CN)_ must contain the _Gateway ID_ (64 bits) 28 | of each gateway as a HEX encoded string, e.g. `0102030405060708`. 29 | 30 | ## Channel-plan / `router_config` 31 | 32 | You must configure the gateway channel-plan in the ChirpStack Gateway Bridge 33 | [Configuration](../configuration.md) file. 34 | 35 | **Note:** In previous versions of the ChirpStack Gateway Bridge, you had to configure 36 | a _Gateway Profile_. This has been deprecated if favor of directly configuring 37 | the channels in the configuration file. 38 | 39 | ## Known issues 40 | 41 | * The Basic Station does not send RX / TX stats 42 | 43 | ## Prometheus metrics 44 | 45 | The Semtech Basic Station packet-forwarder backend exposes several [Prometheus](https://prometheus.io/) 46 | metrics for monitoring. 47 | 48 | #### backend_basicstation_websocket_ping_pong_count 49 | 50 | The number of WebSocket Ping/Pong requests sent and received (per event type). 51 | 52 | #### backend_basicstation_websocket_received_count 53 | 54 | The number of WebSocket messages received by the backend (per msgtype). 55 | 56 | #### backend_basicstation_websocket_sent_count 57 | 58 | The number of WebSocket messages sent by the backend (per msgtype). 59 | 60 | #### backend_basicstation_gateway_connect_count 61 | 62 | The number of gateway connections received by the backend. 63 | 64 | #### backend_basicstation_gateway_disconnect_count 65 | 66 | The number of gateways that disconnected from the backend. 67 | -------------------------------------------------------------------------------- /src/chirpstack/features/adaptive-data-rate.md: -------------------------------------------------------------------------------- 1 | # Adaptive data-rate (ADR) 2 | 3 | Adaptive data-rate lets ChirpStack control the data-rate and 4 | tx-power of the device, so that it uses less airtime and less power to 5 | transmit the same amount of data. This is not only beneficial for the 6 | energy consumption of the device, but also optimizes the spectrum. 7 | 8 | **Note:** ADR should only be used for static devices (devices that 9 | do not move). 10 | 11 | ## Activating ADR 12 | 13 | The activation of ADR is controlled by the device. Only when the device 14 | sends an uplink frame with the ADR flag set to `true` will ChirpStack 15 | adjust the data-rate and tx-power of the device if needed. 16 | 17 | ## Configuration 18 | 19 | To make sure there is enough link margin left after setting the ideal 20 | data-rate and tx-power, it is important to configure the installation margin 21 | correctly. A higher installation margin makes the ADR algorithm more 22 | conservative. 23 | 24 | ## Custom ADR algorithm 25 | 26 | ChirpStack provides several ADR algorithms out-of-the-box that should cater 27 | most use-cases. However, it is possible to configure additional ADR algorithms. 28 | ADR algorithms must be implemented in JavaScript, and the path(s) to these 29 | file(s) must be configured in the ChirpStack [Configuration](../configuration.md) 30 | file. 31 | 32 | ### Example skeleton 33 | 34 | ```js 35 | // This must return the name of the ADR algorithm. 36 | export function name() { 37 | return "Example plugin"; 38 | } 39 | 40 | // This must return the id of the ADR algorithm. 41 | export function id() { 42 | return "example_id"; 43 | } 44 | 45 | // This handles the ADR request. 46 | // 47 | // Input object example: 48 | // { 49 | // regionName: "eu868", 50 | // regionCommonName: "EU868", 51 | // devEui: "0102030405060708", 52 | // macVersion: "1.0.3", 53 | // regParamsRevision: "A", 54 | // adr: true, 55 | // dr: 1, 56 | // txPowerIndex: 0, 57 | // nbTrans: 1, 58 | // maxTxPowerIndex: 15, 59 | // requiredSnrForDr: -17.5, 60 | // installationMargin: 10, 61 | // minDr: 0, 62 | // maxDr: 5, 63 | // uplinkHistory: [ 64 | // { 65 | // "fCnt": 10, 66 | // "maxSnr": 7.5, 67 | // "maxRssi": -110, 68 | // "txPowerIndex": 0, 69 | // "gatewayCount": 3 70 | // } 71 | // ] 72 | // } 73 | // 74 | // This function must return an object, example: 75 | // { 76 | // dr: 2, 77 | // txPowerIndex: 1, 78 | // nbTrans: 1 79 | // } 80 | export function handle(req) { 81 | return { 82 | dr: req.dr, 83 | txPowerIndex: req.txPowerIndex, 84 | nbTrans: req.nbTrans 85 | }; 86 | } 87 | ``` 88 | -------------------------------------------------------------------------------- /src/chirpstack-mqtt-forwarder/install/tektelic.md: -------------------------------------------------------------------------------- 1 | # Tektelic 2 | 3 | ## Kona gateways 4 | 5 | These instructions appy to the Linux based Tektelic Kona gateways. 6 | 7 | * [Product detail page](https://www.tektelic.com/products/gateways/) 8 | 9 | ### SSH into the gateway 10 | 11 | The first step is to login into the gateway using ssh: 12 | 13 | ```bash 14 | ssh root@GATEWAY-IP-ADDRESS 15 | ``` 16 | 17 | The default password is the serial-number of the gateway which is printed on 18 | the back of the gateway (the 9 characters above the 12V = 1A line). 19 | 20 | ### Packet-forwarder configuration 21 | 22 | You must configure the packet-forwarder on the gateway to forward its data 23 | to `127.0.0.1` at port `1700`. The file `/etc/default/config.json` must 24 | contain the following lines: 25 | 26 | ```json 27 | ... 28 | "gateway_conf" { 29 | ... 30 | "server_address": "127.0.0.1", 31 | "serv_port_up": 1700, 32 | "serv_port_down": 1700, 33 | ... 34 | } 35 | ... 36 | ``` 37 | 38 | After updating the configuration file, make sure to restart the packet-forwarder: 39 | 40 | ```bash 41 | /etc/init.d/pkt_fwd restart 42 | ``` 43 | 44 | 45 | ### Install ChirpStack MQTT Forwarder 46 | 47 | #### Download IPK 48 | 49 | Use the following commands to download the latest version of the 50 | `chirpstack-mqtt-forwarder` package: 51 | 52 | ```bash 53 | cd /tmp 54 | wget https://artifacts.chirpstack.io/downloads/chirpstack-mqtt-forwarder/vendor/tektelic/kona/chirpstack-mqtt-forwarder_{{mqtt_forwarder_version}}-r1_kona.ipk 55 | ``` 56 | 57 | #### Install IPK 58 | 59 | Use the `opkg` package-manager to install the downloaded package. Example: 60 | 61 | ```bash 62 | sudo opkg install chirpstack-mqtt-forwarder_{{mqtt_forwarder_version}}-r1_kona.ipk 63 | ``` 64 | 65 | #### Configuration 66 | 67 | To connect the ChirpStack MQTT Forwarder to your MQTT broker, you must update 68 | the ChirpStack MQTT Forwarder configuration file. This file is located at: 69 | `/etc/chirpstack-mqtt-forwarder/chirpstack-mqtt-forwarder.toml`. 70 | 71 | #### (Re)start and stop commands 72 | 73 | Use the following commands to (re)start and stop the ChirpStack MQTT Forwarder 74 | service: 75 | 76 | ```bash 77 | # Status 78 | sudo monit summary 79 | 80 | # start 81 | monit start chirpstack-mqtt-forwarder 82 | 83 | # stop 84 | monit stop chirpstack-mqtt-forwarder 85 | 86 | # restart 87 | monit restart chirpstack-mqtt-forwarder 88 | ``` 89 | 90 | #### Log output 91 | 92 | To view the ChirpStack MQTT Forwarder log output, use the following command: 93 | 94 | ```bash 95 | tail -f -n 100 /var/log/messages |grep chirpstack-mqtt-forwarder 96 | ``` 97 | 98 | -------------------------------------------------------------------------------- /src/chirpstack-mqtt-forwarder/install/rak.md: -------------------------------------------------------------------------------- 1 | # RAK 2 | 3 | 4 | 5 | ## RAK7268V2 6 | 7 | * [Product details](https://store.rakwireless.com/products/rak7268-8-channel-indoor-lorawan-gateway) 8 | 9 | ### Configure Packet Forwarder 10 | 11 | In the RAK WisGate OS web-interface, you must configure the Packet Forwarder 12 | such that it forwards to `localhost` on port `1700`. 13 | 14 | Please refer to the [WisGate OS 2 manual](https://docs.rakwireless.com/Product-Categories/Software-APIs-and-Libraries/WisGateOS-2/Overview/) 15 | for instructions on how to access the web-interface. 16 | 17 | * In the left menu, click the **Configuration** icon (second icon from top to bottom). 18 | * Configure the following settings: 19 | * **Work mode:** _Packet forwarder_ 20 | * Under **Protocol**: 21 | * **Protocol:** _Semtech UDP GWMP Protocol_ 22 | * Under **UDP Protocol parameters**: 23 | * **Server address:** _localhost_ 24 | * **Server port up:** _1700_ 25 | * **Server port down:** _1700_ 26 | * Click **Save changes** 27 | 28 | ### Install ChirpStack MQTT Forwarder 29 | 30 | #### SSH login 31 | 32 | First you must login into the gateway using SSH: 33 | 34 | ```bash 35 | ssh root@GATEWAY-IP-ADDRESS 36 | ``` 37 | 38 | You must use the password as configured during the setup of the gateway. 39 | 40 | #### Download IPK 41 | 42 | Use the following commands to download the latest version of the 43 | `chirpstack-mqtt-forwarder` package: 44 | 45 | ```bash 46 | cd /tmp 47 | wget https://artifacts.chirpstack.io/downloads/chirpstack-mqtt-forwarder/vendor/rak/mipsel_24kc/chirpstack-mqtt-forwarder_{{mqtt_forwarder_version}}-r1_mipsel_24kc.ipk 48 | ``` 49 | 50 | #### Install IPK 51 | 52 | Use the `opkg` package-manager to install the downloaded package. Example: 53 | 54 | ```bash 55 | opkg install chirpstack-mqtt-forwarder_{{mqtt_forwarder_version}}-r1_mipsel_24kc.ipk 56 | ``` 57 | 58 | #### Configuration 59 | 60 | To connect the ChirpStack MQTT Forwarder to your MQTT broker, you must update 61 | the ChirpStack MQTT Forwarder configuration file. This file is located at: 62 | `/etc/chirpstack-mqtt-forwarder/chirpstack-mqtt-forwarder.toml`. 63 | 64 | #### (Re)start and stop commands 65 | 66 | Use the following commands to (re)start and stop the ChirpStack MQTT Forwarder service: 67 | 68 | ```bash 69 | # start 70 | /etc/init.d/chirpstack-mqtt-forwarder start 71 | 72 | # stop 73 | /etc/init.d/chirpstack-mqtt-forwarder stop 74 | 75 | # restart 76 | /etc/init.d/chirpstack-mqtt-forwarder restart 77 | ``` 78 | 79 | ### Access log output 80 | 81 | Use the following command to access the ChirpStack MQTT Forwarder log output: 82 | 83 | ```bash 84 | logread -f -l 100 -e chirpstack-mqtt-forwarder 85 | ``` 86 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/install/raspberry-pi.md: -------------------------------------------------------------------------------- 1 | # Raspberry Pi 2 | 3 | ## ChirpStack Gateway OS 4 | 5 | Rasberry Pi based gateways are supported by the 6 | [ChirpStack Gateway OS](../../chirpstack-gateway-os/index.md) images. This is the preferred 7 | and easiest option to get started. Please refer the ChirpStack Gateway OS 8 | documentation for installation instructions. 9 | 10 | ## Raspberry Pi OS 11 | 12 | ### ChirpStack Gateway Bridge 13 | 14 | ChirpStack provides a package repository that is compatible with Raspberry Pi OS. 15 | In order to add this repository, execute the following command: 16 | 17 | ```bash 18 | sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 1CE2AFD36DBCCA00 19 | 20 | sudo echo "deb https://artifacts.chirpstack.io/packages/4.x/deb stable main" | sudo tee /etc/apt/sources.list.d/chirpstack.list 21 | sudo apt update 22 | ``` 23 | 24 | Then in order to install the ChirpStack Gateway Bridge: 25 | 26 | ```bash 27 | sudo apt install chirpstack-gateway-bridge 28 | ``` 29 | 30 | If the above step has been completed, update the ChirpStack Gateway Bridge 31 | configuration file. This file is located at `/etc/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml`. 32 | By default it is configured to use with the [Semtech UDP Packet Forwarder](https://github.com/lora-net/packet_forwarder). 33 | The configuration that you most likely want to update is related to the MQTT integration 34 | configuration. 35 | 36 | To (re)start, stop and retrieve the status of the ChirpStack Gateway Bridge 37 | process, use the following commands: 38 | 39 | ```bash 40 | sudo systemctl [start|stop|restart|status] chirpstack-gateway-bridge 41 | ``` 42 | 43 | To retrieve the ChirpStack Gateway Bridge logs: 44 | 45 | ```bash 46 | sudo journalctl -u chirpstack-gateway-bridge -f -n 50 47 | ``` 48 | 49 | ### Packet Forwarder 50 | 51 | #### Semtech UDP Packet Forwarder 52 | 53 | The Semtech UDP Packet Forwarder must be configured so that it forwards its 54 | data to the ChirpStack Gateway Bridge that has been installed in the previous 55 | step. Where the configuration file of the Semtech UDP Packet Forwarder is 56 | located depends on how this Packet Forwarder was installed (which is outside 57 | the scope of this documentation). Typically this file is called `local_conf.json` 58 | and / or `global_conf.json` (in case both are present, values set in `local_conf.json` 59 | have priority over variables set in `global_conf.json`). 60 | 61 | Find the configuration section called `gateway_conf` and update the 62 | `server_address`, `serv_port_up` and `serv_port_down` accordingly: 63 | 64 | 65 | ```json 66 | "gateway_conf": { 67 | ... 68 | "server_address": "localhost", 69 | "serv_port_up": 1700, 70 | "serv_port_down": 1700, 71 | ... 72 | } 73 | ``` 74 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-bridge/configuration.md: -------------------------------------------------------------------------------- 1 | # Configuration 2 | 3 | The `chirpstack-gateway-bridge` has the following command-line flags: 4 | 5 | ```text 6 | ChirpStack Gateway Bridge abstracts the packet_forwarder protocol into Protobuf or JSON over MQTT 7 | > documentation & support: https://www.chirpstack.io/chirpstack-gateway-bridge/ 8 | > source & copyright information: https://github.com/brocaar/chirpstack-gateway-bridge 9 | 10 | Usage: 11 | chirpstack-gateway-bridge [flags] 12 | chirpstack-gateway-bridge [command] 13 | 14 | Available Commands: 15 | configfile Print the ChirpStack Gateway Bridge configuration file 16 | help Help about any command 17 | version Print the ChirpStack Gateway Bridge version 18 | 19 | Flags: 20 | -c, --config string path to configuration file (optional) 21 | -h, --help help for chirpstack-gateway-bridge 22 | --log-level int debug=5, info=4, error=2, fatal=1, panic=0 (default 4) 23 | 24 | Use "chirpstack-gateway-bridge [command] --help" for more information about a command. 25 | ``` 26 | 27 | ## Configuration file 28 | 29 | By default `chirpstack-gateway-bridge` will look in the following order for a 30 | configuration at the following paths when `--config` / `-c` is not set: 31 | 32 | * `chirpstack-gateway-bridge.toml` (current working directory) 33 | * `$HOME/.config/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml` 34 | * `/etc/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml` 35 | 36 | To load configuration from a different location, use the `--config` flag. 37 | 38 | To generate a new configuration file `chirpstack-gateway-bridge.toml`, execute the following command: 39 | 40 | ```bash 41 | chirpstack-gateway-bridge configfile > chirpstack-gateway-bridge.toml 42 | ``` 43 | 44 | Note that this configuration file will be pre-filled with the current configuration 45 | (either loaded from the paths mentioned above, or by using the `--config` flag). 46 | This makes it possible when new fields get added to upgrade your configuration file 47 | while preserving your old configuration. Example: 48 | 49 | ```bash 50 | chirpstack-gateway-bridge configfile --config chirpstack-gateway-bridge-old.toml > chirpstack-gateway-bridge-new.toml 51 | ``` 52 | 53 | Example configuration file: 54 | 55 | ```toml 56 | {%raw%}{{#include chirpstack-gateway-bridge.toml}}{%endraw%} 57 | ``` 58 | 59 | ## Environment variables 60 | 61 | Although using the configuration file is recommended, it is also possible 62 | to use environment variables to set configuration variables. Configuration 63 | dots `.` are replaced with double underscores `__`. 64 | 65 | Example: 66 | 67 | ```toml 68 | [backend.semtech_udp] 69 | udp_bind="0.0.0.0:1700" 70 | ``` 71 | 72 | Can be set using the environment variable: 73 | 74 | ```text 75 | BACKEND__SEMTECH_UDP__UDP_BIND="0.0.0.0:1700" 76 | ``` 77 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/protocol/downlink.md: -------------------------------------------------------------------------------- 1 | # Downlink payload format 2 | 3 | 4 | 5 | On downlink, the Border Gateway creates and re-transmits a Relay encapsulated 6 | to the Relay Gateway in the following format. The Relay encapsulation overhead 7 | is 15 bytes. 8 | 9 | Bytes: 10 | 11 | | 1 byte | 6 bytes | 4 bytes | n bytes | 4 bytes | 12 | | ------------- | ----------------- | -------- | ------------------ | ------- | 13 | | Downlink MHDR | Downlink Metadata | Relay ID | LoRaWAN PHYPayload | MIC | 14 | 15 | ## Downlink MHDR 16 | 17 | Bits: 18 | 19 | | 7..5 | 4..3 | 2..0 | 20 | | ----- | -------------| --------- | 21 | | MType | Payload type | Hop count | 22 | 23 | * MType = `111` (= Proprietary LoRaWAN MType) 24 | * Payload type = `01` (Relayed downlink) 25 | * Hop count = `000` 26 | 27 | **Note:** The hop count is incremented each time the downlink payload is relayed 28 | by an other Relay Gateway. As this changes the downlink payload, the MIC must be 29 | re-calculated. 30 | 31 | ## Downlink Metadata 32 | 33 | Bytes: 34 | 35 | | 2 bytes | 3 bytes | 1 byte | 36 | | ------------------------------ | ------------------ | ---------------- | 37 | | Uplink ID + Downlink data-rate | Downlink Frequency | Delay + TX Power | 38 | 39 | ### Uplink ID + Downlink data-rate 40 | 41 | Bits: 42 | 43 | | 15..4 | 3..0 | 44 | | --------- | ------------------ | 45 | | Uplink ID | Downlink data-rate | 46 | 47 | #### Uplink ID 48 | 49 | Unique identifier (to the Relay Gateway) identifying the uplink to which this 50 | downlink relates. E.g. the Relay Gateway uses this to retrieve the uplink 51 | counter value. 52 | 53 | #### Data-rate 54 | 55 | Downlink data-rate, unsigned integer with a minimum value of `0` and a maximum 56 | value of `15`. 57 | 58 | ### Downlink Frequency 59 | 60 | Encoded as FrequencyHz = `Downlink Frequency x 100`. 61 | 62 | ### Delay + TX Power 63 | 64 | Bits: 65 | 66 | | 7..4 | 3..0 | 67 | | -------- | ----- | 68 | | TX Power | Delay | 69 | 70 | #### TX Power 71 | 72 | The TX Power which must be used for sending the downlink. 73 | 74 | #### Delay 75 | 76 | The relative delay in seconds to the Uplink ID which must be used 77 | for the downlink transmission. Delay is an unsigned integer, encoded as: 78 | 79 | DelaySeconds = `Delay + 1`. 80 | 81 | ## Relay ID 82 | 83 | This contains the Relay ID that must relay the downlink to the 84 | End Device using the provided Downlink metadata. 85 | 86 | ## LoRaWAN PHYPayload 87 | 88 | The LoRaWAN PHYPayload that must be sent to the End-Device. 89 | 90 | ## MIC 91 | 92 | Message integrity code, used by other Relay gateways to check the 93 | data integrity of the packet. This is obtained by calculating the CMAC over 94 | the downlink payload (- MIC bytes), and using the first 4 bytes of the calculated 95 | CMAC as MIC. 96 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-mesh/events.md: -------------------------------------------------------------------------------- 1 | # Events 2 | 3 | The ChirpStack Gateway Mesh provides the option to send events from the Relay 4 | Gateways to the server (through the Border Gateway(s), ChirpStack MQTT Forwarder 5 | to the MQTT broker). 6 | 7 | These events can be divided into the following ranges: 8 | 9 | * 0 - 127: Known / built-in events (encoding / decoding known) 10 | * 128 - 255: Proprietary / custom events (passed as binary payloads) 11 | 12 | 13 | ### Known events 14 | 15 | These events are known by the ChirpStack Gateway Mesh. An example is the 16 | periodic heartbeat sent by Relay Gateways. See also the list of 17 | [TLV payloads](./protocol/tlv-payloads.md). 18 | 19 | ### Proprietary events 20 | 21 | These events can be freely configured in the [Configuration](./configuration.md) 22 | file. Configuration is done in two steps: 23 | 24 | * Configuration of type (number) to command 25 | * Configuration of event-sets (list of type numbers and the interval) 26 | 27 | ## MQTT topic 28 | 29 | Events are published to the following MQTT topic using the [MeshEvent](https://github.com/chirpstack/chirpstack/blob/master/api/proto/gw/gw.proto) 30 | payload: 31 | 32 | ``` 33 | [PREFIX]/gateway/[GATEWAY_ID]/event/mesh 34 | ```` 35 | 36 | **Note:** Depending the ChirpStack MQTT Forwarder [Configuration](../chirpstack-mqtt-forwarder/configuration.md) 37 | this payload will be Protobuf or JSON encoded. 38 | 39 | ## Example 40 | 41 | **Note:** The following example assumes the ChirpStack MQTT Forwarder on the 42 | Border Gateway is configured with `json=true`. 43 | 44 | The following example demonstrates how to periodically send the output of the 45 | `uptime` command as event-type `128`. Please in this example, for simplicity 46 | the output of the command will be sent as text. To keep the payload as small 47 | as possible, it is recommended to use a binary encoding. 48 | 49 | ```toml 50 | [events.commands] 51 | 128 = ["/usr/bin/uptime"] 52 | 53 | [[events.sets]] 54 | interval = "5min" 55 | events = [128] 56 | ``` 57 | 58 | This will be exposed over MQTT using the `[PREFIX]/gateway/[GATEWAY_ID]/event/mesh` 59 | topic. Example payload: 60 | 61 | ```json 62 | { 63 | "gatewayId": "0016c001ff1a0a5f", 64 | "relayId": "f1137eb4", 65 | "time": "2025-05-18T10:28:25+00:00", 66 | "events": [ 67 | { 68 | "proprietary": { 69 | "eventType": 128, 70 | "payload": "IDEwOjI4OjI1IHVwIDMwIG1pbiwgIGxvYWQgYXZlcmFnZTogMC4wNiwgMC4wNiwgMC4wNAo=" 71 | } 72 | } 73 | ] 74 | } 75 | ``` 76 | 77 | Notes: 78 | 79 | * `gatewayId` is the ID of the Border Gateway 80 | * `relayId` is the ID of the Relay Gateway 81 | * `time` is the time when the event was sent by the Relay Gateway 82 | 83 | Note that the `payload` is BASE64 encoded, as the event can be in binary form. 84 | In this example, the output is text. BASE64 decoding `payload` gives: 85 | 86 | ``` 87 | 10:28:25 up 30 min, load average: 0.06, 0.06, 0.04 88 | ``` 89 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/hardware-support.md: -------------------------------------------------------------------------------- 1 | # Hardware support 2 | 3 | 4 | 5 | ## Gateways 6 | 7 | ### RAK 8 | 9 | * [RAK7267 - WisGate Soho Pro Gateway](https://store.rakwireless.com/products/wisgate-soho-pro-gateway-rak7267) 10 | * [RAK7268v2 - WisGate Edge Lite 2](https://store.rakwireless.com/products/rak7268-8-channel-indoor-lorawan-gateway) 11 | * [RAK7289v2 - WisGate Edge Pro](https://store.rakwireless.com/products/rak7289-8-16-channel-outdoor-lorawan-gateway) 12 | * [RAK7391 - WisGate Connect / Compute Module 4 (CM4) Carrier Board](https://store.rakwireless.com/products/wisgate-connect-base-kit-rak7391) 13 | 14 | ### Seeed 15 | 16 | * [SenseCAP M2](https://wiki.seeedstudio.com/Network/SenseCAP_Network/SenseCAP_M2_Multi_Platform/SenseCAP_M2_Multi_Platform_Overview/) 17 | 18 | ## Raspberry Pi 19 | 20 | ### Supported targets 21 | 22 | * Raspberry Pi Zero W 23 | * Raspberry Pi B / B+ 24 | * Raspberry Pi 2B 25 | * Raspberry Pi 3B / 3B+ 26 | * Raspberry Pi 4B 27 | 28 | ### Supported shields 29 | 30 | #### Dragino 31 | 32 | * [Dragino PG1302](https://www.dragino.com/products/lora/item/223-pg1302.html) 33 | 34 | #### IMST 35 | 36 | * [IMST - iC880A](https://wireless-solutions.de/products/long-range-radio/ic880a.html) 37 | * [IMST - Lite Gateway](https://wireless-solutions.de/products/long-range-radio/lora-lite-gateway.html) 38 | 39 | #### Pi Supply 40 | 41 | * [Pi Supply - LoRa Gateway Hat](https://uk.pi-supply.com/products/iot-lora-gateway-hat-for-raspberry-pi) 42 | 43 | #### RAK Wireless 44 | 45 | * [RAK - RAK2245](https://store.rakwireless.com/products/rak2245-pi-hat) 46 | * [RAK - RAK2246 / RAK2246G](https://store.rakwireless.com/products/rak7246-lpwan-developer-gateway) 47 | * [RAK - RAK2247](https://store.rakwireless.com/products/rak2247-lpwan-gateway-concentrator-module) 48 | * [RAK - RAK2287](https://store.rakwireless.com/products/rak2287-lpwan-gateway-concentrator-module) 49 | * [RAK - RAK5146](https://store.rakwireless.com/products/wislink-lpwan-concentrator-rak5146) 50 | * [RAK - RAK5148](https://store.rakwireless.com/products/2-4-ghz-mini-pcie-concentrator-module-for-lora-based-on-sx1280-rak5148) 51 | * [RAK - RAK831](https://store.rakwireless.com/products/rak831-gateway-module) 52 | 53 | #### RisingHF 54 | 55 | * [RisingHF - RHF0M301 LoRaWAN IoT Discovery Kit](http://risinghf.com/#/product-details?product_id=9&lang=en) 56 | 57 | #### Sandbox 58 | 59 | * [Sandbox Electronics - LoRaGo PORT](https://sandboxelectronics.com/?product=lorago-port-multi-channel-lorawan-gateway) 60 | 61 | #### Seeed 62 | 63 | * [Seeed - WM1302](https://wiki.seeedstudio.com/WM1302_module/) 64 | 65 | #### Semtech 66 | 67 | * [Semtech - SX1302 evaluation kit - SX1302CXXXGW1](https://www.semtech.com/products/wireless-rf/lora-core/sx1302cxxxgw1) 68 | * [Semtech - SX1302 evalidation kit - SX1302CSSXXXGW1](https://www.semtech.com/products/wireless-rf/lora-core/sx1302cssxxxgw1) 69 | * [Semtech - SX1280 2.4 GHz evaluation kit](https://www.semtech.com/products/wireless-rf/lora-24ghz/sx1280zxxxxgw1) 70 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/install/dragino.md: -------------------------------------------------------------------------------- 1 | # Dragino 2 | 3 | 4 | 5 | **Note:** These are custom firmware images that are not supported by Dragino and might 6 | might void your warranty. Use at your own risk. 7 | 8 | ## Downloads 9 | 10 | Please use one of the download options below to download the latest 11 | (v{{gateway_os_version}}) ChirpStack Gateway OS image. 12 | 13 | | Model | Factory image | Sysupgrade image | 14 | | ----- | ------------- | ---------------- | 15 | | Dragino LPS8N | | [Download](https://artifacts.chirpstack.io/downloads/chirpstack-gateway-os/{{gateway_os_version}}/dragino/ath79/generic/chirpstack-gateway-os-{{gateway_os_version}}-lps8n-ath79-generic-dragino_lps8n-squashfs-sysupgrade.bin) | 16 | 17 | ## Installation 18 | 19 | ### LPS8N 20 | 21 | **Important note:** The LPS8N device has limited memory. When running the 22 | ChirpStack Gateway OS image on the gateway, it might run out of memory 23 | when flashing a new firmware. To avoid this, it is recommended to stop 24 | all `chirpstack-*` services first. This can be done in the web-interface 25 | under **System > Startup**, by clicking the **Stop** button for each 26 | `chirpstack-` service. 27 | 28 | #### LPS8N to Gateway OS 29 | 30 | This replaces the Dragino LPS8N firmware of the gateway with the 31 | Chirpstack Gateway OS. 32 | 33 | 1. First download the latest ChirpStack Gateway OS image for the Dragino LPS8N (see above table). 34 | 2. In the Dragino LPS8N web-interface, nativate to **System > Firmware Upgrade**. 35 | 3. Click the **Browse** button under _Upload Firmware File_, select the ChirpStack Gateway OS image and click **Upload**. 36 | 4. Once the image has been uploaded, click **Proceed** (do not enable any of the _Preserve Settings_ checkboxes!). 37 | 5. Wait until the firmware is flashed, this will take some minutes. 38 | 39 | #### Gateway OS to LPS8N 40 | 41 | This replaces the ChirpStack Gateway OS with the Dragino LPS8N firmware. 42 | 43 | 1. First download the latest firmware from [https://www.dragino.com/downloads/index.php?dir=LoRa_Gateway/LPS8/Firmware/Release/](https://www.dragino.com/downloads/index.php?dir=LoRa_Gateway/LPS8/Firmware/Release/). 44 | 2. In the ChirpStack Gateway OS web-interface, navigate to **System > Backup / Flash Firmware**. 45 | 3. Click the **Flash image...** button at the bottom of the page and select the Dragino image and click **Upload**. 46 | 4. De-select the **Keep settings and retain the current configuration** option and **Continue**. 47 | * You might see a _Image metadata not present_ warning, in which case you need to enable the **Force upgrade** checkbox. 48 | 5. Wait until the firmware is flashed, this will take some minutes. 49 | 6. Continue with the [Dragino LPS8N documentation](https://wiki.dragino.com/xwiki/bin/view/Main/User%20Manual%20for%20All%20Gateway%20models/LPS8N%20-%20LoRaWAN%20Gateway%20User%20Manual/). 50 | 51 | ## First usage 52 | 53 | After flashing the ChirpStack Gateway OS image, follow the [Getting started](../getting-started.md) 54 | documentation to setup your gateway. 55 | -------------------------------------------------------------------------------- /src/chirpstack/features/device-classes.md: -------------------------------------------------------------------------------- 1 | # Device classes 2 | 3 | ## Class-A 4 | 5 | ### Uplink 6 | 7 | ChirpStack supports LoRaWAN® Class-A devices. In Class-A a device is always in sleep 8 | mode, unless it has something to transmit. Only after an uplink transmission 9 | by the device, ChirpStack is able to schedule a downlink transmission. 10 | 11 | Received frames are de-duplicated (in case it has been received by multiple 12 | gateways), after which the mac-layer is handled by ChirpStack and the 13 | decrypted application-payload is forwarded to the configured integrations. 14 | 15 | ### Downlink 16 | 17 | ChirpStack persists downlink queue-items in its database. One a receive window 18 | occurs (triggered by an uplink), ChirpStack will transmit the items in the 19 | downlink queue FIFO to the device. Please note that mac-commands will get 20 | priority over application-payloads. 21 | 22 | #### Confirmed data 23 | 24 | ChirpStack sends an ack event with `ack: true` to the configured integration 25 | as soon the device has acknowledged the confirmed uplink. If the next uplink 26 | does not contain an acknowledgement, an ack event with `ack: false` is sent 27 | to the configured integrations. 28 | 29 | **Note:** Always check the value of the `ack` field in the ack event! For 30 | some integrations default values are omitted, which is equal to `ack: false`! 31 | 32 | ## Class-B 33 | 34 | ChirpStack supports Class-B devices. A Class-B device synchronizes its 35 | internal clock using Class-B beacons emitted by the gateway, this process 36 | is also called a "beacon lock". Once in the state of a beacon lock, the 37 | device negotiates its ping-interval. ChirpStack is then able to schedule 38 | downlink transmissions on each occurring ping-interval. 39 | 40 | ### Confirmed downlink 41 | 42 | The ack event works the same as for Class-A devices, with the only exception 43 | that an `ack: false` is triggered after the configured Class-B timeout. This 44 | timeout defines the maximum time that the device has to acknowledge a confirmed 45 | downlink. This timeout can be configured in the device-profile. 46 | 47 | ### Requirements 48 | 49 | #### Device 50 | 51 | The device must be able to operate in Class-B mode. 52 | 53 | #### Gateway 54 | 55 | The gateway must have a GNSS based time-source, as Class-B beacon and ping-slot 56 | scheduling must be very precise. The packet-forwarder must be configured to 57 | send Class-B beacons such that the device is able to synchronize its internal 58 | clock. 59 | 60 | ## Class-C 61 | 62 | ### Downlink 63 | 64 | ChirpStack supports Class-C devices and uses the same Class-A 65 | downlink device-queue for Class-C downlink transmissions. 66 | 67 | ### Confirmed data 68 | 69 | The ack event works the same as for Class-A devices, with the only exception 70 | that an `ack: false` is triggered after the configured Class-C timeout. This 71 | timeout defines the maximum time that the device has to acknowledge a confirmed 72 | downlink. This timeout can be configured in the device-profile. 73 | -------------------------------------------------------------------------------- /src/chirpstack-gateway-os/install/seeed.md: -------------------------------------------------------------------------------- 1 | # Seeed 2 | 3 | 4 | 5 | **Note:** These are custom firmware images that are not supported by Seeed and might 6 | might void your warranty. Use at your own risk. 7 | 8 | ## Downloads 9 | 10 | Please use one of the download options below to download the latest 11 | (v{{gateway_os_version}}) ChirpStack Gateway OS image. 12 | 13 | | Model | Factory image | Sysupgrade image | 14 | | ----- | ------------- | ---------------- | 15 | | SenseCAP M2 | | [Download](https://artifacts.chirpstack.io/downloads/chirpstack-gateway-os/{{gateway_os_version}}/seeed/ramips/mt76x8/chirpstack-gateway-os-{{gateway_os_version}}-sensecap-m2-ramips-mt76x8-sensecap_wm7628n-squashfs-sysupgrade.bin) | 16 | 17 | ## Installation 18 | 19 | ### SenseCAP M2 20 | 21 | #### SenseCAP M2 to Gateway OS 22 | 23 | This replaces the (open-source) SenseCAP M2 firmware of the gateway with the 24 | Chirpstack Gateway OS. 25 | 26 | 1. First download the latest ChirpStack Gateway OS image for the SenseCAP M2 (see above table). 27 | 2. In the SenseCAP M2 web-interface, nativate to **System > Backup / Flash Firmware**. 28 | 3. Click the **Flash image...** button at the bottom of the page and select the ChirpStack Gateway OS image and click **Upload**. 29 | 4. Depending the SenseCAP M2 firmware, you might get the option **Keep settings and retain the current configuration**, if this 30 | is the case, then de-select this option and **Continue**. 31 | 5. Wait until the firmware is flashed, this will take some minutes. 32 | 33 | If you did not see the **Keep settings and retain...** option (step 4), then 34 | the previous credentials (and some other settings) will be retained. It is advised 35 | to perform a factory reset after logging into the gateway to avoid conflicting 36 | configuration. The ChirpStackAP-xxxxxx access-point might not work until the 37 | factory reset is performed. A factory-reset can be performed in the web-interface 38 | under **System > Backup / Flash Firmware** by clicking the **Perform reset** 39 | button. 40 | 41 | 42 | #### Gateway OS to SenseCAP M2 43 | 44 | This replaces the Chirpstack Gateway OS with the SenseCAP M2 open-source firmware. 45 | 46 | 1. First download the latest SenseCAP M2 open-source firmware from [https://github.com/Seeed-Solution/LoRa_Gateway_OpenWRT/releases](https://github.com/Seeed-Solution/LoRa_Gateway_OpenWRT/releases). 47 | 2. In the ChirpStack Gateway OS web-interface, navigate to **System > Backup / Flash Firmware**. 48 | 3. Click the **Flash image...** button at the bottom of the page and select the SenseCAP M2 image and click **Upload**. 49 | 4. De-select the **Keep settings and retain the current configuration** option and **Continue**. 50 | 5. Wait until the firmware is flashed, this will take some minutes. 51 | 6. Continue with the [Login into Console](https://wiki.seeedstudio.com/flash_opensource_firmware_to_m2_gateway/#login-into-console) documentation. 52 | 53 | ## First usage 54 | 55 | After flashing the ChirpStack Gateway OS image, follow the [Getting started](../getting-started.md) 56 | documentation to setup your gateway. 57 | --------------------------------------------------------------------------------