RadioLib
Universal wireless communication library for Arduino
Loading...
Searching...
No Matches
LoRaWAN.h
1#if !defined(_RADIOLIB_LORAWAN_H) && !RADIOLIB_EXCLUDE_LORAWAN
2#define _RADIOLIB_LORAWAN_H
3
4#include "../../TypeDef.h"
5#include "../PhysicalLayer/PhysicalLayer.h"
6#include "../../utils/Cryptography.h"
7
8// activation mode
9#define RADIOLIB_LORAWAN_MODE_OTAA (0x07AA)
10#define RADIOLIB_LORAWAN_MODE_ABP (0x0AB9)
11#define RADIOLIB_LORAWAN_MODE_NONE (0x0000)
12
13// operation mode
14#define RADIOLIB_LORAWAN_CLASS_A (0x00)
15#define RADIOLIB_LORAWAN_CLASS_B (0x01)
16#define RADIOLIB_LORAWAN_CLASS_C (0x02)
17
18// preamble format
19#define RADIOLIB_LORAWAN_LORA_SYNC_WORD (0x34)
20#define RADIOLIB_LORAWAN_LORA_PREAMBLE_LEN (8)
21#define RADIOLIB_LORAWAN_GFSK_SYNC_WORD (0xC194C1)
22#define RADIOLIB_LORAWAN_GFSK_PREAMBLE_LEN (5)
23#define RADIOLIB_LORAWAN_LR_FHSS_SYNC_WORD (0x2C0F7995)
24
25// MAC header field encoding MSB LSB DESCRIPTION
26#define RADIOLIB_LORAWAN_MHDR_MTYPE_JOIN_REQUEST (0x00 << 5) // 7 5 message type: join request
27#define RADIOLIB_LORAWAN_MHDR_MTYPE_JOIN_ACCEPT (0x01 << 5) // 7 5 join accept
28#define RADIOLIB_LORAWAN_MHDR_MTYPE_UNCONF_DATA_UP (0x02 << 5) // 7 5 unconfirmed data up
29#define RADIOLIB_LORAWAN_MHDR_MTYPE_UNCONF_DATA_DOWN (0x03 << 5) // 7 5 unconfirmed data down
30#define RADIOLIB_LORAWAN_MHDR_MTYPE_CONF_DATA_UP (0x04 << 5) // 7 5 confirmed data up
31#define RADIOLIB_LORAWAN_MHDR_MTYPE_CONF_DATA_DOWN (0x05 << 5) // 7 5 confirmed data down
32#define RADIOLIB_LORAWAN_MHDR_MTYPE_PROPRIETARY (0x07 << 5) // 7 5 proprietary
33#define RADIOLIB_LORAWAN_MHDR_MTYPE_MASK (0x07 << 5) // 7 5 bitmask of all possible options
34#define RADIOLIB_LORAWAN_MHDR_MAJOR_R1 (0x00 << 0) // 1 0 major version: LoRaWAN R1
35
36// frame control field encoding
37#define RADIOLIB_LORAWAN_FCTRL_ADR_ENABLED (0x01 << 7) // 7 7 adaptive data rate: enabled
38#define RADIOLIB_LORAWAN_FCTRL_ADR_DISABLED (0x00 << 7) // 7 7 disabled
39#define RADIOLIB_LORAWAN_FCTRL_ADR_ACK_REQ (0x01 << 6) // 6 6 adaptive data rate ACK request
40#define RADIOLIB_LORAWAN_FCTRL_ACK (0x01 << 5) // 5 5 confirmed message acknowledge
41#define RADIOLIB_LORAWAN_FCTRL_FRAME_PENDING (0x01 << 4) // 4 4 downlink frame is pending
42
43// fPort field
44#define RADIOLIB_LORAWAN_FPORT_MAC_COMMAND (0x00 << 0) // 7 0 payload contains MAC commands only
45#define RADIOLIB_LORAWAN_FPORT_PAYLOAD_MIN (0x01 << 0) // 7 0 start of user-allowed fPort range
46#define RADIOLIB_LORAWAN_FPORT_PAYLOAD_MAX (0xDF << 0) // 7 0 end of user-allowed fPort range
47#define RADIOLIB_LORAWAN_FPORT_TS009 (0xE0 << 0) // 7 0 fPort used for TS009 testing
48#define RADIOLIB_LORAWAN_FPORT_TS011 (0xE2 << 0) // 7 0 fPort used for TS011 Forwarding
49#define RADIOLIB_LORAWAN_FPORT_RESERVED (0xE0 << 0) // 7 0 fPort values equal to and larger than this are reserved
50
51// data rate encoding
52#define RADIOLIB_LORAWAN_DATA_RATE_MODEM (0x03 << 6) // 7 6 modem mask
53#define RADIOLIB_LORAWAN_DATA_RATE_LORA (0x00 << 6) // 7 6 use LoRa modem
54#define RADIOLIB_LORAWAN_DATA_RATE_FSK (0x01 << 6) // 7 6 use FSK modem
55#define RADIOLIB_LORAWAN_DATA_RATE_LR_FHSS (0x02 << 6) // 7 6 use LR-FHSS modem
56#define RADIOLIB_LORAWAN_DATA_RATE_SF (0x07 << 3) // 5 3 LoRa spreading factor mask
57#define RADIOLIB_LORAWAN_DATA_RATE_SF_12 (0x05 << 3) // 5 3 LoRa spreading factor: SF12
58#define RADIOLIB_LORAWAN_DATA_RATE_SF_11 (0x04 << 3) // 5 3 SF11
59#define RADIOLIB_LORAWAN_DATA_RATE_SF_10 (0x03 << 3) // 5 3 SF10
60#define RADIOLIB_LORAWAN_DATA_RATE_SF_9 (0x02 << 3) // 5 3 SF9
61#define RADIOLIB_LORAWAN_DATA_RATE_SF_8 (0x01 << 3) // 5 3 SF8
62#define RADIOLIB_LORAWAN_DATA_RATE_SF_7 (0x00 << 3) // 5 3 SF7
63#define RADIOLIB_LORAWAN_DATA_RATE_BW (0x03 << 1) // 2 1 bandwidth mask
64#define RADIOLIB_LORAWAN_DATA_RATE_BW_125_KHZ (0x00 << 1) // 2 1 125 kHz
65#define RADIOLIB_LORAWAN_DATA_RATE_BW_250_KHZ (0x01 << 1) // 2 1 250 kHz
66#define RADIOLIB_LORAWAN_DATA_RATE_BW_500_KHZ (0x02 << 1) // 2 1 LoRa bandwidth: 500 kHz
67#define RADIOLIB_LORAWAN_DATA_RATE_BW_137_KHZ (0x00 << 1) // 2 1 137 kHz
68#define RADIOLIB_LORAWAN_DATA_RATE_BW_336_KHZ (0x01 << 1) // 2 1 336 kHz
69#define RADIOLIB_LORAWAN_DATA_RATE_BW_1523_KHZ (0x02 << 1) // 2 1 LR-FHSS bandwidth: 1523 kHz
70#define RADIOLIB_LORAWAN_DATA_RATE_CR (0x01 << 0) // 0 0 coding rate mask
71#define RADIOLIB_LORAWAN_DATA_RATE_CR_1_3 (0x00 << 0) // 0 0 LR-FHSS coding rate: 1/3
72#define RADIOLIB_LORAWAN_DATA_RATE_CR_2_3 (0x01 << 0) // 0 0 2/3
73#define RADIOLIB_LORAWAN_DATA_RATE_UNUSED (0xFF << 0) // 7 0 unused data rate
74
75// channels and channel plans
76#define RADIOLIB_LORAWAN_UPLINK (0x00 << 0)
77#define RADIOLIB_LORAWAN_DOWNLINK (0x01 << 0)
78#define RADIOLIB_LORAWAN_RX1 (0x01 << 0)
79#define RADIOLIB_LORAWAN_RX2 (0x02 << 0)
80#define RADIOLIB_LORAWAN_RX_BC (0x03 << 0)
81#define RADIOLIB_LORAWAN_BAND_DYNAMIC (0)
82#define RADIOLIB_LORAWAN_BAND_FIXED (1)
83#define RADIOLIB_LORAWAN_CHANNEL_NUM_DATARATES (15)
84#define RADIOLIB_LORAWAN_CHANNEL_INDEX_NONE (0xFF >> 0)
85
86// recommended default settings
87#define RADIOLIB_LORAWAN_RECEIVE_DELAY_1_MS (1000)
88#define RADIOLIB_LORAWAN_RECEIVE_DELAY_2_MS ((RADIOLIB_LORAWAN_RECEIVE_DELAY_1_MS) + 1000)
89#define RADIOLIB_LORAWAN_RX1_DR_OFFSET (0)
90#define RADIOLIB_LORAWAN_JOIN_ACCEPT_DELAY_1_MS (5000)
91#define RADIOLIB_LORAWAN_JOIN_ACCEPT_DELAY_2_MS (6000)
92#define RADIOLIB_LORAWAN_ADR_ACK_LIMIT_EXP (0x06)
93#define RADIOLIB_LORAWAN_ADR_ACK_DELAY_EXP (0x05)
94#define RADIOLIB_LORAWAN_RETRANSMIT_TIMEOUT_MIN_MS (1000)
95#define RADIOLIB_LORAWAN_RETRANSMIT_TIMEOUT_MAX_MS (3000)
96#define RADIOLIB_LORAWAN_POWER_STEP_SIZE_DBM (-2)
97#define RADIOLIB_LORAWAN_REJOIN_MAX_COUNT_N (10) // send rejoin request 16384 uplinks
98#define RADIOLIB_LORAWAN_REJOIN_MAX_TIME_N (15) // once every year, not actually implemented
99
100// join request message layout
101#define RADIOLIB_LORAWAN_JOIN_REQUEST_LEN (23)
102#define RADIOLIB_LORAWAN_JOIN_REQUEST_JOIN_EUI_POS (1)
103#define RADIOLIB_LORAWAN_JOIN_REQUEST_DEV_EUI_POS (9)
104#define RADIOLIB_LORAWAN_JOIN_REQUEST_DEV_NONCE_POS (17)
105#define RADIOLIB_LORAWAN_JOIN_REQUEST_TYPE (0xFF)
106#define RADIOLIB_LORAWAN_JOIN_REQUEST_TYPE_0 (0x00)
107#define RADIOLIB_LORAWAN_JOIN_REQUEST_TYPE_1 (0x01)
108#define RADIOLIB_LORAWAN_JOIN_REQUEST_TYPE_2 (0x02)
109
110// join accept message layout
111#define RADIOLIB_LORAWAN_JOIN_ACCEPT_MAX_LEN (33)
112#define RADIOLIB_LORAWAN_JOIN_ACCEPT_JOIN_NONCE_POS (1)
113#define RADIOLIB_LORAWAN_JOIN_ACCEPT_HOME_NET_ID_POS (4)
114#define RADIOLIB_LORAWAN_JOIN_ACCEPT_DEV_ADDR_POS (7)
115#define RADIOLIB_LORAWAN_JOIN_ACCEPT_DL_SETTINGS_POS (11)
116#define RADIOLIB_LORAWAN_JOIN_ACCEPT_RX_DELAY_POS (12)
117#define RADIOLIB_LORAWAN_JOIN_ACCEPT_CFLIST_POS (13)
118#define RADIOLIB_LORAWAN_JOIN_ACCEPT_CFLIST_LEN (16)
119#define RADIOLIB_LORAWAN_JOIN_ACCEPT_CFLIST_TYPE_POS (RADIOLIB_LORAWAN_JOIN_ACCEPT_CFLIST_POS + RADIOLIB_LORAWAN_JOIN_ACCEPT_CFLIST_LEN - 1)
120
121// join accept key derivation layout
122#define RADIOLIB_LORAWAN_JOIN_ACCEPT_AES_JOIN_NONCE_POS (1) // regular keys
123#define RADIOLIB_LORAWAN_JOIN_ACCEPT_AES_JOIN_EUI_POS (4)
124#define RADIOLIB_LORAWAN_JOIN_ACCEPT_AES_DEV_NONCE_POS (12)
125#define RADIOLIB_LORAWAN_JOIN_ACCEPT_AES_DEV_ADDR_POS (1) // relay keys
126
127// join accept message variables
128#define RADIOLIB_LORAWAN_JOIN_ACCEPT_R_1_0 (0x00 << 7) // 7 7 LoRaWAN revision: 1.0
129#define RADIOLIB_LORAWAN_JOIN_ACCEPT_R_1_1 (0x01 << 7) // 7 7 1.1
130#define RADIOLIB_LORAWAN_JOIN_ACCEPT_F_NWK_S_INT_KEY (0x01)
131#define RADIOLIB_LORAWAN_JOIN_ACCEPT_APP_S_KEY (0x02)
132#define RADIOLIB_LORAWAN_JOIN_ACCEPT_S_NWK_S_INT_KEY (0x03)
133#define RADIOLIB_LORAWAN_JOIN_ACCEPT_NWK_S_ENC_KEY (0x04)
134#define RADIOLIB_LORAWAN_JOIN_ACCEPT_JS_ENC_KEY (0x05)
135#define RADIOLIB_LORAWAN_JOIN_ACCEPT_JS_INT_KEY (0x06)
136#define RADIOLIB_LORAWAN_JOIN_ACCEPT_ROOT_WOR_S_KEY (0x01)
137#define RADIOLIB_LORAWAN_JOIN_ACCEPT_WOR_S_INT_KEY (0x01)
138#define RADIOLIB_LORAWAN_JOIN_ACCEPT_WOR_S_ENC_KEY (0x02)
139
140// frame header layout
141#define RADIOLIB_LORAWAN_FHDR_LEN_START_OFFS (16)
142#define RADIOLIB_LORAWAN_FHDR_DEV_ADDR_POS (RADIOLIB_LORAWAN_FHDR_LEN_START_OFFS + 1)
143#define RADIOLIB_LORAWAN_FHDR_FCTRL_POS (RADIOLIB_LORAWAN_FHDR_LEN_START_OFFS + 5)
144#define RADIOLIB_LORAWAN_FHDR_FCNT_POS (RADIOLIB_LORAWAN_FHDR_LEN_START_OFFS + 6)
145#define RADIOLIB_LORAWAN_FHDR_FOPTS_POS (RADIOLIB_LORAWAN_FHDR_LEN_START_OFFS + 8)
146#define RADIOLIB_LORAWAN_FHDR_FOPTS_LEN_MASK (0x0F)
147#define RADIOLIB_LORAWAN_FHDR_FOPTS_MAX_LEN (15)
148#define RADIOLIB_LORAWAN_FHDR_FPORT_POS(FOPTS) (RADIOLIB_LORAWAN_FHDR_LEN_START_OFFS + 8 + (FOPTS))
149#define RADIOLIB_LORAWAN_FRAME_PAYLOAD_POS(FOPTS) (RADIOLIB_LORAWAN_FHDR_LEN_START_OFFS + 9 + (FOPTS))
150#define RADIOLIB_LORAWAN_FRAME_LEN(PAYLOAD, FOPTS) (16 + 13 + (PAYLOAD) + (FOPTS))
151
152// payload encryption/MIC blocks common layout
153#define RADIOLIB_LORAWAN_BLOCK_MAGIC_POS (0)
154#define RADIOLIB_LORAWAN_BLOCK_CONF_FCNT_POS (1)
155#define RADIOLIB_LORAWAN_BLOCK_DIR_POS (5)
156#define RADIOLIB_LORAWAN_BLOCK_DEV_ADDR_POS (6)
157#define RADIOLIB_LORAWAN_BLOCK_FCNT_POS (10)
158
159// payload encryption block layout
160#define RADIOLIB_LORAWAN_ENC_BLOCK_MAGIC (0x01)
161#define RADIOLIB_LORAWAN_ENC_BLOCK_COUNTER_ID_POS (4)
162#define RADIOLIB_LORAWAN_ENC_BLOCK_COUNTER_POS (15)
163
164// payload MIC blocks layout
165#define RADIOLIB_LORAWAN_MIC_BLOCK_MAGIC (0x49)
166#define RADIOLIB_LORAWAN_MIC_BLOCK_LEN_POS (15)
167#define RADIOLIB_LORAWAN_MIC_DATA_RATE_POS (3)
168#define RADIOLIB_LORAWAN_MIC_CH_INDEX_POS (4)
169
170// maximum allowed dwell time on bands that implement dwell time limitations
171#define RADIOLIB_LORAWAN_DWELL_TIME (400)
172
173// unused frame counter value
174#define RADIOLIB_LORAWAN_FCNT_NONE (0xFFFFFFFF)
175
176// TR013 CSMA recommended values
177#define RADIOLIB_LORAWAN_DIFS_DEFAULT (2)
178#define RADIOLIB_LORAWAN_BACKOFF_MAX_DEFAULT (6)
179#define RADIOLIB_LORAWAN_MAX_CHANGES_DEFAULT (4)
180
181// MAC commands
182#define RADIOLIB_LORAWAN_NUM_MAC_COMMANDS (24)
183
184#define RADIOLIB_LORAWAN_MAC_RESET (0x01)
185#define RADIOLIB_LORAWAN_MAC_LINK_CHECK (0x02)
186#define RADIOLIB_LORAWAN_MAC_LINK_ADR (0x03)
187#define RADIOLIB_LORAWAN_MAC_DUTY_CYCLE (0x04)
188#define RADIOLIB_LORAWAN_MAC_RX_PARAM_SETUP (0x05)
189#define RADIOLIB_LORAWAN_MAC_DEV_STATUS (0x06)
190#define RADIOLIB_LORAWAN_MAC_NEW_CHANNEL (0x07)
191#define RADIOLIB_LORAWAN_MAC_RX_TIMING_SETUP (0x08)
192#define RADIOLIB_LORAWAN_MAC_TX_PARAM_SETUP (0x09)
193#define RADIOLIB_LORAWAN_MAC_DL_CHANNEL (0x0A)
194#define RADIOLIB_LORAWAN_MAC_REKEY (0x0B)
195#define RADIOLIB_LORAWAN_MAC_ADR_PARAM_SETUP (0x0C)
196#define RADIOLIB_LORAWAN_MAC_DEVICE_TIME (0x0D)
197#define RADIOLIB_LORAWAN_MAC_FORCE_REJOIN (0x0E)
198#define RADIOLIB_LORAWAN_MAC_REJOIN_PARAM_SETUP (0x0F)
199#define RADIOLIB_LORAWAN_MAC_DEVICE_MODE (0x20)
200#define RADIOLIB_LORAWAN_MAC_PROPRIETARY (0x80)
201
202// the length of internal MAC command queue - hopefully this is enough for most use cases
203#define RADIOLIB_LORAWAN_MAC_COMMAND_QUEUE_SIZE (9)
204
205// the maximum number of simultaneously available channels
206#define RADIOLIB_LORAWAN_NUM_AVAILABLE_CHANNELS (16)
207
208// maximum MAC command sizes
209#define RADIOLIB_LORAWAN_MAX_MAC_COMMAND_LEN_DOWN (5)
210#define RADIOLIB_LORAWAN_MAX_MAC_COMMAND_LEN_UP (2)
211#define RADIOLIB_LORAWAN_MAX_NUM_ADR_COMMANDS (8)
212
213#define RADIOLIB_LORAWAN_MAX_DOWNLINK_SIZE (250)
214
215// threshold at which sleeping via user callback enabled, in ms
216#define RADIOLIB_LORAWAN_DELAY_SLEEP_THRESHOLD (50)
217
224 const uint8_t cid;
225
227 const uint8_t lenDn;
228
230 const uint8_t lenUp;
231
233 const bool persist;
234
236 const bool user;
237};
238
239#define RADIOLIB_LORAWAN_MAC_COMMAND_NONE { .cid = 0, .lenDn = 0, .lenUp = 0, .persist = false, .user = false }
240
241constexpr LoRaWANMacCommand_t MacTable[RADIOLIB_LORAWAN_NUM_MAC_COMMANDS] = {
242 { RADIOLIB_LORAWAN_MAC_RESET, 1, 1, true, false },
243 { RADIOLIB_LORAWAN_MAC_LINK_CHECK, 2, 0, false, true },
244 { RADIOLIB_LORAWAN_MAC_LINK_ADR, 4, 1, false, false },
245 { RADIOLIB_LORAWAN_MAC_DUTY_CYCLE, 1, 0, false, false },
246 { RADIOLIB_LORAWAN_MAC_RX_PARAM_SETUP, 4, 1, true, false },
247 { RADIOLIB_LORAWAN_MAC_DEV_STATUS, 0, 2, false, false },
248 { RADIOLIB_LORAWAN_MAC_NEW_CHANNEL, 5, 1, false, false },
249 { RADIOLIB_LORAWAN_MAC_RX_TIMING_SETUP, 1, 0, true, false },
250 { RADIOLIB_LORAWAN_MAC_TX_PARAM_SETUP, 1, 0, true, false },
251 { RADIOLIB_LORAWAN_MAC_DL_CHANNEL, 4, 1, true, false },
252 { RADIOLIB_LORAWAN_MAC_REKEY, 1, 1, true, false },
253 { RADIOLIB_LORAWAN_MAC_ADR_PARAM_SETUP, 1, 0, false, false },
254 { RADIOLIB_LORAWAN_MAC_DEVICE_TIME, 5, 0, false, true },
255 { RADIOLIB_LORAWAN_MAC_FORCE_REJOIN, 2, 0, false, false },
256 { RADIOLIB_LORAWAN_MAC_REJOIN_PARAM_SETUP, 1, 1, false, false },
257 { RADIOLIB_LORAWAN_MAC_DEVICE_MODE, 1, 1, true, false },
258 { RADIOLIB_LORAWAN_MAC_PROPRIETARY, 5, 0, false, true },
259};
260
261#define RADIOLIB_LORAWAN_NONCES_VERSION_VAL (0x0001)
262
263enum LoRaWANSchemeBase_t {
264 RADIOLIB_LORAWAN_NONCES_START = 0x00,
265 RADIOLIB_LORAWAN_NONCES_VERSION = RADIOLIB_LORAWAN_NONCES_START, // 2 bytes
266 RADIOLIB_LORAWAN_NONCES_MODE = RADIOLIB_LORAWAN_NONCES_VERSION + sizeof(uint16_t), // 2 bytes
267 RADIOLIB_LORAWAN_NONCES_PLAN = RADIOLIB_LORAWAN_NONCES_MODE + sizeof(uint16_t), // 1 byte
268 RADIOLIB_LORAWAN_NONCES_CHECKSUM = RADIOLIB_LORAWAN_NONCES_PLAN + sizeof(uint8_t), // 2 bytes
269 RADIOLIB_LORAWAN_NONCES_DEV_NONCE = RADIOLIB_LORAWAN_NONCES_CHECKSUM + sizeof(uint16_t), // 2 bytes
270 RADIOLIB_LORAWAN_NONCES_JOIN_NONCE = RADIOLIB_LORAWAN_NONCES_DEV_NONCE + sizeof(uint16_t), // 3 bytes
271 RADIOLIB_LORAWAN_NONCES_ACTIVE = RADIOLIB_LORAWAN_NONCES_JOIN_NONCE + 3, // 1 byte
272 RADIOLIB_LORAWAN_NONCES_SIGNATURE = RADIOLIB_LORAWAN_NONCES_ACTIVE + sizeof(uint8_t), // 2 bytes
273 RADIOLIB_LORAWAN_NONCES_BUF_SIZE = RADIOLIB_LORAWAN_NONCES_SIGNATURE + sizeof(uint16_t) // Nonces buffer size
274};
275
276enum LoRaWANSchemeSession_t {
277 RADIOLIB_LORAWAN_SESSION_START = 0x00,
278 RADIOLIB_LORAWAN_SESSION_NWK_SENC_KEY = RADIOLIB_LORAWAN_SESSION_START, // 16 bytes
279 RADIOLIB_LORAWAN_SESSION_APP_SKEY = RADIOLIB_LORAWAN_SESSION_NWK_SENC_KEY + RADIOLIB_AES128_KEY_SIZE, // 16 bytes
280 RADIOLIB_LORAWAN_SESSION_FNWK_SINT_KEY = RADIOLIB_LORAWAN_SESSION_APP_SKEY + RADIOLIB_AES128_KEY_SIZE, // 16 bytes
281 RADIOLIB_LORAWAN_SESSION_SNWK_SINT_KEY = RADIOLIB_LORAWAN_SESSION_FNWK_SINT_KEY + RADIOLIB_AES128_KEY_SIZE, // 16 bytes
282 RADIOLIB_LORAWAN_SESSION_DEV_ADDR = RADIOLIB_LORAWAN_SESSION_SNWK_SINT_KEY + RADIOLIB_AES128_KEY_SIZE, // 4 bytes
283 RADIOLIB_LORAWAN_SESSION_NONCES_SIGNATURE = RADIOLIB_LORAWAN_SESSION_DEV_ADDR + sizeof(uint32_t), // 2 bytes
284 RADIOLIB_LORAWAN_SESSION_FCNT_UP = RADIOLIB_LORAWAN_SESSION_NONCES_SIGNATURE + sizeof(uint16_t), // 4 bytes
285 RADIOLIB_LORAWAN_SESSION_N_FCNT_DOWN = RADIOLIB_LORAWAN_SESSION_FCNT_UP + sizeof(uint32_t), // 4 bytes
286 RADIOLIB_LORAWAN_SESSION_A_FCNT_DOWN = RADIOLIB_LORAWAN_SESSION_N_FCNT_DOWN + sizeof(uint32_t), // 4 bytes
287 RADIOLIB_LORAWAN_SESSION_ADR_FCNT = RADIOLIB_LORAWAN_SESSION_A_FCNT_DOWN + sizeof(uint32_t), // 4 bytes
288 RADIOLIB_LORAWAN_SESSION_CONF_FCNT_UP = RADIOLIB_LORAWAN_SESSION_ADR_FCNT + sizeof(uint32_t), // 4 bytes
289 RADIOLIB_LORAWAN_SESSION_CONF_FCNT_DOWN = RADIOLIB_LORAWAN_SESSION_CONF_FCNT_UP + sizeof(uint32_t), // 4 bytes
290 RADIOLIB_LORAWAN_SESSION_RJ_COUNT0 = RADIOLIB_LORAWAN_SESSION_CONF_FCNT_DOWN + sizeof(uint32_t), // 2 bytes
291 RADIOLIB_LORAWAN_SESSION_RJ_COUNT1 = RADIOLIB_LORAWAN_SESSION_RJ_COUNT0 + sizeof(uint16_t), // 2 bytes
292 RADIOLIB_LORAWAN_SESSION_HOMENET_ID = RADIOLIB_LORAWAN_SESSION_RJ_COUNT1 + sizeof(uint16_t), // 4 bytes
293 RADIOLIB_LORAWAN_SESSION_VERSION = RADIOLIB_LORAWAN_SESSION_HOMENET_ID + sizeof(uint32_t), // 1 byte
294 RADIOLIB_LORAWAN_SESSION_CLASS = RADIOLIB_LORAWAN_SESSION_VERSION + 1, // 1 byte
295 RADIOLIB_LORAWAN_SESSION_LINK_ADR = RADIOLIB_LORAWAN_SESSION_CLASS + sizeof(uint8_t), // 14 bytes
296 RADIOLIB_LORAWAN_SESSION_DUTY_CYCLE = RADIOLIB_LORAWAN_SESSION_LINK_ADR + 14, // 1 byte
297 RADIOLIB_LORAWAN_SESSION_RX_PARAM_SETUP = RADIOLIB_LORAWAN_SESSION_DUTY_CYCLE + 1, // 4 bytes
298 RADIOLIB_LORAWAN_SESSION_RX_TIMING_SETUP = RADIOLIB_LORAWAN_SESSION_RX_PARAM_SETUP + 4, // 1 byte
299 RADIOLIB_LORAWAN_SESSION_TX_PARAM_SETUP = RADIOLIB_LORAWAN_SESSION_RX_TIMING_SETUP + 1, // 1 byte
300 RADIOLIB_LORAWAN_SESSION_ADR_PARAM_SETUP = RADIOLIB_LORAWAN_SESSION_TX_PARAM_SETUP + 1, // 1 byte
301 RADIOLIB_LORAWAN_SESSION_REJOIN_PARAM_SETUP = RADIOLIB_LORAWAN_SESSION_ADR_PARAM_SETUP + 1, // 1 byte
302 RADIOLIB_LORAWAN_SESSION_UL_CHANNELS = RADIOLIB_LORAWAN_SESSION_REJOIN_PARAM_SETUP + 1, // 16*5 bytes
303 RADIOLIB_LORAWAN_SESSION_DL_CHANNELS = RADIOLIB_LORAWAN_SESSION_UL_CHANNELS + RADIOLIB_LORAWAN_NUM_AVAILABLE_CHANNELS*5, // 16*4 bytes
304 RADIOLIB_LORAWAN_SESSION_AVAILABLE_CHANNELS = RADIOLIB_LORAWAN_SESSION_DL_CHANNELS + RADIOLIB_LORAWAN_NUM_AVAILABLE_CHANNELS*4, // 2 bytes
305 RADIOLIB_LORAWAN_SESSION_MAC_QUEUE = RADIOLIB_LORAWAN_SESSION_AVAILABLE_CHANNELS + sizeof(uint16_t), // 15 bytes
306 RADIOLIB_LORAWAN_SESSION_MAC_QUEUE_LEN = RADIOLIB_LORAWAN_SESSION_MAC_QUEUE + RADIOLIB_LORAWAN_FHDR_FOPTS_MAX_LEN, // 1 byte
307 RADIOLIB_LORAWAN_SESSION_SIGNATURE = RADIOLIB_LORAWAN_SESSION_MAC_QUEUE_LEN + sizeof(uint8_t), // 2 bytes
308 RADIOLIB_LORAWAN_SESSION_BUF_SIZE = RADIOLIB_LORAWAN_SESSION_SIGNATURE + sizeof(uint16_t) // Session buffer size
309};
310
319
321 uint8_t idx;
322
324 uint32_t freq;
325
327 uint8_t drMin;
328
330 uint8_t drMax;
331
333 uint8_t dr;
334
337};
338
339// alias for unused channel
340#define RADIOLIB_LORAWAN_CHANNEL_NONE { .enabled = false, .idx = RADIOLIB_LORAWAN_CHANNEL_INDEX_NONE, .freq = 0, \
341 .drMin = 0, .drMax = 0, .dr = RADIOLIB_LORAWAN_DATA_RATE_UNUSED, .available = false }
342
350 uint8_t numChannels;
351
353 uint32_t freqStart;
354
356 uint32_t freqStep;
357
359 uint8_t drMin;
360
362 uint8_t drMax;
363
366};
367
368// alias for unused channel span
369#define RADIOLIB_LORAWAN_CHANNEL_SPAN_NONE { .numChannels = 0, .freqStart = 0, .freqStep = 0, .drMin = 0, .drMax = 0, .drJoinRequest = RADIOLIB_LORAWAN_DATA_RATE_UNUSED }
370
377 uint8_t bandNum;
378
380 uint8_t bandType;
381
383 uint32_t freqMin;
384
386 uint32_t freqMax;
387
389 uint8_t payloadLenMax[RADIOLIB_LORAWAN_CHANNEL_NUM_DATARATES];
390
392 int8_t powerMax;
393
396
399
402
405
408
411
413 uint8_t numTxSpans;
414
417
420
421 uint8_t rx1DrTable[RADIOLIB_LORAWAN_CHANNEL_NUM_DATARATES][8];
422
425
428
431
433 uint8_t dataRates[RADIOLIB_LORAWAN_CHANNEL_NUM_DATARATES];
434};
435
436// supported bands
437extern const LoRaWANBand_t EU868;
438extern const LoRaWANBand_t US915;
439extern const LoRaWANBand_t EU433;
440extern const LoRaWANBand_t AU915;
441extern const LoRaWANBand_t CN470;
442extern const LoRaWANBand_t AS923;
443extern const LoRaWANBand_t AS923_2;
444extern const LoRaWANBand_t AS923_3;
445extern const LoRaWANBand_t AS923_4;
446extern const LoRaWANBand_t KR920;
447extern const LoRaWANBand_t IN865;
448
453enum LoRaWANBandNum_t {
454 BandEU868,
455 BandUS915,
456 BandEU433,
457 BandAU915,
458 BandCN470,
459 BandAS923,
460 BandAS923_2,
461 BandAS923_3,
462 BandAS923_4,
463 BandKR920,
464 BandIN865,
465 BandLast
466};
467
468// provide easy access to the number of currently supported bands
469#define RADIOLIB_LORAWAN_NUM_SUPPORTED_BANDS (BandLast - BandEU868)
470
471// array of currently supported bands
472extern const LoRaWANBand_t* LoRaWANBands[];
473
480 bool newSession = false;
481
483 uint16_t devNonce = 0;
484
486 uint32_t joinNonce = 0;
487};
488
495 uint8_t dir;
496
499
503
506
508 uint8_t datarate;
509
511 float freq;
512
514 int16_t power;
515
517 uint32_t fCnt;
518
520 uint8_t fPort;
521
523 uint8_t nbTrans;
524
527};
528
534 public:
535
542 LoRaWANNode(PhysicalLayer* phy, const LoRaWANBand_t* band, uint8_t subBand = 0);
543
548 uint8_t* getBufferNonces();
549
555 int16_t setBufferNonces(const uint8_t* persistentBuffer);
556
560 void clearSession();
561
566 uint8_t* getBufferSession();
567
573 int16_t setBufferSession(const uint8_t* persistentBuffer);
574
583 int16_t beginOTAA(uint64_t joinEUI, uint64_t devEUI, const uint8_t* nwkKey, const uint8_t* appKey);
584
595 int16_t beginABP(uint32_t addr, const uint8_t* fNwkSIntKey, const uint8_t* sNwkSIntKey, const uint8_t* nwkSEncKey, const uint8_t* appSKey);
596
603 virtual int16_t activateOTAA(uint8_t initialDr = RADIOLIB_LORAWAN_DATA_RATE_UNUSED, LoRaWANJoinEvent_t *joinEvent = NULL);
604
611 virtual int16_t activateABP(uint8_t initialDr = RADIOLIB_LORAWAN_DATA_RATE_UNUSED);
612
614 bool isActivated();
615
617 int16_t setClass(uint8_t cls);
618
631 int16_t startMulticastSession(uint8_t cls, uint32_t mcAddr, const uint8_t* mcAppSKey, const uint8_t* mcNwkSKey, uint32_t mcFCntMin = 0, uint32_t mcFCntMax = 0xFFFFFFFF, uint32_t mcFreq = 0, uint8_t mcDr = RADIOLIB_LORAWAN_DATA_RATE_UNUSED);
632
635
636 #if defined(RADIOLIB_BUILD_ARDUINO)
649 virtual int16_t sendReceive(const String& strUp, uint8_t fPort, String& strDown, bool isConfirmed = false, LoRaWANEvent_t* eventUp = NULL, LoRaWANEvent_t* eventDown = NULL);
650 #endif
651
663 virtual int16_t sendReceive(const char* strUp, uint8_t fPort, bool isConfirmed = false, LoRaWANEvent_t* eventUp = NULL, LoRaWANEvent_t* eventDown = NULL);
664
678 virtual int16_t sendReceive(const char* strUp, uint8_t fPort, uint8_t* dataDown, size_t* lenDown, bool isConfirmed = false, LoRaWANEvent_t* eventUp = NULL, LoRaWANEvent_t* eventDown = NULL);
679
692 virtual int16_t sendReceive(const uint8_t* dataUp, size_t lenUp, uint8_t fPort = 1, bool isConfirmed = false, LoRaWANEvent_t* eventUp = NULL, LoRaWANEvent_t* eventDown = NULL);
693
708 virtual int16_t sendReceive(const uint8_t* dataUp, size_t lenUp, uint8_t fPort, uint8_t* dataDown, size_t* lenDown, bool isConfirmed = false, LoRaWANEvent_t* eventUp = NULL, LoRaWANEvent_t* eventDown = NULL);
709
718 int16_t getDownlinkClassC(uint8_t* dataDown, size_t* lenDown, LoRaWANEvent_t* eventDown = NULL);
719
727 int16_t sendMacCommandReq(uint8_t cid);
728
737 int16_t getMacLinkCheckAns(uint8_t* margin, uint8_t* gwCnt);
738
748 int16_t getMacDeviceTimeAns(uint32_t* gpsEpoch, uint8_t* fraction, bool returnUnix = true);
749
755 int16_t setDatarate(uint8_t drUp);
756
762 int16_t setTxPower(int8_t txPower);
763
770 int16_t setRx2Dr(uint8_t dr);
771
776 void setADR(bool enable = true);
777
784 void setDutyCycle(bool enable = true, RadioLibTime_t msPerHour = 0);
785
792 void setDwellTime(bool enable, RadioLibTime_t msPerUplink = 0);
793
801 void setCSMA(bool csmaEnabled, uint8_t maxChanges = 4, uint8_t backoffMax = 0, uint8_t difsSlots = 2);
802
808 void setDeviceStatus(uint8_t battLevel);
809
818
823 uint32_t getFCntUp();
824
829 uint32_t getNFCntDown();
830
835 uint32_t getAFCntDown();
836
842 void resetFCntDown();
843
848 uint32_t getDevAddr();
849
855
864
867
872 uint8_t getMaxPayloadLen();
873
875 typedef void (*SleepCb_t)(RadioLibTime_t ms);
876
884 void setSleepFunction(SleepCb_t cb);
885
890 bool TS009 = false;
891
905
906#if !RADIOLIB_GODMODE
907 protected:
908#endif
909 PhysicalLayer* phyLayer = NULL;
910 const LoRaWANBand_t* band = NULL;
911
912 // a buffer that holds all LW base parameters that should persist at all times!
913 uint8_t bufferNonces[RADIOLIB_LORAWAN_NONCES_BUF_SIZE] = { 0 };
914
915 // a buffer that holds all LW session parameters that preferably persist, but can be afforded to get lost
916 uint8_t bufferSession[RADIOLIB_LORAWAN_SESSION_BUF_SIZE] = { 0 };
917
918 uint8_t fOptsUp[RADIOLIB_LORAWAN_FHDR_FOPTS_MAX_LEN] = { 0 };
919 uint8_t fOptsDown[RADIOLIB_LORAWAN_FHDR_FOPTS_MAX_LEN] = { 0 };
920 uint8_t fOptsUpLen = 0;
921 uint8_t fOptsDownLen = 0;
922
923 uint16_t lwMode = RADIOLIB_LORAWAN_MODE_NONE;
924 uint8_t lwClass = RADIOLIB_LORAWAN_CLASS_A;
925 bool isActive = false;
926
927 uint64_t joinEUI = 0;
928 uint64_t devEUI = 0;
929 uint8_t nwkKey[RADIOLIB_AES128_KEY_SIZE] = { 0 };
930 uint8_t appKey[RADIOLIB_AES128_KEY_SIZE] = { 0 };
931
932 // the following is either provided by the network server (OTAA)
933 // or directly entered by the user (ABP)
934 uint32_t devAddr = 0;
935 uint8_t appSKey[RADIOLIB_AES128_KEY_SIZE] = { 0 };
936 uint8_t fNwkSIntKey[RADIOLIB_AES128_KEY_SIZE] = { 0 };
937 uint8_t sNwkSIntKey[RADIOLIB_AES128_KEY_SIZE] = { 0 };
938 uint8_t nwkSEncKey[RADIOLIB_AES128_KEY_SIZE] = { 0 };
939 uint8_t jSIntKey[RADIOLIB_AES128_KEY_SIZE] = { 0 };
940
941 uint16_t keyCheckSum = 0;
942
943 // device-specific parameters, persistent through sessions
944 uint16_t devNonce = 0;
945 uint32_t joinNonce = 0;
946
947 // session-specific parameters
948 uint32_t homeNetId = 0;
949 uint8_t adrLimitExp = RADIOLIB_LORAWAN_ADR_ACK_LIMIT_EXP;
950 uint8_t adrDelayExp = RADIOLIB_LORAWAN_ADR_ACK_DELAY_EXP;
951 uint8_t nbTrans = 1; // Number of allowed frame retransmissions
952 uint8_t txPowerSteps = 0;
953 uint8_t txPowerMax = 0;
954 uint32_t fCntUp = 0;
955 uint32_t aFCntDown = 0;
956 uint32_t nFCntDown = 0;
957 uint32_t confFCntUp = RADIOLIB_LORAWAN_FCNT_NONE;
958 uint32_t confFCntDown = RADIOLIB_LORAWAN_FCNT_NONE;
959 uint32_t adrFCnt = 0;
960
961 // ADR is enabled by default
962 bool adrEnabled = true;
963
964 // duty cycle is set upon initialization and activated in regions that impose this
965 bool dutyCycleEnabled = false;
966 uint32_t dutyCycle = 0;
967
968 // dwell time is set upon initialization and activated in regions that impose this
969 uint16_t dwellTimeUp = 0;
970 uint16_t dwellTimeDn = 0;
971
972 RadioLibTime_t tUplink = 0; // scheduled uplink transmission time (internal clock)
973 RadioLibTime_t tDownlink = 0; // time at end of downlink reception
974
975 // multicast parameters
976 uint8_t multicast = false;
977 uint32_t mcAddr = 0;
978 uint8_t mcAppSKey[RADIOLIB_AES128_KEY_SIZE] = { 0 };
979 uint8_t mcNwkSKey[RADIOLIB_AES128_KEY_SIZE] = { 0 };
980 uint32_t mcAFCnt = 0;
981 uint32_t mcAFCntMax = 0;
982
983 // enable/disable CSMA for LoRaWAN
984 bool csmaEnabled = false;
985
986 // maximum number of channel hops during CSMA
987 uint8_t maxChanges = RADIOLIB_LORAWAN_MAX_CHANGES_DEFAULT;
988
989 // number of backoff slots to be checked after DIFS phase.
990 // A random BO avoids collisions in the case where two or more nodes start the CSMA
991 // process at the same time.
992 uint8_t backoffMax = RADIOLIB_LORAWAN_BACKOFF_MAX_DEFAULT;
993
994 // number of CADs to estimate a clear channel
995 uint8_t difsSlots = RADIOLIB_LORAWAN_DIFS_DEFAULT;
996
997 // available channel frequencies from list passed during OTA activation
998 LoRaWANChannel_t channelPlan[2][RADIOLIB_LORAWAN_NUM_AVAILABLE_CHANNELS];
999
1000 // currently configured channels for Tx, Rx1, Rx2, RxBC
1001 LoRaWANChannel_t channels[4] = { RADIOLIB_LORAWAN_CHANNEL_NONE, RADIOLIB_LORAWAN_CHANNEL_NONE,
1002 RADIOLIB_LORAWAN_CHANNEL_NONE, RADIOLIB_LORAWAN_CHANNEL_NONE };
1003
1004 // delays between the uplink and Rx1/2 windows
1005 // the first field is meaningless, but is used for offsetting for Rx windows 1 and 2
1006 RadioLibTime_t rxDelays[3] = { 0, RADIOLIB_LORAWAN_RECEIVE_DELAY_1_MS, RADIOLIB_LORAWAN_RECEIVE_DELAY_2_MS };
1007
1008 // offset between Tx and Rx1 (such that Rx1 has equal or lower DR)
1009 uint8_t rx1DrOffset = 0;
1010
1011 // LoRaWAN revision (1.0 vs 1.1)
1012 uint8_t rev = 0;
1013
1014 // Time on Air of last uplink
1015 RadioLibTime_t lastToA = 0;
1016
1017 // timestamp to measure the Rx1/2 delay (from uplink end)
1018 RadioLibTime_t rxDelayStart = 0;
1019
1020 // duration of SPI transaction for phyLayer->launchMode()
1021 RadioLibTime_t launchDuration = 0;
1022
1023 // device status - battery level
1024 uint8_t battLevel = 0xFF;
1025
1026 // indicates whether an uplink has MAC commands as payload
1027 bool isMACPayload = false;
1028
1029 // save the selected sub-band in case this must be restored in ADR control
1030 uint8_t subBand = 0;
1031
1032 // allow port 226 for devices implementing TS011
1033 bool TS011 = false;
1034
1035 SleepCb_t sleepCb = nullptr;
1036
1037 // this will reset the device credentials, so the device starts completely new
1038 void clearNonces();
1039
1040 // start a fresh session using default parameters
1041 void createSession(uint16_t lwMode, uint8_t initialDr);
1042
1043 // setup Join-Request payload
1044 void composeJoinRequest(uint8_t* joinRequestMsg);
1045
1046 // extract Join-Accept payload and start a new session
1047 int16_t processJoinAccept(LoRaWANJoinEvent_t *joinEvent);
1048
1049 // a join-accept can piggy-back a set of channels or channel masks
1050 void processCFList(const uint8_t* cfList);
1051
1052 // check whether payload length and fport are allowed
1053 int16_t isValidUplink(uint8_t* len, uint8_t fPort);
1054
1055 // perform ADR backoff
1056 void adrBackoff();
1057
1058 // create an encrypted uplink buffer, composing metadata, user data and MAC data
1059 void composeUplink(const uint8_t* in, uint8_t lenIn, uint8_t* out, uint8_t fPort, bool isConfirmed);
1060
1061 // generate and set the MIC of an uplink buffer (depends on selected channels)
1062 void micUplink(uint8_t* inOut, uint8_t lenInOut);
1063
1064 // transmit uplink buffer on a specified channel
1065 int16_t transmitUplink(const LoRaWANChannel_t* chnl, uint8_t* in, uint8_t len, bool retrans = false);
1066
1067 // handle one of the Class A receive windows with a given channel and certain timestamps
1068 int16_t receiveClassA(uint8_t dir, const LoRaWANChannel_t* dlChannel, uint8_t window, const RadioLibTime_t dlDelay, RadioLibTime_t tReference);
1069
1070 // handle a Class C receive window with timeout (between Class A windows) or without (between uplinks)
1071 int16_t receiveClassC(RadioLibTime_t timeout = 0);
1072
1073 // open a series of Class A (and C) downlinks
1074 int16_t receiveDownlink();
1075
1076 // extract downlink payload and process MAC commands
1077 int16_t parseDownlink(uint8_t* data, size_t* len, uint8_t window, LoRaWANEvent_t* event = NULL);
1078
1079 // execute mac command, return the number of processed bytes for sequential processing
1080 bool execMacCommand(uint8_t cid, uint8_t* optIn, uint8_t lenIn);
1081 bool execMacCommand(uint8_t cid, uint8_t* optIn, uint8_t lenIn, uint8_t* optOut);
1082
1083 // possible override for additional MAC commands that are not in the base specification
1084 virtual bool derivedMacHandler(uint8_t cid, uint8_t* optIn, uint8_t lenIn, uint8_t* optOut);
1085
1086 // pre-process a (set of) LinkAdrReq commands into one super-channel-mask + Tx/Dr/NbTrans fields
1087 void preprocessMacLinkAdr(uint8_t* mPtr, uint8_t cLen, uint8_t* mAdrOpt);
1088
1089 // post-process a (set of) LinkAdrAns commands depending on LoRaWAN version
1090 void postprocessMacLinkAdr(uint8_t* ack, uint8_t cLen);
1091
1092 // get the properties of a MAC command given a certain command ID
1093 int16_t getMacCommand(uint8_t cid, LoRaWANMacCommand_t* cmd);
1094
1095 // possible override for additional MAC commands that are not in the base specification
1096 virtual int16_t derivedMacFinder(uint8_t cid, LoRaWANMacCommand_t* cmd);
1097
1098 // get the length of a certain MAC command in a specific direction (up/down)
1099 // if inclusive is true, add one for the CID byte
1100 // include payload in case the MAC command has a dynamic length
1101 virtual int16_t getMacLen(uint8_t cid, uint8_t* len, uint8_t dir, bool inclusive = false, uint8_t* payload = NULL);
1102
1103 // find out of a MAC command should persist destruction
1104 // in uplink direction, some commands must persist if no downlink is received
1105 // in downlink direction, the user-accessible MAC commands remain available for retrieval
1106 bool isPersistentMacCommand(uint8_t cid, uint8_t dir);
1107
1108 // push MAC command to queue, done by copy
1109 int16_t pushMacCommand(uint8_t cid, const uint8_t* cOcts, uint8_t* out, uint8_t* lenOut, uint8_t dir);
1110
1111 // retrieve the payload of a certain MAC command, if present in the buffer
1112 int16_t getMacPayload(uint8_t cid, const uint8_t* in, uint8_t lenIn, uint8_t* out, uint8_t dir);
1113
1114 // delete a specific MAC command from queue, indicated by the command ID
1115 int16_t deleteMacCommand(uint8_t cid, uint8_t* inOut, uint8_t* lenInOut, uint8_t dir);
1116
1117 // clear a MAC buffer, possible retaining persistent MAC commands
1118 void clearMacCommands(uint8_t* inOut, uint8_t* lenInOut, uint8_t dir);
1119
1120 // configure the common physical layer properties (frequency, sync word etc.)
1121 int16_t setPhyProperties(const LoRaWANChannel_t* chnl, uint8_t dir, int8_t pwr, size_t pre = 0);
1122
1123 // Performs CSMA as per LoRa Alliance Technical Recommendation 13 (TR-013).
1124 bool csmaChannelClear(uint8_t difs, uint8_t numBackoff);
1125
1126 // perform a single CAD operation for the under SF/CH combination. Returns either busy or otherwise.
1127 bool cadChannelClear();
1128
1129 // (dynamic bands:) get or (fixed bands:) create a complete 80-bit channel mask for current configuration
1130 void getChannelPlanMask(uint64_t* chMaskGrp0123, uint32_t* chMaskGrp45);
1131
1132 // setup uplink/downlink channel data rates and frequencies
1133 // for dynamic channels, there is a small set of predefined channels
1134 // in case of JoinRequest, add some optional extra frequencies
1135 void selectChannelPlanDyn();
1136
1137 // setup uplink/downlink channel data rates and frequencies
1138 // for fixed bands, we only allow one sub-band at a time to be selected
1139 void selectChannelPlanFix();
1140
1141 // get the number of available channels,
1142 // along with a 16-bit mask indicating which channels can be used next for uplink/downlink
1143 uint8_t getAvailableChannels(uint16_t* mask);
1144
1145 // (re)set/restore which channels can be used next for uplink/downlink
1146 void setAvailableChannels(uint16_t mask);
1147
1148 // select a set of random TX/RX channels for up- and downlink
1149 int16_t selectChannels();
1150
1151 // apply a 96-bit channel mask
1152 bool applyChannelMask(uint64_t chMaskGrp0123, uint32_t chMaskGrp45);
1153
1154#if RADIOLIB_DEBUG_PROTOCOL
1155 // print the available channels through debug
1156 void printChannels();
1157#endif
1158
1159 // method to generate message integrity code
1160 uint32_t generateMIC(const uint8_t* msg, size_t len, uint8_t* key);
1161
1162 // method to verify message integrity code
1163 // it assumes that the MIC is the last 4 bytes of the message
1164 bool verifyMIC(uint8_t* msg, size_t len, uint8_t* key);
1165
1166 // find the first usable data rate for the given band
1167 int16_t findDataRate(uint8_t dr, DataRate_t* dataRate);
1168
1169 // function to encrypt and decrypt payloads (regular uplink/downlink)
1170 void processAES(const uint8_t* in, size_t len, uint8_t* key, uint8_t* out, uint32_t addr, uint32_t fCnt, uint8_t dir, uint8_t ctrId, bool counter);
1171
1172 // function that allows sleeping via user-provided callback
1173 void sleepDelay(RadioLibTime_t ms);
1174
1175 // 16-bit checksum method that takes a uint8_t array of even length and calculates the checksum
1176 static uint16_t checkSum16(const uint8_t *key, uint16_t keyLen);
1177
1178 // check the integrity of a buffer using a 16-bit checksum located in the last two bytes of the buffer
1179 static int16_t checkBufferCommon(const uint8_t *buffer, uint16_t size);
1180
1181 // network-to-host conversion method - takes data from network packet and converts it to the host endians
1182 template<typename T>
1183 static T ntoh(const uint8_t* buff, size_t size = 0);
1184
1185 // host-to-network conversion method - takes data from host variable and and converts it to network packet endians
1186 template<typename T>
1187 static void hton(uint8_t* buff, T val, size_t size = 0);
1188};
1189
1190template<typename T>
1191T LoRaWANNode::ntoh(const uint8_t* buff, size_t size) {
1192 const uint8_t* buffPtr = buff;
1193 size_t targetSize = sizeof(T);
1194 if(size != 0) {
1195 targetSize = size;
1196 }
1197 T res = 0;
1198 for(size_t i = 0; i < targetSize; i++) {
1199 res |= (uint32_t)(*(buffPtr++)) << 8*i;
1200 }
1201 return(res);
1202}
1203
1204template<typename T>
1205void LoRaWANNode::hton(uint8_t* buff, T val, size_t size) {
1206 uint8_t* buffPtr = buff;
1207 size_t targetSize = sizeof(T);
1208 if(size != 0) {
1209 targetSize = size;
1210 }
1211 for(size_t i = 0; i < targetSize; i++) {
1212 *(buffPtr++) = val >> 8*i;
1213 }
1214}
1215
1216#endif
LoRaWAN-compatible node (class A device).
Definition LoRaWAN.h:533
void clearSession()
Clear an active session, so that the device will have to rejoin the network.
Definition LoRaWAN.cpp:283
virtual int16_t sendReceive(const char *strUp, uint8_t fPort, bool isConfirmed=false, LoRaWANEvent_t *eventUp=NULL, LoRaWANEvent_t *eventDown=NULL)
Send a message to the server and wait for a downlink during Rx1 and/or Rx2 window.
Definition LoRaWAN.cpp:44
void setSleepFunction(SleepCb_t cb)
Set custom delay/sleep function callback. If set, LoRaWAN node will call this function to wait for pe...
Definition LoRaWAN.cpp:3633
int16_t startMulticastSession(uint8_t cls, uint32_t mcAddr, const uint8_t *mcAppSKey, const uint8_t *mcNwkSKey, uint32_t mcFCntMin=0, uint32_t mcFCntMax=0xFFFFFFFF, uint32_t mcFreq=0, uint8_t mcDr=RADIOLIB_LORAWAN_DATA_RATE_UNUSED)
Start a Multicast session.
Definition LoRaWAN.cpp:1064
int16_t setDatarate(uint8_t drUp)
Set uplink datarate. This should not be used when ADR is enabled.
Definition LoRaWAN.cpp:2946
void scheduleTransmission(RadioLibTime_t tUplink)
Set the exact time a transmission should occur. Note: this is the internal clock time....
Definition LoRaWAN.cpp:3080
RadioLibTime_t scanGuard
Rx window padding in milliseconds according to the spec, the Rx window must be at least enough time t...
Definition LoRaWAN.h:904
void setCSMA(bool csmaEnabled, uint8_t maxChanges=4, uint8_t backoffMax=0, uint8_t difsSlots=2)
Configures CSMA for LoRaWAN as per TR013, LoRa Alliance.
Definition LoRaWAN.cpp:3062
void(* SleepCb_t)(RadioLibTime_t ms)
Callback to a user-provided sleep function.
Definition LoRaWAN.h:875
void setDutyCycle(bool enable=true, RadioLibTime_t msPerHour=0)
Toggle adherence to dutyCycle limits to on or off.
Definition LoRaWAN.cpp:3037
int16_t beginABP(uint32_t addr, const uint8_t *fNwkSIntKey, const uint8_t *sNwkSIntKey, const uint8_t *nwkSEncKey, const uint8_t *appSKey)
Set the device credentials and activation configuration.
Definition LoRaWAN.cpp:622
RadioLibTime_t timeUntilUplink()
Returns time in milliseconds until next uplink is available under dutyCycle limits.
Definition LoRaWAN.cpp:3585
int16_t getDownlinkClassC(uint8_t *dataDown, size_t *lenDown, LoRaWANEvent_t *eventDown=NULL)
Check if there is an RxC downlink and parse it if available.
Definition LoRaWAN.cpp:2115
void stopMulticastSession()
Stop an ongoing multicast session.
Definition LoRaWAN.cpp:1116
void setDeviceStatus(uint8_t battLevel)
Set device status.
Definition LoRaWAN.cpp:3076
RadioLibTime_t dutyCycleInterval(RadioLibTime_t msPerHour, RadioLibTime_t airtime)
Calculate the minimum interval to adhere to a certain dutyCycle. This interval is based on the ToA of...
Definition LoRaWAN.cpp:3575
void setDwellTime(bool enable, RadioLibTime_t msPerUplink=0)
Set or disable uplink dwell time limitation; enabled by default if mandatory.
Definition LoRaWAN.cpp:3049
uint32_t getAFCntDown()
Returns the last application downlink's frame counter; also 0 if no application downlink occured yet.
Definition LoRaWAN.cpp:3096
RadioLibTime_t getLastToA()
Get the Time-on-air of the last uplink message (in milliseconds).
Definition LoRaWAN.cpp:3109
virtual int16_t activateABP(uint8_t initialDr=RADIOLIB_LORAWAN_DATA_RATE_UNUSED)
Join network by restoring ABP session or performing over-the-air activation. In this procedure,...
Definition LoRaWAN.cpp:941
bool TS009
TS009 Protocol Specification Verification switch (allows FPort 224 and cuts off uplink payload instea...
Definition LoRaWAN.h:890
uint8_t * getBufferNonces()
Returns the pointer to the internal buffer that holds the LW base parameters.
Definition LoRaWAN.cpp:234
uint8_t * getBufferSession()
Returns the pointer to the internal buffer that holds the LW session parameters.
Definition LoRaWAN.cpp:436
bool isActivated()
Whether there is an ongoing session active.
Definition LoRaWAN.cpp:1031
int16_t setTxPower(int8_t txPower)
Configure TX power of the radio module.
Definition LoRaWAN.cpp:2979
int16_t getMacDeviceTimeAns(uint32_t *gpsEpoch, uint8_t *fraction, bool returnUnix=true)
Returns the network time after requesting a DeviceTime MAC command. Returns 'true' if a network respo...
Definition LoRaWAN.cpp:2792
uint32_t getNFCntDown()
Returns the last network downlink's frame counter; also 0 if no network downlink occured yet.
Definition LoRaWAN.cpp:3092
int16_t setClass(uint8_t cls)
Configure class (RADIOLIB_LORAWAN_CLASS_A or RADIOLIB_LORAWAN_CLASS_C)
Definition LoRaWAN.cpp:1035
int16_t beginOTAA(uint64_t joinEUI, uint64_t devEUI, const uint8_t *nwkKey, const uint8_t *appKey)
Set the device credentials and activation configuration.
Definition LoRaWAN.cpp:594
uint8_t getMaxPayloadLen()
Returns the maximum allowed uplink payload size given the current MAC state. Most importantly,...
Definition LoRaWAN.cpp:3594
virtual int16_t activateOTAA(uint8_t initialDr=RADIOLIB_LORAWAN_DATA_RATE_UNUSED, LoRaWANJoinEvent_t *joinEvent=NULL)
Join network by restoring OTAA session or performing over-the-air activation. By this procedure,...
Definition LoRaWAN.cpp:880
uint32_t getFCntUp()
Returns the last uplink's frame counter; also 0 if no uplink occured yet.
Definition LoRaWAN.cpp:3085
int16_t setBufferNonces(const uint8_t *persistentBuffer)
Fill the internal buffer that holds the LW base parameters with a supplied buffer.
Definition LoRaWAN.cpp:248
int16_t setRx2Dr(uint8_t dr)
Configure the Rx2 datarate for ABP mode. This should not be needed for LoRaWAN 1.1 as it is configure...
Definition LoRaWAN.cpp:3005
int16_t sendMacCommandReq(uint8_t cid)
Add a MAC command to the uplink queue. Only LinkCheck and DeviceTime are available to the user....
Definition LoRaWAN.cpp:2757
int16_t getMacLinkCheckAns(uint8_t *margin, uint8_t *gwCnt)
Returns the quality of connectivity after requesting a LinkCheck MAC command. Returns 'true' if a net...
Definition LoRaWAN.cpp:2781
void setADR(bool enable=true)
Toggle ADR to on or off.
Definition LoRaWAN.cpp:3033
int16_t setBufferSession(const uint8_t *persistentBuffer)
Fill the internal buffer that holds the LW session parameters with a supplied buffer.
Definition LoRaWAN.cpp:469
uint32_t getDevAddr()
Returns the DevAddr of the device, regardless of OTAA or ABP mode.
Definition LoRaWAN.cpp:3105
void resetFCntDown()
Reset the downlink frame counters (application and network) This is unsafe and can possibly allow rep...
Definition LoRaWAN.cpp:3100
Provides common interface for protocols that run on LoRa/FSK modules, such as RTTY or LoRaWAN....
Definition PhysicalLayer.h:216
unsigned long RadioLibTime_t
Type used for durations in RadioLib.
Definition TypeDef.h:642
Structure to save information about LoRaWAN band.
Definition LoRaWAN.h:375
int8_t powerMax
Maximum allowed output power in this band in dBm.
Definition LoRaWAN.h:392
bool txParamSupported
Whether this band implements the MAC command TxParamSetupReq.
Definition LoRaWAN.h:407
LoRaWANChannel_t txAck[2]
Relay channels for ACK downlink.
Definition LoRaWAN.h:430
RadioLibTime_t dutyCycle
Number of milliseconds per hour of allowed Time-on-Air.
Definition LoRaWAN.h:398
uint8_t dataRates[RADIOLIB_LORAWAN_CHANNEL_NUM_DATARATES]
The corresponding datarates, bandwidths and coding rates for DR index.
Definition LoRaWAN.h:433
RadioLibTime_t dwellTimeUp
Maximum dwell time per uplink message in milliseconds.
Definition LoRaWAN.h:401
LoRaWANChannel_t txWoR[2]
Relay channels for WoR uplink.
Definition LoRaWAN.h:427
uint32_t freqMin
Minimum allowed frequency (coded in 100 Hz steps)
Definition LoRaWAN.h:383
uint8_t payloadLenMax[RADIOLIB_LORAWAN_CHANNEL_NUM_DATARATES]
Array of allowed maximum application payload lengths for each data rate (N-value)
Definition LoRaWAN.h:389
LoRaWANChannel_t txFreqs[3]
A set of default uplink (TX) channels for dynamic bands.
Definition LoRaWAN.h:410
int8_t powerNumSteps
Number of power steps in this band.
Definition LoRaWAN.h:395
LoRaWANChannelSpan_t txSpans[2]
Default uplink (TX) channel spans for fixed bands, including Join-Request parameters.
Definition LoRaWAN.h:416
uint8_t bandNum
Identier for this band.
Definition LoRaWAN.h:377
uint32_t freqMax
Maximum allowed frequency (coded in 100 Hz steps)
Definition LoRaWAN.h:386
uint8_t bandType
Whether the channels are fixed per specification, or dynamically allocated through the network (plus ...
Definition LoRaWAN.h:380
LoRaWANChannel_t rx2
Backup channel for downlink (RX2) window.
Definition LoRaWAN.h:424
uint8_t numTxSpans
The number of TX channel spans for fixed bands.
Definition LoRaWAN.h:413
RadioLibTime_t dwellTimeDn
Maximum dwell time per downlink message in milliseconds.
Definition LoRaWAN.h:404
LoRaWANChannelSpan_t rx1Span
Default downlink (RX1) channel span for fixed bands.
Definition LoRaWAN.h:419
IDs of all currently supported bands.
Structure to save information about LoRaWAN channels. To save space, adjacent channels are saved in "...
Definition LoRaWAN.h:316
bool available
Whether this channel is available for channel selection.
Definition LoRaWAN.h:336
uint8_t dr
Datarate currently in use on this channel.
Definition LoRaWAN.h:333
uint32_t freq
The channel frequency (coded in 100 Hz steps)
Definition LoRaWAN.h:324
uint8_t idx
The channel number, as specified by defaults or the network.
Definition LoRaWAN.h:321
uint8_t drMin
Minimum allowed datarate for this channel.
Definition LoRaWAN.h:327
bool enabled
Whether this channel is enabled (can be used) or is disabled.
Definition LoRaWAN.h:318
uint8_t drMax
Maximum allowed datarate for this channel (inclusive)
Definition LoRaWAN.h:330
Structure to save information about LoRaWAN channels. To save space, adjacent channels are saved in "...
Definition LoRaWAN.h:348
uint8_t drJoinRequest
Allowed data rates for a join request message.
Definition LoRaWAN.h:365
uint32_t freqStart
Center frequency of the first channel in span (coded in 100 Hz steps)
Definition LoRaWAN.h:353
uint8_t numChannels
Total number of channels in the span.
Definition LoRaWAN.h:350
uint8_t drMax
Maximum allowed datarate for all channels in this span (inclusive)
Definition LoRaWAN.h:362
uint32_t freqStep
Frequency step between adjacent channels (coded in 100 Hz steps)
Definition LoRaWAN.h:356
uint8_t drMin
Minimum allowed datarate for all channels in this span.
Definition LoRaWAN.h:359
Structure to save extra information about uplink/downlink event.
Definition LoRaWAN.h:493
float freq
Frequency in MHz.
Definition LoRaWAN.h:511
bool confirmed
Whether the event is confirmed or not (e.g., confirmed uplink sent by user application)
Definition LoRaWAN.h:498
uint8_t fPort
Port number.
Definition LoRaWAN.h:520
int16_t power
Transmit power in dBm for uplink, or RSSI for downlink.
Definition LoRaWAN.h:514
bool confirming
Whether the event is confirming a previous request (e.g., server downlink reply to confirmed uplink s...
Definition LoRaWAN.h:502
uint8_t datarate
Datarate.
Definition LoRaWAN.h:508
uint8_t dir
Event direction, one of RADIOLIB_LORAWAN_CHANNEL_DIR_*.
Definition LoRaWAN.h:495
uint8_t nbTrans
Number of times this uplink was transmitted (ADR)
Definition LoRaWAN.h:523
uint32_t fCnt
The appropriate frame counter - for different events, different frame counters will be reported!
Definition LoRaWAN.h:517
bool multicast
Multicast or unicast.
Definition LoRaWAN.h:526
bool frmPending
Whether further downlink messages are pending on the server side.
Definition LoRaWAN.h:505
Structure to save extra information about activation event.
Definition LoRaWAN.h:478
bool newSession
Whether a new session was started.
Definition LoRaWAN.h:480
uint32_t joinNonce
The received Join-Request JoinNonce value.
Definition LoRaWAN.h:486
uint16_t devNonce
The transmitted Join-Request DevNonce value.
Definition LoRaWAN.h:483
MAC command specification structure.
Definition LoRaWAN.h:222
const uint8_t lenDn
Uplink message length.
Definition LoRaWAN.h:227
const bool user
Whether this MAC command can be issued by the user or not.
Definition LoRaWAN.h:236
const uint8_t cid
Command ID.
Definition LoRaWAN.h:224
const uint8_t lenUp
Downlink message length.
Definition LoRaWAN.h:230
const bool persist
Some commands must be resent until Class A downlink received.
Definition LoRaWAN.h:233
Common data rate structure.
Definition PhysicalLayer.h:74