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

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers NSL01.h Source File

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 //------------------------------------------------------------------------------