The NSL01 library contains the software stack to control 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 have a look at: http://www.mcloud-systems.com/nsl01-lorawan-nucleo-arduino-shield

Fork of NSL01 by mCloud Systems

Embed: (wiki syntax)

« Back to documentation index

NSL01 Class Reference

NSL01 Class Reference

NSL01 class: A library which controls the NSL01 LoRaWAN shield from mCloud Systems GmbH. More...

#include <NSL01.h>

Public Member Functions

 NSL01 (void)
 Consructor of NSL01: Create a NSL01 instance with the serial device objects specified in main.
 ~NSL01 ()
 Destructor of NSL01: Destroy instance.
int ping (void)
 Method to ping NSL01.
int reset (void)
 Method to reset NSL01 (software reset).
int get_device_info (void)
 Method to identify the local connected NSL01 device.
int get_firmware_info (void)
 Method to identify the onboard radio firmware of NSL01.
int get_device_status (void)
 Method to get the current device status of NSL01.
int get_network_status (void)
 Method to read the current network / activation status of NSL01.
int get_RTC_info (void)
 Method to read the current Real Time Clock (RTC) value of NSL01.
int set_RTC (RTC_struct RTC_data)
 Method to set the Real Time Clock (RTC) value of NSL01.
int set_RTC_alarm (RTC_alarm_struct RTC_alarm_data)
 Method to set the Real Time Clock (RTC) alarm of NSL01.
int get_RTC_alarm (void)
 Method to get the Real Time Clock (RTC) alarm info of NSL01.
int clear_RTC_alarm (void)
 Method to clear a pending Real Time Clock (RTC) alarm of NSL01.
int get_system_operation_mode (void)
 Method to get the current system operation mode of NSL01.
int set_system_operation_mode (UINT8 system_mode)
 Method to set the system operation mode of NSL01.
int ABP_device_activation (UINT32 deviceAddress, UINT8 *nwkSessionKey, UINT8 *appSessionKey)
 Method to activate NSL01 in Activation by Personalization (ABP) mode and save parameters in non-volatile memory.
int ABP_device_reactivation (void)
 Method to reactivate NSL01 in Activation by Personalization (ABP) mode using the parameters previously stored in non-volatile memory.
int deactivate (void)
 Method to deactivate the NSL01 LoRaWAN end-device => further data exchange over the air will be disabled.
int set_join_parameter (UINT8 *appEUI, UINT8 *appKey)
 Method to configure the Over-the-Air Activation (OTTA) parameters of NSL01 which are used during the join network procedure 'join_network'.
int join_network (void)
 Method to start the join network procedure of NSL01 in Over-the-Air Activation (OTTA) mode with previously defined parameters in 'set_join_parameter' method.
int send_Udata (UINT8 port, UINT8 *srcData, int srcLength)
 Method to transmit data in an unreliable way to the network server <=> no acknowledgement will be sent from the network server and no retransmission method is available on the end-device (NSL01) side.
int send_Cdata (UINT8 port, UINT8 *srcData, int srcLength)
 Method to transmit data in a reliable way to the network server <=> confirmed data transmission.
int set_radio_stack_config (Radio_config_struct radio_stack)
 Method to set/configure the internal radio stack configuration of NSL01 <=> main parameters for data transmission.
int get_radio_stack_config (void)
 Method to read the current radio stack configuration of NSL01 <=> main parameters for data transmission.
int get_freqband_info (void)
 Method to get information related to the supported frequency bands used by the firmware.
int get_EUI (void)
 Method to get/read the unique 64-bit device EUI.
int set_EUI (UINT8 *device_EUI)
 Method to set/write the unique 64-bit device EUI.
int set_custom_configuration (int RF_gain_offset)
 Method to configure the custom parameters (RF gain offset to compensate possible transmission losses/gains including circuit matching, antennas, ...).
int get_custom_configuration (void)
 Method to get/read the custom configuration parameters (RF gain offset) of NSL01.
int factory_reset (void)
 Method to restore the initial firmware settings, stored during production time (factory reset).
int get_PowerLimit_configuration (void)
 Method to read the transmit power limit configuration parameters of NSL01 for different frequency sub-bands.
int set_PowerLimit_configuration (UINT8 sub_band, UINT8 power_limit_flag, UINT8 power_limit)
 Method to set/configure the transmit power limit configuration parameters of NSL01 for a dedicated frequency sub-band.

Data Fields

RTC_struct RTC_data
 Member variable for Real Time Clock (RTC) information based on global defined RTC_struct which contains:

  • UINT16 year
  • UINT8 month
  • UINT8 day
  • UINT8 hour
  • UINT8 minute
  • UINT8 second.

RTC_alarm_struct RTC_alarm
 Member variable for Real Time Clock (RTC) alarm based on global defined RTC_alarm_struct which contains:

  • bool periodic
  • UINT8 hour
  • UINT8 minute
  • UINT8 second.

Radio_config_struct Radio_config
 Member variable for radio stack configuration based on global defined Radio_config_struct which contains:

  • UINT8 data_rate_index;
  • UINT8 Tx_power;
  • UINT8 adaptive_data_rate;
  • UINT8 duty_cycle_control;
  • UINT8 class_C_support;
  • UINT8 RF_packet_format;
  • UINT8 forwarding;
  • UINT8 power_saving;
  • UINT8 number_retransmissions;
  • UINT8 band_index;
  • UINT8 header_MAC_cmd_capacity;.


Detailed Description

NSL01 class: A library which controls the NSL01 LoRaWAN shield from mCloud Systems GmbH.

The NSL01 is a professional plug & play LoRaWAN shield for a wide range of STM32 Nucleo-64™ boards with Arduino™ Uno Rev3 connectivity.

For more information about the NSL01 LoRaWAN shield: http://www.mcloud-systems.com/nsl01-lorawan-nucleo-arduino-shield

Note:
Two serial device objects have to be specified in main:
  • Serial comm_pc(SERIAL_TX, SERIAL_RX)
  • Serial comm_LoRa(PB_6,PA_10) => TX and RX pins depending on STM32 Nucleo-64 board! => Please check datasheet of NSL01!
The dependencies directory contains several C-driver functions which have to be included in the project! The NSL01 class is based on these drivers!
Author:
mCloud Systems Team
Version:
V1.0
Date:
20-June-2018

Copyright (c) 2018 mCloud Systems GmbH, MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Example:

   #include "mbed.h"
   #include "./NSL01/NSL01.h"

   //--UART interface for onboard LoRaWAN radio module
   //--(Tx and Rx pin depending on STM32 Nucleo-64 board)
   PinName Pin_UART_Tx = PB_6;
   PinName Pin_UART_Rx = PA_10;
   Serial comm_LoRa(Pin_UART_Tx, Pin_UART_Rx);

   //--Standard serial interface (PC) for (internal) debugging
   Serial comm_pc(SERIAL_TX, SERIAL_RX);
 
   int main() 
   {
      //--Create NSL01 object and initialize device
      NSL01 LoRa;
      
      //--Apply methods, e.g. ping NSL01 device
      LoRa.ping();

      //--Insert your specific code here

   }

Definition at line 340 of file NSL01.h.


Constructor & Destructor Documentation

NSL01 ( void   )

Consructor of NSL01: Create a NSL01 instance with the serial device objects specified in main.

Definition at line 117 of file NSL01.cpp.

~NSL01 (  )

Destructor of NSL01: Destroy instance.

Definition at line 134 of file NSL01.cpp.


Member Function Documentation

int ABP_device_activation ( UINT32  deviceAddress,
UINT8 *  nwkSessionKey,
UINT8 *  appSessionKey 
)

Method to activate NSL01 in Activation by Personalization (ABP) mode and save parameters in non-volatile memory.

Note:
A device must be activated prior to any further data exchange with a network server!
After a successful activation the NSL01 will automatically send an empty unconfirmed uplink message ("alive message") over the air!
Parameters:
deviceAddress: unique 32-Bit Device Address
*nwkSessionKey: device specific 128-Bit Network Session Key
*appSessionKey: device specific 128-Bit Application Session Key
Returns:
1 on success, -1 on error

Definition at line 612 of file NSL01.cpp.

int ABP_device_reactivation ( void   )

Method to reactivate NSL01 in Activation by Personalization (ABP) mode using the parameters previously stored in non-volatile memory.

Note:
A device must be activated prior to any further data exchange with a network server!
After a successful activation the NSL01 will automatically send an empty unconfirmed uplink message ("alive message") over the air!
Returns:
1 on success, -1 on error

Definition at line 690 of file NSL01.cpp.

int clear_RTC_alarm ( void   )

Method to clear a pending Real Time Clock (RTC) alarm of NSL01.

Returns:
1 on success, -1 on error

Definition at line 493 of file NSL01.cpp.

int deactivate ( void   )

Method to deactivate the NSL01 LoRaWAN end-device => further data exchange over the air will be disabled.

Returns:
1 on success, -1 on error

Definition at line 722 of file NSL01.cpp.

int factory_reset ( void   )

Method to restore the initial firmware settings, stored during production time (factory reset).

Returns:
1 on success, -1 on error

Definition at line 1347 of file NSL01.cpp.

int get_custom_configuration ( void   )

Method to get/read the custom configuration parameters (RF gain offset) of NSL01.

Returns:
1 on success, -1 on error

Definition at line 1318 of file NSL01.cpp.

int get_device_info ( void   )

Method to identify the local connected NSL01 device.

As a result the device sends a response message which contains all necessary device information.

Returns:
1 on success, -1 on error

Definition at line 207 of file NSL01.cpp.

int get_device_status ( void   )

Method to get the current device status of NSL01.

As a result the device sends a response message which contains all device status information.

Returns:
1 on success, -1 on error

Definition at line 267 of file NSL01.cpp.

int get_EUI ( void   )

Method to get/read the unique 64-bit device EUI.

Returns:
1 on success, -1 on error

Definition at line 1188 of file NSL01.cpp.

int get_firmware_info ( void   )

Method to identify the onboard radio firmware of NSL01.

As a result the device sends a response message which contains all firmware related data.

Returns:
1 on success, -1 on error

Definition at line 237 of file NSL01.cpp.

int get_freqband_info ( void   )

Method to get information related to the supported frequency bands used by the firmware.

Moreover, the maximum supported EIRP for each band is provided.

Returns:
1 on success, -1 on error

Definition at line 1160 of file NSL01.cpp.

int get_network_status ( void   )

Method to read the current network / activation status of NSL01.

Returns:
1 on success, -1 on error

Definition at line 295 of file NSL01.cpp.

int get_PowerLimit_configuration ( void   )

Method to read the transmit power limit configuration parameters of NSL01 for different frequency sub-bands.

Returns:
1 on success, -1 on error

Definition at line 1376 of file NSL01.cpp.

int get_radio_stack_config ( void   )

Method to read the current radio stack configuration of NSL01 <=> main parameters for data transmission.

Returns:
1 on success, -1 on error

Definition at line 1130 of file NSL01.cpp.

int get_RTC_alarm ( void   )

Method to get the Real Time Clock (RTC) alarm info of NSL01.

Returns:
1 on success, -1 on error

Definition at line 465 of file NSL01.cpp.

int get_RTC_info ( void   )

Method to read the current Real Time Clock (RTC) value of NSL01.

Returns:
1 on success, -1 on error

Definition at line 323 of file NSL01.cpp.

int get_system_operation_mode ( void   )

Method to get the current system operation mode of NSL01.

Note:
Two system operation modes are supported:
  • Standard / Application Mode
  • Customer Mode
Some device functionality is only supported in customer mode!
Returns:
1 on success, -1 on error

Definition at line 527 of file NSL01.cpp.

int join_network ( void   )

Method to start the join network procedure of NSL01 in Over-the-Air Activation (OTTA) mode with previously defined parameters in 'set_join_parameter' method.

Note:
Once the 'join_network' method is triggered an internal event method is invoked periodically to indicate the joining procedure.
An internal join network indication event method is invoked after successful reception of a server join response packet or after the expiration of a complete join process without success (the join request will be retransmitted changing the spreading factor from SF7 till SF12, reusing each spreading factor twice).
Returns:
1 on success, -1 on error

Definition at line 817 of file NSL01.cpp.

int ping ( void   )

Method to ping NSL01.

Returns:
1 on success, -1 on error

Definition at line 146 of file NSL01.cpp.

int reset ( void   )

Method to reset NSL01 (software reset).

Note:
After executing this command the module will be restarted after approximately 200ms!
Returns:
1 on success, -1 on error

Definition at line 177 of file NSL01.cpp.

int send_Cdata ( UINT8  port,
UINT8 *  srcData,
int  srcLength 
)

Method to transmit data in a reliable way to the network server <=> confirmed data transmission.

Note:
An internal 'reliable data transmit indication' event method is invoked after the radio packet has been sent, containing information about the data transfer.
Parameters:
port: LoRaWAN Port number (> 0)
*srcData: Application Payload (data which have to be transmitted)
srcLength: Lenght of Application Payload data
Returns:
1 on success, -1 on error

Definition at line 915 of file NSL01.cpp.

int send_Udata ( UINT8  port,
UINT8 *  srcData,
int  srcLength 
)

Method to transmit data in an unreliable way to the network server <=> no acknowledgement will be sent from the network server and no retransmission method is available on the end-device (NSL01) side.

Note:
An internal 'unreliable data transmit indication' event method is invoked after the radio packet has been sent, containing information about the data transfer.
Parameters:
port: LoRaWAN Port number (> 0)
*srcData: Application Payload (data which have to be transmitted)
srcLength: Lenght of Application Payload data
Returns:
1 on success, -1 on error

Definition at line 855 of file NSL01.cpp.

int set_custom_configuration ( int  RF_gain_offset )

Method to configure the custom parameters (RF gain offset to compensate possible transmission losses/gains including circuit matching, antennas, ...).

The RF gain offset should be rated in units of dBd (decibels relative to a half-wavelength dipole antenna, where 0 dBd = 2.15 dBi).

Note:
This parameter can only be set in "customer mode"!
Parameters:
RF_gain_offset: RF gain offset in dBd
Returns:
1 on success, -1 on error

Definition at line 1272 of file NSL01.cpp.

int set_EUI ( UINT8 *  device_EUI )

Method to set/write the unique 64-bit device EUI.

Note:
The device EUI can only be set in "customer mode"!
Parameters:
*device_EUI: Unique 64-bit device EUI (UINT8 array)
Returns:
1 on success, -1 on error

Definition at line 1220 of file NSL01.cpp.

int set_join_parameter ( UINT8 *  appEUI,
UINT8 *  appKey 
)

Method to configure the Over-the-Air Activation (OTTA) parameters of NSL01 which are used during the join network procedure 'join_network'.

Parameters:
*appEUI: globally unique 64-Bit Application EUI
*appKey: device specific 128-Bit AES Application Key
Returns:
1 on success, -1 on error

Definition at line 755 of file NSL01.cpp.

int set_PowerLimit_configuration ( UINT8  sub_band,
UINT8  power_limit_flag,
UINT8  power_limit 
)

Method to set/configure the transmit power limit configuration parameters of NSL01 for a dedicated frequency sub-band.

Note:
These parameters can only be set in "customer mode"!
Parameters:
sub_band: Sub-band index [0...5] according to specification
power_limit_flag: Tx power limit flag for sub-band [enabled/disabled]
power_limit: Tx power limit for sub-band in dBm [0...16]
Returns:
1 on success, -1 on error

Definition at line 1411 of file NSL01.cpp.

int set_radio_stack_config ( Radio_config_struct  radio_stack )

Method to set/configure the internal radio stack configuration of NSL01 <=> main parameters for data transmission.

Parameters:
radio_stack: Radio stack config data defined in Radio_config_struct
Returns:
1 on success, -1 on error

Definition at line 969 of file NSL01.cpp.

int set_RTC ( RTC_struct  RTC_data )

Method to set the Real Time Clock (RTC) value of NSL01.

Parameters:
RTC_data: RTC data defined in RTC_struct
Returns:
1 on success, -1 on error

Definition at line 353 of file NSL01.cpp.

int set_RTC_alarm ( RTC_alarm_struct  RTC_alarm_data )

Method to set the Real Time Clock (RTC) alarm of NSL01.

Parameters:
RTC_alarm_data: RTC alarm defined in RTC_alarm_struct
Returns:
1 on success, -1 on error

Definition at line 399 of file NSL01.cpp.

int set_system_operation_mode ( UINT8  system_mode )

Method to set the system operation mode of NSL01.

Note:
After executing this command the module will be restarted after approximately 200ms!
Parameters:
system_mode0 : Standard/Application mode
system_mode1 : Reserved/Not used
system_mode2 : Reserved/Not used
system_mode3 : Customer mode
Returns:
1 on success, -1 on error

Definition at line 563 of file NSL01.cpp.


Field Documentation

Radio_config_struct Radio_config

Member variable for radio stack configuration based on global defined Radio_config_struct which contains:

  • UINT8 data_rate_index;
  • UINT8 Tx_power;
  • UINT8 adaptive_data_rate;
  • UINT8 duty_cycle_control;
  • UINT8 class_C_support;
  • UINT8 RF_packet_format;
  • UINT8 forwarding;
  • UINT8 power_saving;
  • UINT8 number_retransmissions;
  • UINT8 band_index;
  • UINT8 header_MAC_cmd_capacity;.

Definition at line 393 of file NSL01.h.

RTC_alarm_struct RTC_alarm

Member variable for Real Time Clock (RTC) alarm based on global defined RTC_alarm_struct which contains:

  • bool periodic
  • UINT8 hour
  • UINT8 minute
  • UINT8 second.

Definition at line 376 of file NSL01.h.

RTC_struct RTC_data

Member variable for Real Time Clock (RTC) information based on global defined RTC_struct which contains:

  • UINT16 year
  • UINT8 month
  • UINT8 day
  • UINT8 hour
  • UINT8 minute
  • UINT8 second.

Definition at line 366 of file NSL01.h.