The NSL01 library contains all functions for controlling the NSL01 LoRaWAN shield from mCloud System GmbH. The NSL01 is a professional plug & play LoRaWAN shield for a wide range of STM32 Nucleo-64 boards with Arduino Uno Rev 3 connectivity. For more information about the NSL01 LoRaWAN shield: http://www.mcloud-systems.com/nsl01-lorawan-nucleo-arduino-shield
NSL01.h
00001 /* 00002 ******************************************************************************** 00003 * @file NSL01.h 00004 * 00005 * @brief Class for controlling the NSL01 LoRaWAN shield from 00006 * mCloud Systems GmbH. 00007 * 00008 * @brief For more information about the NSL01 LoRaWAN shield: 00009 * http://www.mcloud-systems.com/nsl01-lorawan-nucleo-arduino-shield 00010 * 00011 * @author mCloud Systems Team 00012 * 00013 * @version V1.0 00014 * @date 20-June-2018 00015 ******************************************************************************** 00016 * @attention 00017 * 00018 * Copyright (c) 2018 mCloud Systems GmbH, MIT License 00019 * 00020 * Permission is hereby granted, free of charge, to any person obtaining a copy 00021 * of this software and associated documentation files (the "Software"), to deal 00022 * in the Software without restriction, including without limitation the rights 00023 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 00024 * copies of the Software, and to permit persons to whom the Software is 00025 * furnished to do so, subject to the following conditions: 00026 * 00027 * The above copyright notice and this permission notice shall be included in 00028 * all copies or substantial portions of the Software. 00029 * 00030 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 00031 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00032 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 00033 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 00034 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 00035 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 00036 * SOFTWARE. 00037 */ 00038 00039 #ifndef NSL01_h 00040 #define NSL01_h 00041 00042 //#define DEBUG 00043 00044 //------------------------------------------------------------------------------ 00045 // 00046 // Include Files 00047 // 00048 //------------------------------------------------------------------------------ 00049 00050 #include "mbed.h" 00051 #include "./dependencies/NSL01_HCI_Layer.h" 00052 #include <string.h> 00053 #include <stdint.h> 00054 00055 //------------------------------------------------------------------------------ 00056 // 00057 // Section Defines 00058 // 00059 //------------------------------------------------------------------------------ 00060 00061 #define DEVICE_ADDR_LEN 4 00062 #define KEY_LEN 16 00063 #define EUI_LEN 8 00064 00065 //------------------------------------------------------------------------------ 00066 // 00067 // General Declarations 00068 // 00069 //------------------------------------------------------------------------------ 00070 00071 //--Global variables from main.h 00072 extern Serial comm_pc; 00073 extern Serial comm_LoRa; 00074 00075 //--Define shortcuts for datatypes 00076 typedef int8_t INT8; 00077 typedef uint8_t UINT8; 00078 typedef uint16_t UINT16; 00079 typedef uint32_t UINT32; 00080 00081 //--Struct for Real Time Clock (RTC) information 00082 typedef struct 00083 { 00084 UINT16 year; 00085 UINT8 month; 00086 UINT8 day; 00087 UINT8 hour; 00088 UINT8 minute; 00089 UINT8 second; 00090 }RTC_struct; 00091 00092 //--Struct for Real Time Clock (RTC) alarm 00093 typedef struct 00094 { 00095 bool periodic; 00096 UINT8 hour; 00097 UINT8 minute; 00098 UINT8 second; 00099 }RTC_alarm_struct; 00100 00101 //--Struct for radio stack configuration 00102 typedef struct 00103 { 00104 UINT8 data_rate_index; 00105 UINT8 Tx_power; 00106 UINT8 adaptive_data_rate; 00107 UINT8 duty_cycle_control; 00108 UINT8 class_C_support; 00109 UINT8 RF_packet_format; 00110 UINT8 forwarding; 00111 UINT8 power_saving; 00112 UINT8 number_retransmissions; 00113 UINT8 band_index; 00114 UINT8 header_MAC_cmd_capacity; 00115 }Radio_config_struct; 00116 00117 //--Helper struct for ID -> string conversion 00118 typedef struct 00119 { 00120 int ID; 00121 const char* String; 00122 }TIDString; 00123 00124 //------------------------------------------------------------------------------ 00125 // 00126 // Endpoint (SAP) Identifier 00127 // 00128 //------------------------------------------------------------------------------ 00129 00130 #define DEVMGMT_SAP_ID 0x01 00131 #define LORAWAN_SAP_ID 0x10 00132 00133 //------------------------------------------------------------------------------ 00134 // 00135 // Device Management SAP Message Identifier 00136 // 00137 //------------------------------------------------------------------------------ 00138 00139 //--Status Identifier 00140 #define DEVMGMT_STATUS_OK 0x00 00141 #define DEVMGMT_STATUS_ERROR 0x01 00142 #define DEVMGMT_STATUS_CMD_NOT_SUPPORTED 0x02 00143 #define DEVMGMT_STATUS_WRONG_PARAMETER 0x03 00144 #define DEVMGMT_STATUS_WRONG_DEVICE_MODE 0x04 00145 00146 //--Message Identifier 00147 #define DEVMGMT_MSG_PING_REQ 0x01 //-Identifier for ping LoRa module 00148 #define DEVMGMT_MSG_PING_RSP 0x02 00149 00150 #define DEVMGMT_MSG_GET_DEVICE_INFO_REQ 0x03 //-Identifier for getting device infos 00151 #define DEVMGMT_MSG_GET_DEVICE_INFO_RSP 0x04 00152 00153 #define DEVMGMT_MSG_GET_FW_VERSION_REQ 0x05 //-Identifier for getting firmware infos 00154 #define DEVMGMT_MSG_GET_FW_VERSION_RSP 0x06 00155 00156 #define DEVMGMT_MSG_RESET_REQ 0x07 //--Software reset 00157 #define DEVMGMT_MSG_RESET_RSP 0x08 00158 00159 #define DEVMGMT_MSG_SET_OPMODE_REQ 0x09 //-Identifier for system operating mode 00160 #define DEVMGMT_MSG_SET_OPMODE_RSP 0x0A 00161 #define DEVMGMT_MSG_GET_OPMODE_REQ 0x0B 00162 #define DEVMGMT_MSG_GET_OPMODE_RSP 0x0C 00163 00164 #define DEVMGMT_MSG_SET_RTC_REQ 0x0D //-Identifier for RTC 00165 #define DEVMGMT_MSG_SET_RTC_RSP 0x0E 00166 #define DEVMGMT_MSG_GET_RTC_REQ 0x0F 00167 #define DEVMGMT_MSG_GET_RTC_RSP 0x10 00168 00169 #define DEVMGMT_MSG_GET_DEVICE_STATUS_REQ 0x17 //-Identifier for getting device status 00170 #define DEVMGMT_MSG_GET_DEVICE_STATUS_RSP 0x18 00171 00172 #define DEVMGMT_MSG_SET_RTC_ALARM_REQ 0x31 //--Identifier for RTC alarm 00173 #define DEVMGMT_MSG_SET_RTC_ALARM_RSP 0x32 00174 #define DEVMGMT_MSG_CLEAR_RTC_ALARM_REQ 0x33 00175 #define DEVMGMT_MSG_CLEAR_RTC_ALARM_RSP 0x34 00176 #define DEVMGMT_MSG_GET_RTC_ALARM_REQ 0x35 00177 #define DEVMGMT_MSG_GET_RTC_ALARM_RSP 0x36 00178 #define DEVMGMT_MSG_RTC_ALARM_IND 0x38 00179 00180 //------------------------------------------------------------------------------ 00181 // 00182 // LoRaWAN SAP Message Identifier 00183 // 00184 //------------------------------------------------------------------------------ 00185 00186 //--Status Identifier 00187 #define LORAWAN_STATUS_OK 0x00 00188 #define LORAWAN_STATUS_ERROR 0x01 00189 #define LORAWAN_STATUS_CMD_NOT_SUPPORTED 0x02 00190 #define LORAWAN_STATUS_WRONG_PARAMETER 0x03 00191 #define LORAWAN_STATUS_WRONG_DEVICE_MODE 0x04 00192 #define LORAWAN_STATUS_NOT_ACTIVATED 0x05 00193 #define LORAWAN_STATUS_BUSY 0x06 00194 #define LORAWAN_STATUS_QUEUE_FULL 0x07 00195 #define LORAWAN_STATUS_LENGTH_ERROR 0x08 00196 #define LORAWAN_STATUS_NO_FACTORY_SETTINGS 0x09 00197 #define LORAWAN_STATUS_CHANNEL_BLOCKED_BY_DC 0x0A 00198 #define LORAWAN_STATUS_CHANNEL_NOT_AVAILABLE 0x0B 00199 00200 //--Message Identifier 00201 #define LORAWAN_MSG_ACTIVATE_DEVICE_REQ 0x01 //--Identifier for ABP activation/reactivation and deactivation 00202 #define LORAWAN_MSG_ACTIVATE_DEVICE_RSP 0x02 00203 #define LORAWAN_MSG_REACTIVATE_DEVICE_REQ 0x1D 00204 #define LORAWAN_MSG_REACTIVATE_DEVICE_RSP 0x1E 00205 #define LORAWAN_MSG_DEACTIVATE_DEVICE_REQ 0x21 00206 #define LORAWAN_MSG_DEACTIVATE_DEVICE_RSP 0x22 00207 00208 #define LORAWAN_MSG_SET_JOIN_PARAM_REQ 0x05 //--Identifier for joining in OTA mode 00209 #define LORAWAN_MSG_SET_JOIN_PARAM_RSP 0x06 00210 #define LORAWAN_MSG_JOIN_NETWORK_REQ 0x09 00211 #define LORAWAN_MSG_JOIN_NETWORK_RSP 0x0A 00212 #define LORAWAN_MSG_JOIN_TRANSMIT_IND 0x0B 00213 #define LORAWAN_MSG_JOIN_NETWORK_IND 0x0C 00214 00215 #define LORAWAN_MSG_SEND_UDATA_REQ 0x0D //--Identifier for U-data 00216 #define LORAWAN_MSG_SEND_UDATA_RSP 0x0E 00217 #define LORAWAN_MSG_SEND_UDATA_TX_IND 0x0F 00218 #define LORAWAN_MSG_RECV_UDATA_RX_IND 0x10 00219 00220 #define LORAWAN_MSG_SEND_CDATA_REQ 0x11 //--Identifier for C-data 00221 #define LORAWAN_MSG_SEND_CDATA_RSP 0x12 00222 #define LORAWAN_MSG_SEND_CDATA_TX_IND 0x13 00223 #define LORAWAN_MSG_RECV_CDATA_RX_IND 0x14 00224 00225 #define LORAWAN_MSG_RECV_ACK_IND 0x15 //--Identifier for ACK receiption 00226 #define LORAWAN_MSG_RECV_NODATA_IND 0x16 00227 00228 #define LORAWAN_MSG_SET_RSTACK_CONFIG_REQ 0x19 //--Identifier for radio stack configuration 00229 #define LORAWAN_MSG_SET_RSTACK_CONFIG_RSP 0x1A 00230 #define LORAWAN_MSG_GET_RSTACK_CONFIG_REQ 0x1B 00231 #define LORAWAN_MSG_GET_RSTACK_CONFIG_RSP 0x1C 00232 00233 #define LORAWAN_MSG_FACTORY_RESET_REQ 0x23 //--Apply factory reset 00234 #define LORAWAN_MSG_FACTORY_RESET_RSP 0x24 00235 00236 #define LORAWAN_MSG_SET_DEVICE_EUI_REQ 0x25 //--Identifier for EUI 00237 #define LORAWAN_MSG_SET_DEVICE_EUI_RSP 0x26 00238 #define LORAWAN_MSG_GET_DEVICE_EUI_REQ 0x27 00239 #define LORAWAN_MSG_GET_DEVICE_EUI_RSP 0x28 00240 00241 #define LORAWAN_MSG_GET_NWK_STATUS_REQ 0x29 //--Identifier for network status 00242 #define LORAWAN_MSG_GET_NWK_STATUS_RSP 0x2A 00243 00244 #define LORAWAN_MSG_SET_CUSTOM_CFG_REQ 0x31 //--Identifier for custom configuration 00245 #define LORAWAN_MSG_SET_CUSTOM_CFG_RSP 0x32 00246 #define LORAWAN_MSG_GET_CUSTOM_CFG_REQ 0x33 00247 #define LORAWAN_MSG_GET_CUSTOM_CFG_RSP 0x34 00248 00249 #define LORAWAN_MSG_GET_SUPPORTED_BANDS_REQ 0x35 //--Identifier for supported frequency bands 00250 #define LORAWAN_MSG_GET_SUPPORTED_BANDS_RSP 0x36 00251 00252 #define LORAWAN_MSG_SET_TXPOWER_LIMIT_CONFIG_REQ 0x37 //--Identifier for Tx power limit configuration 00253 #define LORAWAN_MSG_SET_TXPOWER_LIMIT_CONFIG_RSP 0x38 00254 #define LORAWAN_MSG_GET_TXPOWER_LIMIT_CONFIG_REQ 0x39 00255 #define LORAWAN_MSG_GET_TXPOWER_LIMIT_CONFIG_RSP 0x3A 00256 00257 //------------------------------------------------------------------------------ 00258 // 00259 // LoRaWAN Event Message Identifier 00260 // 00261 //------------------------------------------------------------------------------ 00262 00263 #define LORAWAN_EVENT_MSG_ALARM 0x01 //--RTC alarm indication event 00264 #define LORAWAN_EVENT_MSG_JOIN_TIMEOUT 0x02 //--Join network indication timeout 00265 #define LORAWAN_EVENT_MSG_CDATA_MAX_RETRANSMISSION 0x03 //--Maximum number of retransmissions reached 00266 #define LORAWAN_EVENT_MSG_CDATA_PAYLOAD_EXCEEDED 0x04 //--Maximum payload size exceeded for current data rate 00267 00268 00269 /** NSL01 class: A library which controls the NSL01 LoRaWAN shield from 00270 * mCloud Systems GmbH. 00271 * 00272 * @brief The NSL01 is a professional plug & play LoRaWAN shield for a wide 00273 * range of STM32 Nucleo-64&tm; boards with Arduino&tm; Uno Rev3 00274 * connectivity. 00275 * 00276 * @brief For more information about the NSL01 LoRaWAN shield: 00277 * http://www.mcloud-systems.com/nsl01-lorawan-nucleo-arduino-shield 00278 * 00279 * @note Two serial device objects have to be specified in main: 00280 * - Serial comm_pc(SERIAL_TX, SERIAL_RX) 00281 * - Serial comm_LoRa(PB_6,PA_10) => TX and RX pins depending on STM32 00282 * Nucleo-64 board! => Please check datasheet of NSL01! 00283 * 00284 * @note The dependencies directory contains several C-driver functions which 00285 * have to be included in the project! The NSL01 class is based on these 00286 * drivers! 00287 * 00288 * @author mCloud Systems Team 00289 * @version V1.0 00290 * @date 20-June-2018 00291 * 00292 * Copyright (c) 2018 mCloud Systems GmbH, MIT License 00293 * 00294 * Permission is hereby granted, free of charge, to any person obtaining a copy 00295 * of this software and associated documentation files (the "Software"), to 00296 * deal in the Software without restriction, including without limitation the 00297 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 00298 * sell copies of the Software, and to permit persons to whom the Software is 00299 * furnished to do so, subject to the following conditions: 00300 * 00301 * The above copyright notice and this permission notice shall be included in 00302 * all copies or substantial portions of the Software. 00303 * 00304 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 00305 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00306 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 00307 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 00308 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 00309 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 00310 * THE SOFTWARE. 00311 * 00312 * Example: 00313 * @code 00314 * #include "mbed.h" 00315 * #include "./NSL01/NSL01.h" 00316 * 00317 * //--UART interface for onboard LoRaWAN radio module 00318 * //--(Tx and Rx pin depending on STM32 Nucleo-64 board) 00319 * PinName Pin_UART_Tx = PB_6; 00320 * PinName Pin_UART_Rx = PA_10; 00321 * Serial comm_LoRa(Pin_UART_Tx, Pin_UART_Rx); 00322 * 00323 * //--Standard serial interface (PC) for (internal) debugging 00324 * Serial comm_pc(SERIAL_TX, SERIAL_RX); 00325 * 00326 * int main() 00327 * { 00328 * //--Create NSL01 object and initialize device 00329 * NSL01 LoRa; 00330 * 00331 * //--Apply methods, e.g. ping NSL01 device 00332 * LoRa.ping(); 00333 * 00334 * //--Insert your specific code here 00335 * 00336 * } 00337 * @endcode 00338 */ 00339 00340 class NSL01 00341 { 00342 public: 00343 00344 00345 /** Consructor of NSL01: Create a NSL01 instance with the serial device 00346 * objects specified in main. 00347 */ 00348 NSL01(void); 00349 00350 00351 /** Destructor of NSL01: Destroy instance. 00352 * 00353 */ 00354 ~NSL01(); 00355 00356 00357 /** Member variable for Real Time Clock (RTC) information based on global 00358 * defined RTC_struct which contains: 00359 * - UINT16 year 00360 * - UINT8 month 00361 * - UINT8 day 00362 * - UINT8 hour 00363 * - UINT8 minute 00364 * - UINT8 second 00365 */ 00366 RTC_struct RTC_data; 00367 00368 00369 /** Member variable for Real Time Clock (RTC) alarm based on global 00370 * defined RTC_alarm_struct which contains: 00371 * - bool periodic 00372 * - UINT8 hour 00373 * - UINT8 minute 00374 * - UINT8 second 00375 */ 00376 RTC_alarm_struct RTC_alarm; 00377 00378 00379 /** Member variable for radio stack configuration based on global defined 00380 * Radio_config_struct which contains: 00381 * - UINT8 data_rate_index; 00382 * - UINT8 Tx_power; 00383 * - UINT8 adaptive_data_rate; 00384 * - UINT8 duty_cycle_control; 00385 * - UINT8 class_C_support; 00386 * - UINT8 RF_packet_format; 00387 * - UINT8 forwarding; 00388 * - UINT8 power_saving; 00389 * - UINT8 number_retransmissions; 00390 * - UINT8 band_index; 00391 * - UINT8 header_MAC_cmd_capacity; 00392 */ 00393 Radio_config_struct Radio_config; 00394 00395 00396 /** Method to ping NSL01. 00397 * 00398 * @returns 1 on success, -1 on error 00399 */ 00400 int ping(void); 00401 00402 00403 /** Method to reset NSL01 (software reset). 00404 * 00405 * @note After executing this command the module will be restarted after 00406 * approximately 200ms! 00407 * 00408 * @returns 1 on success, -1 on error 00409 */ 00410 int reset(void); 00411 00412 00413 /** Method to identify the local connected NSL01 device. As a result the 00414 * device sends a response message which contains all necessary device 00415 * information. 00416 * 00417 * @returns 1 on success, -1 on error 00418 */ 00419 int get_device_info(void); 00420 00421 00422 /** Method to identify the onboard radio firmware of NSL01. As a result the 00423 * device sends a response message which contains all firmware related 00424 * data. 00425 * 00426 * @returns 1 on success, -1 on error 00427 */ 00428 int get_firmware_info(void); 00429 00430 00431 /** Method to get the current device status of NSL01. As a result the device 00432 * sends a response message which contains all device status information. 00433 * 00434 * @returns 1 on success, -1 on error 00435 */ 00436 int get_device_status(void); 00437 00438 00439 /** Method to read the current network / activation status of NSL01. 00440 * 00441 * @returns 1 on success, -1 on error 00442 */ 00443 int get_network_status(void); 00444 00445 00446 /** Method to read the current Real Time Clock (RTC) value of NSL01. 00447 * 00448 * @returns 1 on success, -1 on error 00449 */ 00450 int get_RTC_info(void); 00451 00452 00453 /** Method to set the Real Time Clock (RTC) value of NSL01. 00454 * 00455 * @param RTC_data : RTC data defined in RTC_struct 00456 * 00457 * @returns 1 on success, -1 on error 00458 */ 00459 int set_RTC(RTC_struct RTC_data); 00460 00461 00462 /** Method to set the Real Time Clock (RTC) alarm of NSL01. 00463 * 00464 * @param RTC_alarm_data : RTC alarm defined in RTC_alarm_struct 00465 * 00466 * @returns 1 on success, -1 on error 00467 */ 00468 int set_RTC_alarm(RTC_alarm_struct RTC_alarm_data); 00469 00470 00471 /** Method to get the Real Time Clock (RTC) alarm info of NSL01. 00472 * 00473 * @returns 1 on success, -1 on error 00474 */ 00475 int get_RTC_alarm(void); 00476 00477 00478 /** Method to clear a pending Real Time Clock (RTC) alarm of NSL01. 00479 * 00480 * @returns 1 on success, -1 on error 00481 */ 00482 int clear_RTC_alarm(void); 00483 00484 00485 /** Method to get the current system operation mode of NSL01. 00486 * 00487 * @note Two system operation modes are supported: 00488 * - Standard / Application Mode 00489 * - Customer Mode 00490 * 00491 * @note Some device functionality is only supported in customer mode! 00492 * 00493 * @returns 1 on success, -1 on error 00494 */ 00495 int get_system_operation_mode(void); 00496 00497 00498 /** Method to set the system operation mode of NSL01. 00499 * 00500 * @note After executing this command the module will be restarted after 00501 * approximately 200ms! 00502 * 00503 * @param system_mode 0 : Standard/Application mode 00504 * @param system_mode 1 : Reserved/Not used 00505 * @param system_mode 2 : Reserved/Not used 00506 * @param system_mode 3 : Customer mode 00507 * 00508 * @returns 1 on success, -1 on error 00509 */ 00510 int set_system_operation_mode(UINT8 system_mode); 00511 00512 00513 /** Method to activate NSL01 in Activation by Personalization (ABP) mode 00514 * and save parameters in non-volatile memory. 00515 * 00516 * @note A device must be activated prior to any further data exchange with 00517 * a network server! 00518 * 00519 * @note After a successful activation the NSL01 will automatically send an 00520 * empty unconfirmed uplink message ("alive message") over the air! 00521 * 00522 * @param deviceAddress : unique 32-Bit Device Address 00523 * @param *nwkSessionKey : device specific 128-Bit Network Session Key 00524 * @param *appSessionKey : device specific 128-Bit Application Session Key 00525 * 00526 * @returns 1 on success, -1 on error 00527 */ 00528 int ABP_device_activation(UINT32 deviceAddress, 00529 UINT8* nwkSessionKey, 00530 UINT8* appSessionKey); 00531 00532 00533 /** Method to reactivate NSL01 in Activation by Personalization (ABP) mode 00534 * using the parameters previously stored in non-volatile memory. 00535 * 00536 * @note A device must be activated prior to any further data exchange with 00537 * a network server! 00538 * 00539 * @note After a successful activation the NSL01 will automatically send an 00540 * empty unconfirmed uplink message ("alive message") over the air! 00541 * 00542 * @returns 1 on success, -1 on error 00543 */ 00544 int ABP_device_reactivation(void); 00545 00546 00547 /** Method to deactivate the NSL01 LoRaWAN end-device => further data 00548 * exchange over the air will be disabled. 00549 * 00550 * @returns 1 on success, -1 on error 00551 */ 00552 int deactivate(void); 00553 00554 00555 /** Method to configure the Over-the-Air Activation (OTTA) parameters of 00556 * NSL01 which are used during the join network procedure 'join_network'. 00557 * 00558 * @param *appEUI : globally unique 64-Bit Application EUI 00559 * @param *appKey : device specific 128-Bit AES Application Key 00560 * 00561 * @returns 1 on success, -1 on error 00562 */ 00563 int set_join_parameter(UINT8* appEUI, UINT8* appKey); 00564 00565 00566 /** Method to start the join network procedure of NSL01 in Over-the-Air 00567 * Activation (OTTA) mode with previously defined parameters in 00568 * 'set_join_parameter' method. 00569 * 00570 * @note Once the 'join_network' method is triggered an internal event 00571 * method is invoked periodically to indicate the joining procedure. 00572 * 00573 * @note An internal join network indication event method is invoked after 00574 * successful reception of a server join response packet or after the 00575 * expiration of a complete join process without success (the join request 00576 * will be retransmitted changing the spreading factor from SF7 till SF12, 00577 * reusing each spreading factor twice). 00578 * 00579 * @returns 1 on success, -1 on error 00580 */ 00581 int join_network(void); 00582 00583 00584 /** Method to transmit data in an unreliable way to the network server <=> 00585 * no acknowledgement will be sent from the network server and no 00586 * retransmission method is available on the end-device (NSL01) side 00587 * 00588 * @note An internal 'unreliable data transmit indication' event method is 00589 * invoked after the radio packet has been sent, containing information 00590 * about the data transfer. 00591 * 00592 * @param port : LoRaWAN Port number (> 0) 00593 * @param *srcData : Application Payload (data which have to be transmitted) 00594 * @param srcLength : Lenght of Application Payload data 00595 * 00596 * @returns 1 on success, -1 on error 00597 */ 00598 int send_Udata(UINT8 port, UINT8* srcData, int srcLength); 00599 00600 00601 /** Method to transmit data in a reliable way to the network server <=> 00602 * confirmed data transmission. 00603 * 00604 * @note An internal 'reliable data transmit indication' event method is 00605 * invoked after the radio packet has been sent, containing information 00606 * about the data transfer. 00607 * 00608 * @param port : LoRaWAN Port number (> 0) 00609 * @param *srcData : Application Payload (data which have to be transmitted) 00610 * @param srcLength : Lenght of Application Payload data 00611 * 00612 * @returns 1 on success, -1 on error 00613 */ 00614 int send_Cdata(UINT8 port, UINT8* srcData, int srcLength); 00615 00616 00617 /** Method to set/configure the internal radio stack configuration of NSL01 00618 * <=> main parameters for data transmission. 00619 * 00620 * @param radio_stack : Radio stack config data defined in 00621 * Radio_config_struct 00622 * 00623 * @returns 1 on success, -1 on error 00624 */ 00625 int set_radio_stack_config(Radio_config_struct radio_stack); 00626 00627 00628 /** Method to read the current radio stack configuration of NSL01 <=> main 00629 * parameters for data transmission. 00630 * 00631 * @returns 1 on success, -1 on error 00632 */ 00633 int get_radio_stack_config(void); 00634 00635 00636 /** Method to get information related to the supported frequency bands used 00637 * by the firmware. Moreover, the maximum supported EIRP for each band is 00638 * provided. 00639 * 00640 * @returns 1 on success, -1 on error 00641 */ 00642 int get_freqband_info(void); 00643 00644 00645 /** Method to get/read the unique 64-bit device EUI. 00646 * 00647 * @returns 1 on success, -1 on error 00648 */ 00649 int get_EUI(void); 00650 00651 00652 /** Method to set/write the unique 64-bit device EUI. 00653 * 00654 * @note The device EUI can only be set in "customer mode"! 00655 * 00656 * @param *device_EUI : Unique 64-bit device EUI (UINT8 array) 00657 * 00658 * @returns 1 on success, -1 on error 00659 */ 00660 int set_EUI(UINT8 *device_EUI); 00661 00662 00663 /** Method to configure the custom parameters (RF gain offset to compensate 00664 * possible transmission losses/gains including circuit matching, 00665 * antennas, ...). The RF gain offset should be rated in units of dBd 00666 * (decibels relative to a half-wavelength dipole antenna, where 00667 * 0 dBd = 2.15 dBi). 00668 * 00669 * @note This parameter can only be set in "customer mode"! 00670 * 00671 * @param RF_gain_offset : RF gain offset in dBd 00672 * 00673 * @returns 1 on success, -1 on error 00674 */ 00675 int set_custom_configuration(int RF_gain_offset); 00676 00677 00678 /** Method to get/read the custom configuration parameters (RF gain offset) 00679 * of NSL01. 00680 * 00681 * @returns 1 on success, -1 on error 00682 */ 00683 int get_custom_configuration(void); 00684 00685 00686 /** Method to restore the initial firmware settings, stored during 00687 * production time (factory reset). 00688 * 00689 * @returns 1 on success, -1 on error 00690 */ 00691 int factory_reset(void); 00692 00693 00694 /** Method to read the transmit power limit configuration parameters of 00695 * NSL01 for different frequency sub-bands. 00696 * 00697 * @returns 1 on success, -1 on error 00698 */ 00699 int get_PowerLimit_configuration(void); 00700 00701 00702 /** Method to set/configure the transmit power limit configuration 00703 * parameters of NSL01 for a dedicated frequency sub-band. 00704 * 00705 * @note These parameters can only be set in "customer mode"! 00706 * 00707 * @param sub_band : Sub-band index [0...5] according to specification 00708 * @param power_limit_flag : Tx power limit flag for sub-band [enabled/disabled] 00709 * @param power_limit : Tx power limit for sub-band in dBm [0...16] 00710 * 00711 * @returns 1 on success, -1 on error 00712 */ 00713 int set_PowerLimit_configuration(UINT8 sub_band, UINT8 power_limit_flag, UINT8 power_limit); 00714 00715 00716 private: 00717 00718 00719 /** Internal method to initialize NSL01. 00720 * 00721 * @note This method is automatically invoked in constructor. 00722 * 00723 */ 00724 void initialize(void); 00725 00726 00727 /** Internal callback method for event handling of NSL01. 00728 * 00729 * @note This method is invoked automatically whenever an event occurs. 00730 * 00731 * @param Event_ID : Event message identifier defined in header of NSL01.h 00732 */ 00733 static void 00734 LoRa_event(int Event_ID); 00735 00736 00737 /** Internal processing of received HCI messages (callback method). 00738 * 00739 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00740 * 00741 * @returns TWiMOD_HCI_Message* struct 00742 */ 00743 static TWiMOD_HCI_Message* 00744 Process_RxMessage(TWiMOD_HCI_Message* rxMessage); 00745 00746 00747 /** Internal processing of received device management messages. 00748 * 00749 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00750 */ 00751 static void 00752 Process_DevMgmt_Message(TWiMOD_HCI_Message* rxMessage); 00753 00754 00755 /** Internal processing of received LoRaWAN messages. 00756 * 00757 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00758 */ 00759 static void 00760 Process_LoRaWAN_Message(TWiMOD_HCI_Message* rxMessage); 00761 00762 00763 /** Internal method to show device information of NSL01. 00764 * 00765 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00766 */ 00767 static void 00768 DevMgmt_DeviceInfo_Rsp(TWiMOD_HCI_Message* rxMessage); 00769 00770 00771 /** Internal method to show firmware information of NSL01. 00772 * 00773 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00774 */ 00775 static void 00776 DevMgmt_FirmwareVersion_Rsp(TWiMOD_HCI_Message* rxMessage); 00777 00778 00779 /** Internal method to show device status of NSL01. 00780 * 00781 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00782 */ 00783 static void 00784 DevMgmt_DeviceStatus_Rsp(TWiMOD_HCI_Message* rxMessage); 00785 00786 00787 /** Internal method to show RTC information of NSL01. 00788 * 00789 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00790 */ 00791 static void 00792 DevMgmt_RTC_Rsp(TWiMOD_HCI_Message* rxMessage); 00793 00794 00795 /** Internal method to show RTC alarm information of NSL01. 00796 * 00797 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00798 */ 00799 static void 00800 DevMgmt_Get_Alarm_Rsp(TWiMOD_HCI_Message* rxMessage); 00801 00802 00803 /** Internal method to get the system operation mode of NSL01. 00804 * 00805 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00806 */ 00807 static void 00808 DevMgmt_OperationMode_Rsp(TWiMOD_HCI_Message* rxMessage); 00809 00810 00811 /** Internal method to get the status of NSL01 after reactivation in 00812 * Activation by Personalization (ABP) mode with parameters in non- 00813 * volatile memory. 00814 * 00815 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00816 */ 00817 static void 00818 LoRaWAN_Reactivate_Device_Rsp(TWiMOD_HCI_Message* rxMessage); 00819 00820 00821 /** Internal event method for join network transmit indication which is 00822 * automatically invoked whenever the join radio message has been sent to 00823 * the host. 00824 * 00825 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00826 */ 00827 static void 00828 LoRaWAN_Process_JoinTxIndication(TWiMOD_HCI_Message* rxMessage); 00829 00830 00831 /** Internal event method to indicate the join network procedure which is 00832 * automatically invoked after successful reception of a server join 00833 * response or after expiration of a complete join process without success. 00834 * 00835 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00836 */ 00837 static void 00838 LoRaWAN_Process_JoinNetworkIndication(TWiMOD_HCI_Message* rxMessage); 00839 00840 00841 /** Internal method to evaluate response from 'send_Udata' method. 00842 * 00843 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00844 */ 00845 static void 00846 LoRaWAN_send_Udata_Rsp(TWiMOD_HCI_Message* rxMessage); 00847 00848 00849 /** Internal event method which is triggered by the host after a radio 00850 * packet has been sent. 00851 * 00852 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00853 */ 00854 static void 00855 LoRaWAN_Udata_Tx_Indication(TWiMOD_HCI_Message* rxMessage); 00856 00857 00858 /** Internal event method which is sent to the host after reception of an 00859 * unreliable radio packet containing application payload. 00860 * 00861 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00862 */ 00863 static void 00864 LoRaWAN_Udata_Rx_Indication(TWiMOD_HCI_Message* rxMessage); 00865 00866 00867 /** Internal method to evaluate response from 'send_Cdata' method. 00868 * 00869 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00870 */ 00871 static void 00872 LoRaWAN_send_Cdata_Rsp(TWiMOD_HCI_Message* rxMessage); 00873 00874 00875 /** Internal event method which is invoked by the host after a radio 00876 * packet has been sent or if the retransmission procedure finishes 00877 * without success. 00878 * 00879 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00880 */ 00881 static void 00882 LoRaWAN_Cdata_Tx_Indication(TWiMOD_HCI_Message* rxMessage); 00883 00884 00885 /** Internal event message which is sent to the host after reception of a 00886 * reliable radio packet containing application payload. The device will 00887 * acknowledge the reception with a set Ack-Bit in the next reliable/ 00888 * unreliable uplink radio packet to the network server. 00889 * 00890 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00891 */ 00892 static void 00893 LoRaWAN_Cdata_Rx_Indication(TWiMOD_HCI_Message* rxMessage); 00894 00895 00896 /** Internal event method which is sent to the host in case no expected 00897 * confirmation or data has been received as a result of prior reliable 00898 * uplink radio packet. 00899 * 00900 * @note Method is not used at the moment! 00901 * 00902 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00903 */ 00904 static void 00905 LoRaWAN_Rx_NoData_Indication(TWiMOD_HCI_Message* rxMessage); 00906 00907 00908 /** Internal method to evaluate response from 'set_radio_stack_config' 00909 * method. 00910 * 00911 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00912 */ 00913 static void 00914 LoRaWAN_Set_RadioStack_Config_Rsp(TWiMOD_HCI_Message* rxMessage); 00915 00916 00917 /** Internal method to evaluate response from 'get_radio_stack_config' 00918 * method. 00919 * 00920 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00921 */ 00922 static void 00923 LoRaWAN_Get_RadioStack_Config_Rsp(TWiMOD_HCI_Message* rxMessage); 00924 00925 00926 /** Internal method to evaluate response from 'get_freqband_info' 00927 * method. 00928 * 00929 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00930 */ 00931 static void 00932 LoRaWAN_Get_FreqBand_Rsp(TWiMOD_HCI_Message* rxMessage); 00933 00934 00935 /** Internal method to evaluate response from 'get_EUI' method. 00936 * 00937 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00938 */ 00939 static void 00940 LoRaWAN_Get_DeviceEUI_Rsp(TWiMOD_HCI_Message* rxMessage); 00941 00942 00943 /** Internal method to evaluate response from 'get_custom_configuration' 00944 * method. 00945 * 00946 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00947 */ 00948 static void 00949 LoRaWAN_Get_Custom_Config_Rsp(TWiMOD_HCI_Message* rxMessage); 00950 00951 00952 /** Internal method to evaluate response from 'get_network_status' 00953 * method. 00954 * 00955 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00956 */ 00957 static void 00958 LoRaWAN_Network_Status_Rsp(TWiMOD_HCI_Message* rxMessage); 00959 00960 00961 /** Internal method to evaluate response from 'get_PowerLimit_configuration' 00962 * method. 00963 * 00964 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00965 */ 00966 static void 00967 LoRaWAN_Get_TxPower_Limit_Config_Rsp(TWiMOD_HCI_Message* rxMessage); 00968 00969 00970 /** Internal method to evaluate response from 'set_PowerLimit_configuration' 00971 * method. 00972 * 00973 * @param TWiMOD_HCI_Message* : Rx message struct in WiMOD_HCI_Layer.h 00974 */ 00975 static void 00976 LoRaWAN_Set_TxPower_Limit_Config_Rsp(TWiMOD_HCI_Message* rxMessage); 00977 00978 00979 /** Internal method to show status response as human readable string. 00980 * 00981 * @param message_string : Message string to display 00982 * @param statusTable : Device management status strings 00983 * @param statusID : Status identifier 00984 */ 00985 static void 00986 LoRaWAN_ShowResponse(const char* message_string, const TIDString* statusTable, UINT8 statusID); 00987 00988 00989 /** Internal help method to convert RTC data. 00990 * 00991 * @param RTC_data : RTC data in UINT32 format 00992 * @param *RTC_string : RTC data as string 00993 */ 00994 static void 00995 convert_RTC_message(UINT32 RTC_data, char *RTC_string); 00996 00997 00998 /** Internal help method for data conversion (UINT8 array in UINT16 value). 00999 * 01000 * @param *Payload : UINT8 array 01001 */ 01002 static UINT16 01003 Convert_Payload_Data_UINT16(UINT8 *Payload); 01004 01005 01006 /** Internal help method for data conversion (UINT8 array in UINT32 value). 01007 * 01008 * @param *Payload : UINT8 array 01009 */ 01010 static UINT32 01011 Convert_Payload_Data_UINT32(UINT8 *Payload); 01012 01013 01014 /** Internal method to wait until response from LoRa module. 01015 * 01016 */ 01017 void LoRaWAN_wait(void); 01018 }; 01019 01020 #endif // NSL01_h 01021 01022 //------------------------------------------------------------------------------ 01023 // end of file 01024 //------------------------------------------------------------------------------
Generated on Wed Jul 13 2022 06:29:55 by
1.7.2