Skip to content

Commit af0273c

Browse files
adriansmaresadriansmares
authored
Add relay commands documentation (#1261)
* doc: Add LoRaWAN Relay concepts * doc: Add LoRaWAN Relay settings * doc: Fix anchor link dead zone
1 parent 509d016 commit af0273c

File tree

3 files changed

+205
-8
lines changed

3 files changed

+205
-8
lines changed

‎doc/content/devices/concepts/relay/_index.md

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
title: "Relay"
3+
description: ""
4+
aliases: ["/devices/relay"]
5+
---
6+
7+
This section describes the basic concepts and limitations related to [LoRaWAN® Relay](https://resources.lora-alliance.org/technical-specifications/ts011-1-0-0-relay).
8+
9+
<!--more-->
10+
11+
The relay functionality is introduced as an additional technical specification of the LoRaWAN® protocol, which enables end devices to communicate with a Network Server using another end device as an intermediate hop.
12+
13+
Under normal operations, an end device communicates with a Network Server via one or more gateways. In certain circumstances gateways cannot be installed efficiently in the vicinity of the end devices. An intermediate end device, called a _relay_, can be used to bridge the gap between the end device which is out of reach for gateway coverage, and the nearest gateway.
14+
15+
The relay device is a standard end device, possibly battery powered, which periodically listens on a dedicated channel for a Wake On Radio (WOR) message. The wake on radio message signals to the relay that an end device wants to transmit a message which the relay may re-transmit in order for it to be picked up by a gateway.
16+
17+
The Network Server may also choose to transmit a downlink message to the end device served by the relay, in a dedicated window called RX relay (RXR). As such, bidirectional communication is possible while using relays.
18+
19+
## Concepts
20+
21+
### Relay Mode
22+
23+
End devices can choose to operate in two different relay modes - transmit and receive. A transmitting end device is an end device which wants to use another end device in order communicate with the Network Server. A receiving end device is listening for messages and re-transmits them.
24+
25+
A receiving end device is not forced to operate strictly as a relay. It may conduct its own operations and sends its own messages. As such, the receiving end device is not forced to be a dedicated relay.
26+
27+
Due to overloaded meaning of the word relay (as it refers to the specification, the operation mode of the receiving end device, the capability of the transmitting end device to communicate with a relay, and generally the receive and transmit behavior), {{% tts %}} prefers to call the end device which sends messages to be retransmitted by an intermediary a _served end device_, as it is served by an intermediary end device. An end device which retransmits messages for a served end device is called a _serving end device_.
28+
29+
### Wake On Radio
30+
31+
Traditional gateways can listen on multiple radio channels at the same time, and also on multiple data rates. This capability requires additional hardware and processing power which is generally not available to a standard end device. On the other hand, forcing all communication to take place on a fixed radio channel with fixed transmission parameters is inefficient and can lead to congestion and collisions.
32+
33+
In order to counter balance the limitations above, end devices implementing the relay specification use a dedicated channel called the Wake On Radio (WOR) channel, to signal that a transmission will take place. The signal, called a Wake On Radio message, is sent by the served end device, to be picked up by the serving end device. The serving end device decrypts the Wake On Radio message, and if it decides that it should forward the upcoming message, sends back a Wake On Radio Acknowledgement (WOR-ACK).
34+
35+
The Wake On Radio message does not contain the actual message data - it only contains metadata regarding the upcoming transmission, such as the frequency and the data rate. It is encrypted with a session key which exists between the serving and served end device.
36+
37+
If the served end device receives the WOR-ACK message, or the message to be transmitted is a Join Request, it may choose to transmit the message. Both the serving end device and other gateways may receive this message, and the Network Server can choose which path to use in order to send a downlink message back, if required.
38+
39+
### Channel Activity Detection
40+
41+
Listening continuously for Wake On Radio messages is not suitable for every serving end device, as they may be battery powered. In order to deal with this limitation, serving end devices listen _periodically_ for Wake On Radio messages, using Channel Activity Detection (CAD). The serving end device can sleep between two CAD instances.
42+
43+
### RX Relay
44+
45+
If the end device has received an uplink via a serving end device, it can choose to transmit back a downlink message to the served end device. In order to achieve this, the Network Server wraps the downlink to be sent to the served end device and sends it to the serving end device in the RX1 or RX2 windows of the transmission done by the serving end device. The serving end device then transmits this downlink back to the served end device in the RX relay (RXR) window, which is fixed and occurs 18 seconds after the transmission done by the served end device.
46+
47+
### Additional Channels
48+
49+
If multiple serving end devices are operating in the same area, it may be possible that a single Wake On Radio message 'wakes up' multiple serving end devices at the same time, thus forcing them to listen and process the Wake On Radio message even though it is not addressed to them.
50+
51+
In order to deal with this limitation, an additional channel, sometimes called a secondary channel, can be configured between the served and serving end device, in order to ensure that Wake On Radio messages wake up only the designated serving end device.
52+
53+
### Uplink Forwarding Rules
54+
55+
A standard gateway device will forward all messages received from the end devices to the Network Server. In a sense, a gateway is a transparent component of a LoRaWAN deployment, as it does not do any dedicated processing of the messages.
56+
57+
In contrast, a serving end device will forward only messages from a predefined set of served end devices. This is achieved using uplink forwarding rules, which allow the serving end device to decrypt and process the Wake On Radio messages sent by the served end devices.
58+
59+
### Join Request Forwarding Rules
60+
61+
As Join Request messages occur before a session is in place between an end device and the Network Server, we cannot talk about a way for the serving end device to decide cryptographically if it is should forward the Join Request or not.
62+
63+
In order to deal with this limitation, serving end devices can have a whitelist of DevEUIs and JoinEUIs for which they should forward join requests.
64+
65+
### Forwarding Limits
66+
67+
Served end devices which are configured erroneously, or outright bugged, may transmit LoRaWAN messages very often. Also, Join Requests from malicious devices may mimic real end devices and convince the serving end device to transmit fake Join Requests.
68+
69+
In order to deal with these problems, the serving end device has a system of forwarding limits in place. The limits control how often the serving end device may choose to retransmit messages from served end devices. The limits operate on a refillable bucket basis: every hour new tokens are added into a dedicated bucket, and transmitting a message consumes a token. Without a token, no transmission takes place.
70+
71+
The limits can be configured both on a local and global basis. Local limits apply on a per uplink forwarding rule basis, while global rules apply for the serving end device as a whole.
72+
73+
## Limitations
74+
75+
### Wake On Radio Requirement
76+
77+
Because the serving end device learns about the upcoming transmission via a Wake On Radio message, it logically follows that the served end device must be capable of transmitting such messages. As such, LoRaWAN end devices which do not implement the relay specification cannot participate in the relay protocol.
78+
79+
### Uplink Forwarding Rules Limit
80+
81+
The current relay specification allows at most 16 uplink forwarding rules. As such, at most 16 served end devices may be attached to a serving end device.
82+
83+
### Join Request Forwarding Rules Limit
84+
85+
The current relay specification allows at most 15 join request forwarding rules. In certain circumstances this may mean that a whitelist approach cannot be used.
86+

‎doc/content/devices/configuring-devices/relay-settings/_index.md

+117
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
title: "Relay Settings"
3+
description: ""
4+
aliases: ["/devices/relay-settings"]
5+
---
6+
7+
This section provides guidelines for configuring [relay]({{< ref "/devices/concepts/relay" >}}) settings for end devices via CLI.
8+
9+
<!--more-->
10+
11+
{{< cli-only >}}
12+
13+
## Retroactivity
14+
15+
In contrast to [MAC settings]({{< ref "/devices/configuring-devices/mac-settings" >}}), the relay configuration commands will automatically apply changes to both the current, pending and future sessions of the end devices.
16+
17+
## Examples
18+
19+
### Enabling the Serving Mode {{< new-in-version "3.29.0">}}
20+
21+
In order to enable the [serving mode]({{< ref "/devices/concepts/relay#relay-mode" >}}) of an end device, use the `create` command and the `--mode.serving` parameter.
22+
23+
```bash
24+
ttn-lw-cli relays create <app-id> <device-id> --mode.serving
25+
```
26+
27+
### Enabling the Served Mode {{< new-in-version "3.29.0">}}
28+
29+
In order to enable the [served mode]({{< ref "/devices/concepts/relay#relay-mode" >}}) of an end device, use the `create` command and the `--mode.served` flag.
30+
31+
{{< note "A serving end device must already exist." />}}
32+
33+
```bash
34+
ttn-lw-cli relays create <app-id> <device-id> --mode.served.mode.end-device-controlled --mode.served.serving-device-id <serving-device-id>
35+
```
36+
37+
Multiple modes of operations are available for a served end device:
38+
1. A device may always attempt to use the serving end device before transmitting an uplink message. This mode is called _always_, and can be used using the `--mode.served.mode.always` flag.
39+
2. A device may attempt to use the serving end device only after it has not received a downlink message recently. This mode is called _dynamic_, and can be used using the `--mode.served.mode.dynamic` flag.
40+
3. A device may have its own algorithm to choose when to use the serving end device. This mode is called _end device controlled_, and can be used using the `--mode.served.mode.end-device-controlled` flag.
41+
42+
### Retrieving the Settings {{< new-in-version "3.29.0">}}
43+
44+
In order to retrieve the settings of a serving end device, use the `get` command.
45+
46+
```bash
47+
ttn-lw-cli relays get <app-id> <device-id> --mode.serving
48+
```
49+
50+
The `--mode.served` may be used to retrieve the settings of a served end device.
51+
52+
### Updating the Settings {{< new-in-version "3.29.0">}}
53+
54+
In order to update the settings of an end device, use the `set` command.
55+
56+
```bash
57+
ttn-lw-cli relays set <app-id> <device-id> --mode.serving.cad-periodicity 1
58+
```
59+
60+
You can see the possible parameters which can be updated using the `--help` flag.
61+
62+
### Removing the Settings {{< new-in-version "3.29.0">}}
63+
64+
In order to delete all of the relay settings of an end device, use the `delete` command.
65+
66+
```bash
67+
ttn-lw-cli relays delete <app-id> <device-id>
68+
```
69+
70+
### Creating an Uplink Forwarding Rule {{< new-in-version "3.29.0">}}
71+
72+
In order to create an uplink forwarding rule on a serving end device, for a served end device, use the `uplink-forwarding-rules create` command.
73+
74+
{{< note "Rule IDs are strictly positive integers between 0 and 15." />}}
75+
{{< note "The served end device must be in the same application as the serving end device." />}}
76+
77+
```bash
78+
ttn-lw-cli relays uplink-forwarding-rules create <app-id> <device-id> <rule-id> --device-id <served-device-id>
79+
```
80+
81+
### Retrieving All Uplink Forwarding Rules {{< new-in-version "3.29.0">}}
82+
83+
In order to retrieve all of the uplink forwarding rules of a serving end device, use the `uplink-forwarding-rules list` command.
84+
85+
```bash
86+
ttn-lw-cli relays uplink-forwarding-rules list <app-id> <device-id> --device-id
87+
```
88+
89+
Like other `list`-like commands in {{% tts %}}, the fields which are returned have to be specified in the command flags. Use the `--help` flags to see which other fields can be retrieved.
90+
91+
### Retrieving Individual Uplink Forwarding Rules {{< new-in-version "3.29.0">}}
92+
93+
In order to retrieve an individual uplink forwarding rule of a serving end device, use the `uplink-forwarding-rules get` command.
94+
95+
```bash
96+
ttn-lw-cli relays uplink-forwarding-rules get <app-id> <device-id> <rule-id>
97+
```
98+
99+
Like other `get`-like commands in {{% tts %}}, the fields which are returned have to be specified in the command flags. Use the `--help` flags to see which other fields can be retrieved.
100+
101+
### Updating Uplink Forwarding Rules {{< new-in-version "3.29.0">}}
102+
103+
In order to update an uplink forwarding rule of a serving end device, use the `uplink-forwarding-rules set` command.
104+
105+
```bash
106+
ttn-lw-cli relays uplink-forwarding-rules set <app-id> <device-id> <rule-id> --device-id <serving-device-id>
107+
```
108+
109+
You can see the possible parameters which can be updated using the `--help` flag.
110+
111+
### Deleting Uplink Forwarding Rules {{< new-in-version "3.29.0">}}
112+
113+
In order to delete an uplink forwarding rule of a serving end device, use the `uplink-forwarding-rules delete` command.
114+
115+
```bash
116+
ttn-lw-cli relays uplink-forwarding-rules delete <app-id> <device-id> <rule-id>
117+
```

‎doc/themes/the-things-stack/assets/css/common/global.scss

+2-8
Original file line numberDiff line numberDiff line change
@@ -127,14 +127,8 @@ table.fixed td { overflow: auto; }
127127

128128
// Fix for anchor link headbutting https://css-tricks.com/hash-tag-links-padding/
129129
.content {
130-
h2::before, h3::before, h4::before {
131-
display: block;
132-
content: " ";
133-
margin-top: -$navbar-height - 1rem;
134-
height: $navbar-height + 1rem;
135-
visibility: hidden;
136-
pointer-events: none;
137-
z-index: -1;
130+
h2, h3, h4 {
131+
scroll-margin-top: 0.25em;
138132
}
139133
}
140134

0 commit comments

Comments
 (0)