Line data Source code
1 1 : /*
2 : * Copyright (c) 2020 Manivannan Sadhasivam <mani@kernel.org>
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_LORAWAN_LORAWAN_H_
8 : #define ZEPHYR_INCLUDE_LORAWAN_LORAWAN_H_
9 :
10 : /**
11 : * @file
12 : * @brief Public LoRaWAN APIs
13 : * @defgroup lorawan_api LoRaWAN APIs
14 : * @since 2.5
15 : * @version 0.1.0
16 : * @ingroup connectivity
17 : * @{
18 : */
19 :
20 : #include <zephyr/device.h>
21 : #include <zephyr/sys/slist.h>
22 :
23 : #ifdef __cplusplus
24 : extern "C" {
25 : #endif
26 :
27 : /**
28 : * @brief LoRaWAN class types.
29 : */
30 1 : enum lorawan_class {
31 : LORAWAN_CLASS_A = 0x00, /**< Class A device */
32 : LORAWAN_CLASS_B = 0x01, /**< Class B device */
33 : LORAWAN_CLASS_C = 0x02, /**< Class C device */
34 : };
35 :
36 : /**
37 : * @brief LoRaWAN activation types.
38 : */
39 1 : enum lorawan_act_type {
40 : LORAWAN_ACT_OTAA = 0, /**< Over-the-Air Activation (OTAA) */
41 : LORAWAN_ACT_ABP, /**< Activation by Personalization (ABP) */
42 : };
43 :
44 : /**
45 : * @brief LoRaWAN channels mask sizes.
46 : */
47 1 : enum lorawan_channels_mask_size {
48 : LORAWAN_CHANNELS_MASK_SIZE_AS923 = 1, /**< Region AS923 mask size */
49 : LORAWAN_CHANNELS_MASK_SIZE_AU915 = 6, /**< Region AU915 mask size */
50 : LORAWAN_CHANNELS_MASK_SIZE_CN470 = 6, /**< Region CN470 mask size */
51 : LORAWAN_CHANNELS_MASK_SIZE_CN779 = 1, /**< Region CN779 mask size */
52 : LORAWAN_CHANNELS_MASK_SIZE_EU433 = 1, /**< Region EU433 mask size */
53 : LORAWAN_CHANNELS_MASK_SIZE_EU868 = 1, /**< Region EU868 mask size */
54 : LORAWAN_CHANNELS_MASK_SIZE_KR920 = 1, /**< Region KR920 mask size */
55 : LORAWAN_CHANNELS_MASK_SIZE_IN865 = 1, /**< Region IN865 mask size */
56 : LORAWAN_CHANNELS_MASK_SIZE_US915 = 6, /**< Region US915 mask size */
57 : LORAWAN_CHANNELS_MASK_SIZE_RU864 = 1, /**< Region RU864 mask size */
58 : };
59 :
60 : /**
61 : * @brief LoRaWAN datarate types.
62 : */
63 1 : enum lorawan_datarate {
64 : LORAWAN_DR_0 = 0, /**< DR0 data rate */
65 : LORAWAN_DR_1, /**< DR1 data rate */
66 : LORAWAN_DR_2, /**< DR2 data rate */
67 : LORAWAN_DR_3, /**< DR3 data rate */
68 : LORAWAN_DR_4, /**< DR4 data rate */
69 : LORAWAN_DR_5, /**< DR5 data rate */
70 : LORAWAN_DR_6, /**< DR6 data rate */
71 : LORAWAN_DR_7, /**< DR7 data rate */
72 : LORAWAN_DR_8, /**< DR8 data rate */
73 : LORAWAN_DR_9, /**< DR9 data rate */
74 : LORAWAN_DR_10, /**< DR10 data rate */
75 : LORAWAN_DR_11, /**< DR11 data rate */
76 : LORAWAN_DR_12, /**< DR12 data rate */
77 : LORAWAN_DR_13, /**< DR13 data rate */
78 : LORAWAN_DR_14, /**< DR14 data rate */
79 : LORAWAN_DR_15, /**< DR15 data rate */
80 : };
81 :
82 : /**
83 : * @brief LoRaWAN region types.
84 : */
85 1 : enum lorawan_region {
86 : LORAWAN_REGION_AS923, /**< Asia 923 MHz frequency band */
87 : LORAWAN_REGION_AU915, /**< Australia 915 MHz frequency band */
88 : LORAWAN_REGION_CN470, /**< China 470 MHz frequency band */
89 : LORAWAN_REGION_CN779, /**< China 779 MHz frequency band */
90 : LORAWAN_REGION_EU433, /**< Europe 433 MHz frequency band */
91 : LORAWAN_REGION_EU868, /**< Europe 868 MHz frequency band */
92 : LORAWAN_REGION_KR920, /**< South Korea 920 MHz frequency band */
93 : LORAWAN_REGION_IN865, /**< India 865 MHz frequency band */
94 : LORAWAN_REGION_US915, /**< United States 915 MHz frequency band */
95 : LORAWAN_REGION_RU864, /**< Russia 864 MHz frequency band */
96 : };
97 :
98 : /**
99 : * @brief LoRaWAN message types.
100 : */
101 1 : enum lorawan_message_type {
102 : LORAWAN_MSG_UNCONFIRMED = 0, /**< Unconfirmed message */
103 : LORAWAN_MSG_CONFIRMED, /**< Confirmed message */
104 : };
105 :
106 : /**
107 : * @brief LoRaWAN downlink flags.
108 : */
109 0 : enum lorawan_dl_flags {
110 : LORAWAN_DATA_PENDING = BIT(0),
111 : LORAWAN_TIME_UPDATED = BIT(1),
112 : };
113 :
114 : /**
115 : * @brief LoRaWAN join parameters for over-the-Air activation (OTAA)
116 : *
117 : * Note that all of the fields use LoRaWAN 1.1 terminology.
118 : *
119 : * All parameters are optional if a secure element is present in which
120 : * case the values stored in the secure element will be used instead.
121 : */
122 1 : struct lorawan_join_otaa {
123 : /** Join EUI */
124 1 : uint8_t *join_eui;
125 : /** Network Key */
126 1 : uint8_t *nwk_key;
127 : /** Application Key */
128 1 : uint8_t *app_key;
129 : /**
130 : * Device Nonce
131 : *
132 : * Starting with LoRaWAN 1.0.4 the DevNonce must be monotonically
133 : * increasing for each OTAA join with the same EUI. The DevNonce
134 : * should be stored in non-volatile memory by the application.
135 : */
136 1 : uint16_t dev_nonce;
137 : };
138 :
139 : /**
140 : * @brief LoRaWAN join parameters for activation by personalization (ABP)
141 : */
142 1 : struct lorawan_join_abp {
143 : /** Device address on the network */
144 1 : uint32_t dev_addr;
145 : /** Application session key */
146 1 : uint8_t *app_skey;
147 : /** Network session key */
148 1 : uint8_t *nwk_skey;
149 : /** Application EUI */
150 1 : uint8_t *app_eui;
151 : };
152 :
153 : /**
154 : * @brief LoRaWAN join parameters
155 : */
156 1 : struct lorawan_join_config {
157 : /** Join parameters */
158 : union {
159 1 : struct lorawan_join_otaa otaa; /**< OTAA join parameters */
160 1 : struct lorawan_join_abp abp; /**< ABP join parameters */
161 1 : };
162 :
163 : /** Device EUI. Optional if a secure element is present. */
164 1 : uint8_t *dev_eui;
165 :
166 : /** Activation mode */
167 1 : enum lorawan_act_type mode;
168 : };
169 :
170 : /** Flag to indicate receiving on any port */
171 1 : #define LW_RECV_PORT_ANY UINT16_MAX
172 :
173 : /**
174 : * @brief LoRaWAN downlink callback parameters
175 : */
176 1 : struct lorawan_downlink_cb {
177 : /**
178 : * @brief Port to handle messages for.
179 : *
180 : * - Port 0: TX packet acknowledgements
181 : * - Ports 1-255: Standard downlink port
182 : * - LW_RECV_PORT_ANY: All downlinks
183 : */
184 1 : uint16_t port;
185 : /**
186 : * @brief Callback function to run on downlink data
187 : *
188 : * @note Callbacks are run on the system workqueue,
189 : * and should therefore be as short as possible.
190 : *
191 : * @param port Port message was sent on
192 : * @param flags Downlink data flags (see @ref lorawan_dl_flags)
193 : * @param rssi Received signal strength in dBm
194 : * @param snr Signal to Noise ratio in dBm
195 : * @param len Length of data received, will be 0 for ACKs
196 : * @param data Data received, will be NULL for ACKs
197 : */
198 1 : void (*cb)(uint8_t port, uint8_t flags, int16_t rssi, int8_t snr, uint8_t len,
199 : const uint8_t *data);
200 : /** Node for callback list */
201 1 : sys_snode_t node;
202 : };
203 :
204 : /**
205 : * @brief Defines the battery level callback handler function signature.
206 : *
207 : * @retval 0 if the node is connected to an external power source
208 : * @retval 1..254 battery level, where 1 is the minimum and 254 is the maximum value
209 : * @retval 255 if the node was not able to measure the battery level
210 : */
211 1 : typedef uint8_t (*lorawan_battery_level_cb_t)(void);
212 :
213 : /**
214 : * @brief Defines the datarate changed callback handler function signature.
215 : *
216 : * @param dr Updated datarate.
217 : */
218 1 : typedef void (*lorawan_dr_changed_cb_t)(enum lorawan_datarate dr);
219 :
220 : /**
221 : * @brief Register a battery level callback function.
222 : *
223 : * Provide the LoRaWAN stack with a function to be called whenever a battery
224 : * level needs to be read.
225 : *
226 : * Should no callback be provided the lorawan backend will report 255.
227 : *
228 : * @param cb Pointer to the battery level function
229 : */
230 1 : void lorawan_register_battery_level_callback(lorawan_battery_level_cb_t cb);
231 :
232 : /**
233 : * @brief Register a callback to be run on downlink packets
234 : *
235 : * @param cb Pointer to structure containing callback parameters
236 : */
237 1 : void lorawan_register_downlink_callback(struct lorawan_downlink_cb *cb);
238 :
239 : /**
240 : * @brief Register a callback to be called when the datarate changes
241 : *
242 : * The callback is called once upon successfully joining a network and again
243 : * each time the datarate changes due to ADR.
244 : *
245 : * @param cb Pointer to datarate update callback
246 : */
247 1 : void lorawan_register_dr_changed_callback(lorawan_dr_changed_cb_t cb);
248 :
249 : /**
250 : * @brief Join the LoRaWAN network
251 : *
252 : * Join the LoRaWAN network using OTAA or AWB.
253 : *
254 : * @param config Configuration to be used
255 : *
256 : * @return 0 if successful, negative errno code if failure
257 : */
258 1 : int lorawan_join(const struct lorawan_join_config *config);
259 :
260 : /**
261 : * @brief Start the LoRaWAN stack
262 : *
263 : * This function need to be called before joining the network.
264 : *
265 : * @return 0 if successful, negative errno code if failure
266 : */
267 1 : int lorawan_start(void);
268 :
269 : /**
270 : * @brief Send data to the LoRaWAN network
271 : *
272 : * Send data to the connected LoRaWAN network.
273 : *
274 : * @param port Port to be used for sending data. Must be set if the
275 : * payload is not empty.
276 : * @param data Data buffer to be sent
277 : * @param len Length of the buffer to be sent. Maximum length of this
278 : * buffer is 255 bytes but the actual payload size varies with
279 : * region and datarate.
280 : * @param type Specifies if the message shall be confirmed or unconfirmed.
281 : * Must be one of @ref lorawan_message_type.
282 : *
283 : * @return 0 if successful, negative errno code if failure
284 : */
285 1 : int lorawan_send(uint8_t port, uint8_t *data, uint8_t len, enum lorawan_message_type type);
286 :
287 : /**
288 : * @brief Set the current device class
289 : *
290 : * Change the current device class. This function may be called before
291 : * or after a network connection has been established.
292 : *
293 : * @param dev_class New device class
294 : *
295 : * @return 0 if successful, negative errno code if failure
296 : */
297 1 : int lorawan_set_class(enum lorawan_class dev_class);
298 :
299 : /**
300 : * @brief Set the number of tries used for transmissions
301 : *
302 : * @param tries Number of tries to be used
303 : *
304 : * @return 0 if successful, negative errno code if failure
305 : */
306 1 : int lorawan_set_conf_msg_tries(uint8_t tries);
307 :
308 : /**
309 : * @brief Enable Adaptive Data Rate (ADR)
310 : *
311 : * Control whether adaptive data rate (ADR) is enabled. When ADR is enabled,
312 : * the data rate is treated as a default data rate that will be used if the
313 : * ADR algorithm has not established a data rate. ADR should normally only
314 : * be enabled for devices with stable RF conditions (i.e., devices in a mostly
315 : * static location).
316 : *
317 : * @param enable Enable or Disable adaptive data rate.
318 : */
319 1 : void lorawan_enable_adr(bool enable);
320 :
321 : /**
322 : * @brief Set the channels mask.
323 : *
324 : * Change the default channels mask. When mask is not changed, all the channels
325 : * can be used for data transmission. Some Network Servers don't use all the channels,
326 : * in this case, the channels mask must be provided.
327 : *
328 : * @param channels_mask Buffer with channels mask to be used.
329 : * @param channels_mask_size Size of channels mask buffer.
330 : *
331 : * @retval 0 successful
332 : * @retval -EINVAL channels mask or channels mask size is wrong
333 : */
334 1 : int lorawan_set_channels_mask(uint16_t *channels_mask, size_t channels_mask_size);
335 :
336 : /**
337 : * @brief Set the default data rate
338 : *
339 : * Change the default data rate.
340 : *
341 : * @param dr Data rate used for transmissions
342 : *
343 : * @return 0 if successful, negative errno code if failure
344 : */
345 1 : int lorawan_set_datarate(enum lorawan_datarate dr);
346 :
347 : /**
348 : * @brief Get the minimum possible datarate
349 : *
350 : * The minimum possible datarate may change in response to a TxParamSetupReq
351 : * command from the network server.
352 : *
353 : * @return Minimum possible data rate
354 : */
355 1 : enum lorawan_datarate lorawan_get_min_datarate(void);
356 :
357 : /**
358 : * @brief Get the current payload sizes
359 : *
360 : * Query the current payload sizes. The maximum payload size varies with
361 : * datarate, while the current payload size can be less due to MAC layer
362 : * commands which are inserted into uplink packets.
363 : *
364 : * @param max_next_payload_size Maximum payload size for the next transmission
365 : * @param max_payload_size Maximum payload size for this datarate
366 : */
367 1 : void lorawan_get_payload_sizes(uint8_t *max_next_payload_size,
368 : uint8_t *max_payload_size);
369 :
370 : /**
371 : * @brief Set the region and frequency to be used
372 : *
373 : * Control the LoRa region and frequency settings. This should be called before
374 : * @a lorawan_start(). If you only have support for a single region selected via
375 : * Kconfig, this function does not need to be called at all.
376 : *
377 : * @param region The region to be selected
378 : * @return 0 if successful, negative errno otherwise
379 : */
380 1 : int lorawan_set_region(enum lorawan_region region);
381 :
382 : /**
383 : * @brief Request for time according to DeviceTimeReq MAC cmd
384 : *
385 : * Append MAC DevTimeReq command. It will be processed on next send
386 : * message or force sending empty message to request time immediately.
387 : *
388 : * @param force_request Immediately send an empty message to execute the request
389 : * @return 0 if successful, negative errno otherwise
390 : */
391 1 : int lorawan_request_device_time(bool force_request);
392 :
393 : /**
394 : * @brief Retrieve the current time from LoRaWAN stack updated by
395 : * DeviceTimeAns on MAC layer.
396 : *
397 : * This function uses the GPS epoch format, as used in all LoRaWAN services.
398 : *
399 : * The GPS epoch started on 1980-01-06T00:00:00Z, but has since diverged
400 : * from UTC, as it does not consider corrections like leap seconds.
401 : *
402 : * @param gps_time Synchronized time in GPS epoch format truncated to 32-bit.
403 : *
404 : * @return 0 if successful, -EAGAIN if the clock is not yet synchronized.
405 : */
406 1 : int lorawan_device_time_get(uint32_t *gps_time);
407 :
408 : #ifdef CONFIG_LORAWAN_APP_CLOCK_SYNC
409 :
410 : /**
411 : * @brief Run Application Layer Clock Synchronization service
412 : *
413 : * This service sends out its current time in a regular interval (configurable
414 : * via Kconfig) and receives a correction offset from the application server if
415 : * the clock deviation is considered too large.
416 : *
417 : * Clock synchronization is required for firmware upgrades over multicast
418 : * sessions, but can also be used independent of a FUOTA process.
419 : *
420 : * @return 0 if successful, negative errno otherwise.
421 : */
422 : int lorawan_clock_sync_run(void);
423 :
424 : /**
425 : * @brief Retrieve the current synchronized time
426 : *
427 : * This function uses the GPS epoch format, as used in all LoRaWAN services.
428 : *
429 : * The GPS epoch started on 1980-01-06T00:00:00Z, but has since diverged
430 : * from UTC, as it does not consider corrections like leap seconds.
431 : *
432 : * @param gps_time Synchronized time in GPS epoch format truncated to 32-bit.
433 : *
434 : * @return 0 if successful, -EAGAIN if the clock is not yet synchronized.
435 : */
436 : int lorawan_clock_sync_get(uint32_t *gps_time);
437 :
438 : #endif /* CONFIG_LORAWAN_APP_CLOCK_SYNC */
439 :
440 : #ifdef CONFIG_LORAWAN_FRAG_TRANSPORT
441 :
442 : /**
443 : * @brief Run Fragmented Data Block Transport service
444 : *
445 : * This service receives fragmented data (usually firmware images) and
446 : * stores them in the image-1 flash partition.
447 : *
448 : * After all fragments have been received, the provided callback is invoked.
449 : *
450 : * @param transport_finished_cb Callback for notification of finished data transfer.
451 : *
452 : * @return 0 if successful, negative errno otherwise.
453 : */
454 : int lorawan_frag_transport_run(void (*transport_finished_cb)(void));
455 :
456 : #endif /* CONFIG_LORAWAN_FRAG_TRANSPORT */
457 :
458 : #ifdef __cplusplus
459 : }
460 : #endif
461 :
462 : /**
463 : * @}
464 : */
465 :
466 : #endif /* ZEPHYR_INCLUDE_LORAWAN_LORAWAN_H_ */
|
