Skip to content

Commit 11b6981

Browse files
rainerhitzrainerhitz
authored
Add ChirpStack and The Things Stack documentation (#127)
1 parent ff71c71 commit 11b6981

21 files changed

+416
-19
lines changed

‎docs/tutorials/receive-lorawan-sensor-data-from-chirpstack.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,14 @@ sidebar_position: 3
66

77
[ChirpStack](https://www.chirpstack.io/) is an open source LoRaWAN network server stack. This tutorial explains how to receive LoRaWAN sensor data via ChirpStack using the [MQTT Agent](../user-guide/agents-protocols/mqtt). The tutorial is based on the [Dragino LHT65](https://www.dragino.com/products/temperature-humidity-sensor/item/151-lht65.html) LoRaWAN sensor device as an example.
88

9+
:::note
10+
This tutorial focuses on the **manual configuration** of MQTT agent links to provide a deeper understanding of the integration process.
11+
12+
For a more automated approach, please see the specific agent documentation:
13+
* **[ChirpStack](../user-guide/agents-protocols/chirpstack.md)**
14+
* **[The Things Stack (TTS)](../user-guide/agents-protocols/the-things-stack.md)**
15+
:::
16+
917
## Install and start ChirpStack
1018
1. Make a copy of the ChirpStack Docker repository with the following commands:
1119
```shell

‎docs/user-guide/agents-protocols/_lorawan-asset-types.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
## LoRaWAN Asset Types
2+
3+
When using LoRaWAN agents such as [ChirpStack](chirpstack.md) or [The Things Stack](the-things-stack.md), OpenRemote can automatically provision assets and their communication links.
4+
5+
This automation relies on the use of specific **LoRaWAN Asset Types**. In these types, each attribute that is linked to a device data point must contain an `AGENT_LINK_CONFIG` meta item. This meta item acts as a blueprint, allowing the agent to automatically configure the underlying MQTT protocol agent links.
6+
7+
### Configuration Keys
8+
9+
The `AGENT_LINK_CONFIG` meta item is a `ValueType.ObjectMap` containing the following keys:
10+
11+
| Key | Type | Description |
12+
|:---|:---|:---|
13+
| `uplinkPort` | `Integer` | Filters incoming messages by the LoRaWAN FPort. |
14+
| `valueFilterJsonPath` | `String` | The JSON Path used to extract the value from the payload (see [Payload Formats](#network-server-payload-formats)). |
15+
| `valueConverter` | `Map` | Defines a value converter map for incoming values. |
16+
| `downlinkPort` | `Integer` | The FPort used for sending downlink commands. |
17+
| `writeValueConverter` | `Map` | Maps attribute values (e.g., `TRUE`/`FALSE`) to the required Base64 payloads. |
18+
19+
### Network Server Payload Formats
20+
21+
The `valueFilterJsonPath` specifies the exact location of sensor data within the incoming MQTT message. Because different LoRaWAN network servers wrap the decoded device data in different JSON envelopes, the root of your path must match your specific provider:
22+
23+
| Network Server | Payload Root | Example Path |
24+
| :--- | :--- | :--- |
25+
| **ChirpStack** | `$.object` | `$.object.Temperature` |
26+
| **The Things Stack** | `$.uplink_message.decoded_payload` | `$.uplink_message.decoded_payload.Temperature` |
27+
28+
### Example Asset Type
29+
30+
The example demonstrates how to map a sensor reading (uplink) and a command switch (downlink).
31+
32+
```java
33+
@Entity
34+
public class LoRaWanAsset extends Asset<LoRaWanAsset> {
35+
36+
// Uplink: Map temperature from Port 2
37+
public static final AttributeDescriptor<Double> TEMPERATURE = new AttributeDescriptor<>("temperature", ValueType.NUMBER,
38+
new MetaItem<>(MetaItemType.READ_ONLY),
39+
new MetaItem<>(MetaItemType.AGENT_LINK_CONFIG, new ValueType.ObjectMap() {{
40+
putAll(Map.of(
41+
"uplinkPort", 2,
42+
// For ChirpStack use $.object...
43+
// For The Things Stack use $.uplink_message.decoded_payload...
44+
"valueFilterJsonPath", "$.object.Temperature"
45+
));
46+
}})
47+
).withUnits(UNITS_CELSIUS);
48+
49+
// Downlink: Map switch to Base64 payloads on Port 4
50+
public static final AttributeDescriptor<Boolean> SWITCH = new AttributeDescriptor<>("switch", ValueType.BOOLEAN,
51+
new MetaItem<>(MetaItemType.AGENT_LINK_CONFIG, new ValueType.ObjectMap() {{
52+
putAll(Map.of(
53+
"downlinkPort", 4,
54+
"writeValueConverter", new ValueType.ObjectMap() {{
55+
putAll(Map.of(
56+
"TRUE", "DAE=",
57+
"FALSE", "DAA="
58+
));
59+
}}
60+
));
61+
}})
62+
);
63+
64+
public static final AttributeDescriptor<String> DEV_EUI = new AttributeDescriptor<>("devEUI", ValueType.TEXT, new MetaItem<>(MetaItemType.READ_ONLY));
65+
public static final AttributeDescriptor<String> VENDOR_ID = new AttributeDescriptor<>("vendorId", ValueType.TEXT, new MetaItem<>(MetaItemType.READ_ONLY));
66+
public static final AttributeDescriptor<String> MODEL_ID = new AttributeDescriptor<>("modelId", ValueType.TEXT, new MetaItem<>(MetaItemType.READ_ONLY));
67+
public static final AttributeDescriptor<String> FIRMWARE_VERSION = new AttributeDescriptor<>("firmwareVersion", ValueType.TEXT, new MetaItem<>(MetaItemType.READ_ONLY));
68+
public static final AttributeDescriptor<Boolean> SUPPORTS_CLASS_C = new AttributeDescriptor<>("supportsClassC", ValueType.BOOLEAN, new MetaItem<>(MetaItemType.READ_ONLY));
69+
70+
public static final AssetDescriptor<LoRaWanAsset> DESCRIPTOR = new AssetDescriptor<>("molecule-co2", "f18546", LoRaWanAsset.class);
71+
72+
protected LoRaWanAsset() {
73+
}
74+
75+
public LoRaWanAsset(String name) {
76+
super(name);
77+
}
78+
}
79+
```
80+
81+
### Downlink Payload Encoding
82+
83+
When sending commands to a LoRaWAN device, the network server (ChirpStack or The Things Stack) requires the raw binary payload to be formatted as a **Base64 encoded string**.
84+
85+
The `writeValueConverter` is used to perform this data transformation. It maps high-level OpenRemote attribute values to the specific Base64 strings required by the device's hardware commands.
86+
87+
In the example above, the device expects a 2-byte binary command to toggle a switch:
88+
89+
| Attribute Value | Raw Hex Command | Base64 String | Action |
90+
| :--- | :--- |:---| :--- |
91+
| `TRUE` | `0x0C01` | `DAE=` | Switch On |
92+
| `FALSE` | `0x0C00` | `DAA=` | Switch Off |
93+
94+
### Device Metadata Attributes
95+
96+
To successfully manage LoRaWAN devices, the Asset Type must include specific attributes for identification and hardware context.
97+
98+
#### Mandatory: DevEUI
99+
The `devEUI` attribute is **mandatory**. The agent uses this unique 64-bit identifier to match the physical device on the network server (ChirpStack or The Things Stack) to the corresponding asset in OpenRemote.
100+
101+
#### Optional Attributes
102+
The following attributes are optional. These are typically populated during the **CSV Import** process:
103+
104+
* **vendorId**: The manufacturer of the device (e.g., *Dragino* or *Milesight*).
105+
* **modelId**: The specific hardware model or part number (e.g., *LHT65*).
106+
* **firmwareVersion**: The version of the software running on the device.
107+
* **supportsClassC**: A boolean flag indicating if the device supports Class C (always-on) communication.

‎docs/user-guide/agents-protocols/chirpstack.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
import AssetTypes from './_lorawan-asset-types.md';
6+
7+
# ChirpStack
8+
9+
The ChirpStack agent allows integration of LoRaWAN devices managed by a [ChirpStack](https://www.chirpstack.io/) Network Server.
10+
11+
## How It Works
12+
13+
The ChirpStack agent acts as a bridge between OpenRemote and a **ChirpStack Network Server** by utilizing two primary communication channels:
14+
15+
### Message Exchange (MQTT)
16+
17+
The agent connects to the **ChirpStack MQTT integration** for real-time data flow:
18+
* **Uplink messages:** The agent subscribes to device events to receive sensor data.
19+
* **Downlink messages:** The agent publishes to command topics to send configuration or control packets back to the end-devices.
20+
21+
### Device Management (gRPC API)
22+
23+
The agent utilizes the **ChirpStack gRPC API** to interact with the Network Server's management layer. This is specifically used for:
24+
* **Auto-discovery:** The agent queries the API to list the **devices** registered in ChirpStack.
25+
* **Device Profiles:** For each discovered device, the agent retrieves its related **device profile**. This allows OpenRemote to understand the device type during the automatic asset creation process.
26+
27+
## Agent configuration
28+
29+
The following describes the supported agent configuration attributes:
30+
31+
| Attribute | Description | Required | Default |
32+
|-----------------|-----------------------------------------------------------------------------------------------------------------|----------|--------------------------------------------------|
33+
| `MQTTHost` | The hostname or IP address of the ChirpStack MQTT broker. | Y | - |
34+
| `MQTTPort` | The network port for the MQTT connection. | Y | - |
35+
| `clientId` | The unique identifier for this agent's session on the MQTT broker. | Y | - |
36+
| `secureMode` | Boolean flag indicating if the MQTT connection should use TLS/SSL encryption. | N | false |
37+
| `resumeSession` | Boolean flag indicating if the MQTT broker should persist the session and queue messages during agent downtime. | N | false |
38+
| `subscribeQos` | MQTT Quality of Service level for receiving uplinks (0, 1, 2). | N | 0 |
39+
| `publishQos` | MQTT Quality of Service level for sending downlinks (0, 1, 2). | N | 0 |
40+
| `host` | The hostname or IP address of the ChirpStack gRPC API. | Y | - |
41+
| `port` | The network port for the ChirpStack gRPC API. | N | secureGRPC==true -> 443, secureGRPC==false -> 80 |
42+
| `applicationId` | The UUID of the ChirpStack application to be integrated. | Y | - |
43+
| `apiKey` | A ChirpStack API Key used to authenticate the gRPC connection. | Y | - |
44+
| `secureGRPC` | Boolean flag to enable gRPC TLS/SSL encryption. | N | false |
45+
46+
47+
**Example:**
48+
49+
```yaml
50+
MQTTHost: 192.168.1.50
51+
MQTTPort: 1883
52+
clientId: or_chirpstack_agent_1
53+
secureMode: false
54+
resumeSession: true
55+
host: 192.168.1.50
56+
port: 8080
57+
applicationId: 7d809e33-d2ad-4ef1-aac8-2be67501c4d3
58+
apiKey: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhd...
59+
secureGRPC: false
60+
```
61+
62+
## Device to Asset Mapping
63+
64+
To ensure the ChirpStack Agent can automatically create and configure assets, it must be able to map a ChirpStack device to a specific **OpenRemote Asset Type**.
65+
66+
### Auto-discovery Mapping (ChirpStack Tags)
67+
68+
For devices discovered via the gRPC API, the mapping is defined within the **ChirpStack Device Profile**. By adding a specific tag to the profile, you provide the agent with the Asset Type template required to create the asset in OpenRemote:
69+
70+
| Tag Key | Tag Value |
71+
| :--- | :--- |
72+
| `openremote-asset-type` | The exact name of the **OpenRemote Asset Type** (e.g., `WeatherStationAsset`). |
73+
74+
During auto-discovery, the agent reads this tag and creates the corresponding asset in OpenRemote.
75+
76+
### CSV Import Mapping
77+
When importing devices via a CSV file, the asset type is defined directly within the file. The CSV must include a column that specifies the **Asset Type name** for each device record.
78+
79+
For a detailed breakdown of the required columns and an example file, see the [CSV Import Format](#csv-import-format) section below.
80+
81+
## MQTT Agent Link Automation
82+
83+
The ChirpStack agent handles the transmission of sensor data (**uplinks**) and commands (**downlinks**) via the **MQTT protocol**. To eliminate the need for manual configuration of every attribute, the agent automatically provisions these communication links during the discovery or import process.
84+
85+
### Automatic Provisioning Logic
86+
87+
Once a matching Asset Type template is identified, the agent configures the **MQTT Agent Links** based on the following workflow:
88+
89+
1. **Meta item Lookup**: The agent scans the attributes of the selected Asset Type for a meta item named `AGENT_LINK_CONFIG`. For details on the format of this meta item, see [LoRaWAN Asset Types](#lorawan-asset-types).
90+
2. **Link Creation**: The agent uses the template defined in the meta item to generate the specific MQTT topics and data filters required for that individual device.
91+
92+
### Attributes Configured
93+
94+
The following attributes are automatically populated on the resulting agent links to handle the MQTT protocol logic:
95+
96+
* **MQTT Specific**: `subscriptionTopic`, `publishTopic`.
97+
* **Generic Data Processing**: `valueFilters`, `messageMatchPredicate`, `messageMatchFilters`, `writeValue`, and `writeValueConverter`.
98+
99+
## CSV Import Format
100+
101+
Bulk provisioning allows you to create many assets at once. The agent processes each row to instantiate a new asset, using the specified `assetType` to identify which **template** to apply for automatic link configuration.
102+
103+
### CSV Column Structure
104+
105+
> **Note:** The CSV file must **not** contain a header row. The agent identifies the data based on the specific column order defined below.
106+
107+
| Col | Required | Attribute | Description |
108+
| :--- |:---| :--- |:---|
109+
| 1 | **Y** | `devEUI` | The 16-character hexadecimal unique identifier.|
110+
| 2 | N | `deviceName` | The display name for the asset in OpenRemote.|
111+
| 3 | **Y** | `assetType` | The exact name of the **Asset Type template** (case-sensitive).|
112+
| 4 | N | `vendorId` | The manufacturer of the device.|
113+
| 5 | N | `modelId` | The specific hardware model identifier.|
114+
| 6 | N | `firmwareVersion` | The software version on the device.|
115+
116+
### Example File Content
117+
118+
```csv
119+
a84043d8d1842175,Dragino LHT65 1,DraginoLHT65Asset,dragino,lht65,1.8
120+
a84043d8d1842176,Dragino LHT65 2,DraginoLHT65Asset,dragino,lht65,1.8
121+
```
122+
123+
<AssetTypes />
124+
125+
### Reference Documentation
126+
* **[Agent Link Overview](overview.md)**: Deep dive into generic OpenRemote attributes like filters and predicates.

‎docs/user-guide/agents-protocols/disabled-protocols/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"label": "Disabled Protocols",
3-
"position": 20,
3+
"position": 21,
44
"link": {
55
"type": "generated-index"
66
}

‎docs/user-guide/agents-protocols/email.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 3
2+
sidebar_position: 4
33
---
44

55
# E-mail

‎docs/user-guide/agents-protocols/http.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 4
2+
sidebar_position: 5
33
---
44

55
# HTTP

‎docs/user-guide/agents-protocols/knx.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 5
2+
sidebar_position: 6
33
---
44

55
# KNX

‎docs/user-guide/agents-protocols/lora.md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,22 @@
11
---
2-
sidebar_position: 6
2+
sidebar_position: 7
33
---
44

55
# LoRa
66

7-
OpenRemote supports LoRa integration. You can connect OpenRemote to the most popular LoRa network servers (e.g. ChirpStack and TTN), using their documented APIs. As example we have worked out this [Tutorial: connecting to LoRaWAN sensor data from Chirpstack](../../tutorials/receive-lorawan-sensor-data-from-chirpstack.md).
7+
The documentation on this page focuses on custom protocol implementations built directly on top of the **LoRa PHY (Physical Layer)**, such as mesh networks, rather than standard LoRaWAN network server integrations.
8+
9+
:::note
10+
For standard **LoRaWAN** network server support, please refer to the following protocol documentation:
11+
* **[ChirpStack](chirpstack.md)**
12+
* **[The Things Stack (TTS)](the-things-stack.md)**
13+
14+
If you require a technical deep dive into manual configuration of MQTT agent links, see the **[Manual ChirpStack Tutorial](../../tutorials/receive-lorawan-sensor-data-from-chirpstack.md)**.
15+
:::
816

917
## Proof of concept for LoRa mesh network for GPS trackers
1018

11-
In addition, a couple of students have worked on a generic way to use LoRa to connect several devices in a mesh network and link these through a Protocol Agent with OpenRemote. In the specific application they have developed a Range of LoRa GPS trackers which allow for integrating all these trackers, including their live location within OpenRemote.
19+
A couple of students have worked on a generic way to use LoRa to connect several devices in a mesh network and link these through a Protocol Agent with OpenRemote. In the specific application they have developed a Range of LoRa GPS trackers which allow for integrating all these trackers, including their live location within OpenRemote.
1220

1321
Both the firmware running on the individual devices, as well as the Protocol Agent for OpenRemote is available as a separate project ['or-loratrackers'](https://github.com/openremote/or-loratrackers).
1422
It includes a generic asset and attribute model such that the code can be applied for any kind of application and asset model in which you like to build your own connected network of devices leveraging a mesh.

‎docs/user-guide/agents-protocols/modbus.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 7
2+
sidebar_position: 8
33
---
44

55
# Modbus

‎docs/user-guide/agents-protocols/mqtt.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 8
2+
sidebar_position: 9
33
---
44

55
# MQTT

0 commit comments

Comments
 (0)