Skip to content

Commit 54117e9

Browse files
TD-erTD-er
authored
Merge pull request #2546 from TD-er/feature/LoRaTTN_decoder
[LoRa/TTN] Add raw packed decoder (more values, less data) & reduce joins
2 parents aba4d88 + 49a7b54 commit 54117e9

20 files changed

+1540
-625
lines changed

‎docs/source/Controller/C018.rst

Lines changed: 125 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,131 @@ Change log
2727
...
2828

2929
|added|
30-
Initial release version.
30+
2019/08/13 First occurrence in the source.
3131

3232
Description
3333
-----------
34+
35+
`The Things Network (TTN) <https://www.thethingsnetwork.org/>`_ is a global open LoRaWAN network.
36+
LoRaWAN allows low power communication over distances of several km.
37+
38+
A typical use case is a sensor "in the field" which only has to send a few sample values every few minutes.
39+
Such a sensor node does broadcast its message and hopefully one or more gateways may hear the message and route it over the connected network to a server.
40+
41+
The data packets for this kind of cummunication have to be very short (max. 50 bytes) and a sender is only allowed to send for a limited amount of time.
42+
On most frequencies used for the LoRa networks there is a limit of 1% of the time allowed to send.
43+
44+
Such a time limit does also apply for a gateway. This implies that most traffic will be "uplink" data from a node to a gateway.
45+
The analogy here is that the gateway is often mounted as high as possible while the node is at ground level ("in the field")
46+
47+
There is "downlink" traffic possible, for example to notify some change of settings to a node, or simply to help the node to join the network.
48+
49+
In order to communicate with the gateways in the TTN network, you need a LoRa/LoRaWAN radio module.
50+
51+
The radio module does communicate via the LoRa protocol. On top of that you also need a layer for authentication, encryption and routing of data packets.
52+
This layer is called LoRaWAN.
53+
54+
There are several modules available:
55+
56+
- RFM95 & SX127x. These are LoRa modules which needs to have the LoRaWAN stack implemented in software
57+
- Microchip RN2384/RN2903. These are the modules supported in this controller. They have the full LoRaWAN stack present in the module.
58+
59+
60+
Nodes, Gateways, Application
61+
----------------------------
62+
63+
A typical flow of data on The Things Network (TTN) is to have multiple nodes collecting data for a specific use case.
64+
65+
Such a use case is called an "Application" on The Things Network.
66+
For example, a farmer likes to keep track of the feeding machines for his cattle.
67+
68+
So let us call this application "farmer-john-cattle".
69+
70+
For this application, a number of nodes is needed to keep track of the feeding machines in the field.
71+
These nodes are called "Devices" in TTH terms.
72+
For example a device is needed to measure the amount of water in the water tank and one for the food supply.
73+
74+
Such a device must be defined on the TTN console page.
75+
76+
There are two means of authenticating a device to the network (this is called "Join" in TTN terms):
77+
- OTAA - Over-The-Air Authentication
78+
- ABP - activation by personalization
79+
80+
With OTAA, a device broadcasts a join request and one of the gateways in the neighborhood that received this request,
81+
will return a reply with the appropriate application- and network- session keys to handle further communication.
82+
83+
This means the device can only continue if there is a gateway in range at the moment of joining.
84+
It may happen that a gateway does receive the join request, but the device is unable to receive the reply.
85+
When that's happening, the device will not be able to send data to the network since it cannot complete the join.
86+
Another disadvantage of OTAA authenticating is the extra time needed to wait for the reply.
87+
Especially on battery powered devices the extra energy needed may shorten the battery life significantly.
88+
89+
With OTAA, the device is given 3 keys to perform the join:
90+
91+
- Device EUI - An unique 64 bit key on the network.
92+
- Application EUI - An unique 64 bit key generated for the application.
93+
- App Key - A 128 bit key needed to exchange keys with the application.
94+
95+
The result of such an OTAA join is again a set of 3 keys:
96+
97+
- Device Address - An almost unique 32 bit address of your device.
98+
- Network Session Key - 128 bit key to access the network.
99+
- Application Session Key - 128 bit key to encrypt the data for your application.
100+
101+
102+
The other method of authenticating a device is via ABP.
103+
ABP is nothing other than storing the last 3 keys directly on the device itself and thus skipping the OTAA join request.
104+
This means you don't need to receive data on the device and can start sending immediately, and even more important, let your device sleep immediately after sending.
105+
106+
A disadvantage is the deployment of the device. Every device does need to have an unique set of ABP keys generated and stored on the device.
107+
108+
Updating session keys may also be a bit hard to do, since it does need to ask for an update and must also be able to receive that update.
109+
110+
111+
112+
Hybrid OTAA/ABP
113+
---------------
114+
115+
TODO TD-er.
116+
117+
118+
119+
120+
121+
122+
Configure LoRaWAN node for TTN
123+
------------------------------
124+
125+
A LoRaWAN device must join the network in order to be able to route the packets to the right user account.
126+
127+
Prerequisites:
128+
129+
- An user account on the TTN network.
130+
- A TTN gateway in range to send data to (and receive data from)
131+
- Microchip RN2384 or RN2903 LoRaWAN module connected to a node running ESPeasy. (UART connection)
132+
133+
On the TTN network:
134+
- Create an application
135+
- Add a device to the application, either using OTAA or ABP.
136+
137+
In order to create a new device using OTAA, one must either copy the hardware Device EUI key from the device to the TTN console page,
138+
or generate one and enter it into the controller setup page in ESPeasy.
139+
The Application EUI and App Key must be copied from the TTN console page to the ESPeasy controller configuration page.
140+
141+
Using these steps, a device address is generated.
142+
Such an address looks like this: "26 01 20 47"
143+
Also the Network Session Key and Application Session Key can be retrieved from this page and can even be used as if the device is using ABP to join the network.
144+
But keep in mind, these 3 keys will be changed as soon as an OTAA join is performed.
145+
146+
Device configuration with solely an ABP setup are more persistent.
147+
148+
149+
Decoding Data
150+
-------------
151+
152+
153+
Controller Settings
154+
-------------------
155+
156+
157+

‎docs/source/Controller/_Controller.rst

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,12 @@ before WiFi connection is made or during lost connection.
6161
- **Max Queue Depth** - Maximum length of the buffer queue to keep unsent messages.
6262
- **Max Retries** - Maximum number of retries to send a message.
6363
- **Full Queue Action** - How to handle when queue is full, ignore new or delete oldest message.
64-
- **Client Timeout** - Timeout in msec for an network connection used by the controller.
6564
- **Check Reply** - When set to false, a sent message is considered always successful.
65+
- **Client Timeout** - Timeout in msec for an network connection used by the controller.
66+
- **Sample Set Initiator** - Some controllers (e.g. C018 LoRa/TTN) can mark samples to belong to a set of samples. A new sample from set task index will increment this counter.
67+
Especially useful for controllers which cannot send samples in a burst. This makes the receiving time stamp useless to detect what samples were taken around the same time.
68+
The sample set counter value can help matching received samples to a single set.
69+
6670

6771

6872
Sample ThingSpeak configuration
@@ -93,3 +97,5 @@ MQTT related settings
9397
- **Controller lwl topic** - Topic to which LWT (Last Will Testament) messages should be sent.
9498
- **LWT Connect Message** - Connection established message.
9599
- **LWT Disconnect Message** - Connection lost message (sent to broker during connect and published by broker when connection is lost)
100+
101+

‎docs/source/Controller/_controller_substitutions.repl

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,6 @@
184184
.. |C018_github| replace:: C018.ino
185185
.. _C018_github: https://github.com/letscontrolit/ESPEasy/blob/mega/src/_C018.ino
186186
.. |C018_usedby| replace:: `.`
187-
.. |C018_shortinfo| replace:: `.`
187+
.. |C018_shortinfo| replace:: `Controller for the LoRaWAN/TTN network supporting RN2384 (434/868 MHz) and RN2903 (915 MHz)`
188188
.. |C018_maintainer| replace:: `TD-er`
189189
.. |C018_compileinfo| replace:: `.`

‎lib/ESPEasySerial/ESPeasySerial.h

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,10 @@ class ESPeasySerial : public Stream
246246

247247
using Print::write;
248248

249+
int getRxPin() const { return _receivePin; }
250+
int getTxPin() const { return _transmitPin; }
251+
unsigned long getBaudRate() const { return _baud; }
252+
249253
private:
250254

251255
const HardwareSerial* getHW() const;

0 commit comments

Comments
 (0)