Mistake on this page?
Report an issue in GitHub or email us
Public Member Functions
LoRaWANStack Class Reference

LoRaWANStack Class A controller layer for LoRaWAN MAC and PHY. More...

#include <LoRaWANStack.h>

Inheritance diagram for LoRaWANStack:
NonCopyable< LoRaWANStack >

Public Member Functions

void bind_phy_and_radio_driver (LoRaRadio &radio, LoRaPHY &phy)
 Binds PHY layer and radio driver to stack. More...
 
lorawan_status_t initialize_mac_layer (events::EventQueue *queue)
 End device initialization. More...
 
lorawan_status_t set_lora_callbacks (const lorawan_app_callbacks_t *callbacks)
 Sets all callbacks for the application. More...
 
lorawan_status_t connect ()
 Connect OTAA or ABP using Mbed-OS config system. More...
 
lorawan_status_t connect (const lorawan_connect_t &connect)
 Connect OTAA or ABP with parameters. More...
 
lorawan_status_t add_channels (const lorawan_channelplan_t &channel_plan)
 Adds channels to use. More...
 
lorawan_status_t remove_a_channel (uint8_t channel_id)
 Removes a channel from the list. More...
 
lorawan_status_t drop_channel_list ()
 Removes a previously set channel plan. More...
 
lorawan_status_t get_enabled_channels (lorawan_channelplan_t &channel_plan)
 Gets a list of currently enabled channels . More...
 
lorawan_status_t set_confirmed_msg_retry (uint8_t count)
 Sets up a retry counter for confirmed messages. More...
 
lorawan_status_t set_channel_data_rate (uint8_t data_rate)
 Sets up the data rate. More...
 
lorawan_status_t enable_adaptive_datarate (bool adr_enabled)
 Enables ADR. More...
 
int16_t handle_tx (uint8_t port, const uint8_t *data, uint16_t length, uint8_t flags, bool null_allowed=false, bool allow_port_0=false)
 Send message to gateway. More...
 
int16_t handle_rx (uint8_t *data, uint16_t length, uint8_t &port, int &flags, bool validate_params)
 Receives a message from the Network Server. More...
 
lorawan_status_t set_link_check_request ()
 Send Link Check Request MAC command. More...
 
void remove_link_check_request ()
 Removes link check request sticky MAC command. More...
 
lorawan_status_t shutdown ()
 Shuts down the LoRaWAN protocol. More...
 
lorawan_status_t set_device_class (const device_class_t &device_class)
 Change device class. More...
 
lorawan_status_t acquire_tx_metadata (lorawan_tx_metadata &metadata)
 Acquire TX meta-data. More...
 
lorawan_status_t acquire_rx_metadata (lorawan_rx_metadata &metadata)
 Acquire RX meta-data. More...
 
lorawan_status_t acquire_backoff_metadata (int &backoff)
 Acquire backoff meta-data. More...
 
lorawan_status_t stop_sending (void)
 Stops sending. More...
 

Detailed Description

LoRaWANStack Class A controller layer for LoRaWAN MAC and PHY.

Definition at line 60 of file LoRaWANStack.h.

Member Function Documentation

lorawan_status_t acquire_backoff_metadata ( int &  backoff)

Acquire backoff meta-data.

Get hold of backoff time after which the transmission will take place.

Parameters
backoffA reference to the inbound integer which will be filled with any backoff meta-data if available.
Returns
LORAWAN_STATUS_OK if successful, LORAWAN_STATUS_METADATA_NOT_AVAILABLE otherwise
lorawan_status_t acquire_rx_metadata ( lorawan_rx_metadata metadata)

Acquire RX meta-data.

Upon successful reception, RX meta-data will be made available

Parameters
metadataA reference to the inbound structure which will be filled with any RX meta-data if available.
Returns
LORAWAN_STATUS_OK if successful, LORAWAN_STATUS_METADATA_NOT_AVAILABLE otherwise
lorawan_status_t acquire_tx_metadata ( lorawan_tx_metadata metadata)

Acquire TX meta-data.

Upon successful transmission, TX meta-data will be made available

Parameters
metadataA reference to the inbound structure which will be filled with any TX meta-data if available.
Returns
LORAWAN_STATUS_OK if successful, LORAWAN_STATUS_METADATA_NOT_AVAILABLE otherwise
lorawan_status_t add_channels ( const lorawan_channelplan_t channel_plan)

Adds channels to use.

You can provide a list of channels with appropriate parameters filled in. However, this list is not absolute. In some regions, a CF list gets implemented by default, which means that the network can overwrite your channel frequency settings right after receiving a Join Accept. You may try to set up any channel or channels after that and if the channel requested is already active, the request is silently ignored. A negative error code is returned if there is any problem with parameters.

You need to ensure that the base station nearby supports the channel or channels being added.

If your list includes a default channel (a channel where Join Requests are received) you cannot fully configure the channel parameters. Either leave the channel settings to default or check your corresponding PHY layer implementation. For example, LoRaPHYE868.

Parameters
channel_planA list of channels or a single channel.
Returns
LORAWAN_STATUS_OK on success, a negative error code on failure.
void bind_phy_and_radio_driver ( LoRaRadio radio,
LoRaPHY phy 
)

Binds PHY layer and radio driver to stack.

MAC layer is totally detached from the PHY layer so the stack layer needs to play the role of an arbitrator. This API sets the PHY layer object to stack and bind the radio driver object from the application to the PHY layer. Also initialises radio callback handles which the radio driver will use in order to report events.

Parameters
radioLoRaRadio object, i.e., the radio driver
phyLoRaPHY object.
lorawan_status_t connect ( )

Connect OTAA or ABP using Mbed-OS config system.

Returns
For ABP: If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by a 'CONNECTED' event. Otherwise a negative error code is returned. Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.

For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned for the first call. Any subsequent call will return either LORAWAN_STATUS_BUSY (if the previous request for connection is still underway) or LORAWAN_STATUS_ALREADY_CONNECTED (if a network was already joined successfully). A 'CONNECTED' event is sent to the application when the JoinAccept is received.

lorawan_status_t connect ( const lorawan_connect_t connect)

Connect OTAA or ABP with parameters.

Parameters
connectOptions for an end device connection to the gateway.
Returns
For ABP: If everything goes well, LORAWAN_STATUS_OK is returned for first call followed by a 'CONNECTED' event. Otherwise a negative error code is returned. Any subsequent call will return LORAWAN_STATUS_ALREADY_CONNECTED and no event follows.

For OTAA: When a JoinRequest is sent, LORAWAN_STATUS_CONNECT_IN_PROGRESS is returned for the first call. Any subsequent call will return either LORAWAN_STATUS_BUSY (if the previous request for connection is still underway) or LORAWAN_STATUS_ALREADY_CONNECTED (if a network was already joined successfully). A 'CONNECTED' event is sent to the application when the JoinAccept is received.

lorawan_status_t drop_channel_list ( )

Removes a previously set channel plan.

Returns
LORAWAN_STATUS_OK on success, a negative error code on failure.
lorawan_status_t enable_adaptive_datarate ( bool  adr_enabled)

Enables ADR.

Parameters
adr_enabled0 ADR disabled, 1 ADR enabled.
Returns
LORAWAN_STATUS_OK on success, a negative error code on failure.
lorawan_status_t get_enabled_channels ( lorawan_channelplan_t channel_plan)

Gets a list of currently enabled channels .

Parameters
channel_planThe channel plan structure to store final result.
Returns
LORAWAN_STATUS_OK on success, a negative error code on failure.
int16_t handle_rx ( uint8_t *  data,
uint16_t  length,
uint8_t &  port,
int &  flags,
bool  validate_params 
)

Receives a message from the Network Server.

Parameters
dataA pointer to buffer where the received data will be stored.
lengthThe size of data in bytes
portThe application port number. Port numbers 0 and 224 are reserved, whereas port numbers from 1 to 223 (0x01 to 0xDF) are valid port numbers. Anything out of this range is illegal.

In return will contain the number of port to which message was received.

Parameters
flagsA flag is used to determine what type of message is being received, for example:

MSG_UNCONFIRMED_FLAG = 0x01, MSG_CONFIRMED_FLAG = 0x02 MSG_MULTICAST_FLAG = 0x04, MSG_PROPRIETARY_FLAG = 0x08

MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be used in conjunction with MSG_UNCONFIRMED_FLAG and MSG_CONFIRMED_FLAG depending on the intended use.

MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set a confirmed message flag for a proprietary message.

MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are not mutually exclusive, i.e., the user can subscribe to receive both CONFIRMED AND UNCONFIRMED messages at the same time.

In return will contain the flags to determine what kind of message was received.

Parameters
validate_paramsIf set to true, the given port and flags values will be checked against the values received with the message. If values do not match, LORAWAN_STATUS_WOULD_BLOCK will be returned.
Returns
It could be one of these: i) 0 if there is nothing else to read. ii) Number of bytes written to user buffer. iii) LORAWAN_STATUS_WOULD_BLOCK if there is nothing available to read at the moment. iv) A negative error code on failure.
int16_t handle_tx ( uint8_t  port,
const uint8_t *  data,
uint16_t  length,
uint8_t  flags,
bool  null_allowed = false,
bool  allow_port_0 = false 
)

Send message to gateway.

Parameters
portThe application port number. Port numbers 0 and 224 are reserved, whereas port numbers from 1 to 223 (0x01 to 0xDF) are valid port numbers. Anything out of this range is illegal.
dataA pointer to the data being sent. The ownership of the buffer is not transferred. The data is copied to the internal buffers.
lengthThe size of data in bytes.
flagsA flag used to determine what type of message is being sent, for example:

MSG_UNCONFIRMED_FLAG = 0x01 MSG_CONFIRMED_FLAG = 0x02 MSG_MULTICAST_FLAG = 0x04 MSG_PROPRIETARY_FLAG = 0x08 MSG_MULTICAST_FLAG and MSG_PROPRIETARY_FLAG can be used in conjunction with MSG_UNCONFIRMED_FLAG and MSG_CONFIRMED_FLAG depending on the intended use.

MSG_PROPRIETARY_FLAG|MSG_CONFIRMED_FLAG mask will set a confirmed message flag for a proprietary message. MSG_CONFIRMED_FLAG and MSG_UNCONFIRMED_FLAG are mutually exclusive.

Parameters
null_allowedInternal use only. Needed for sending empty packet having CONFIRMED bit on.
allow_port_0Internal use only. Needed for flushing MAC commands.
Returns
The number of bytes sent, or LORAWAN_STATUS_WOULD_BLOCK if another TX is ongoing, or a negative error code on failure.
lorawan_status_t initialize_mac_layer ( events::EventQueue queue)

End device initialization.

Parameters
queueA pointer to an EventQueue passed from the application.
Returns
LORAWAN_STATUS_OK on success, a negative error code on failure.
lorawan_status_t remove_a_channel ( uint8_t  channel_id)

Removes a channel from the list.

Parameters
channel_idIndex of the channel being removed
Returns
LORAWAN_STATUS_OK on success, a negative error code on failure.
void remove_link_check_request ( )

Removes link check request sticky MAC command.

Any already queued request may still get entertained. However, no new requests will be made.

lorawan_status_t set_channel_data_rate ( uint8_t  data_rate)

Sets up the data rate.

set_datarate() first verifies whether the data rate given is valid or not. If it is valid, the system sets the given data rate to the channel.

Parameters
data_rateThe intended data rate, for example DR_0 or DR_1. Note that the macro DR_* can mean different things in different regions.
Returns
LORAWAN_STATUS_OK if everything goes well, otherwise a negative error code.
lorawan_status_t set_confirmed_msg_retry ( uint8_t  count)

Sets up a retry counter for confirmed messages.

Valid only for confirmed messages. This API sets the number of times the stack will retry a CONFIRMED message before giving up and reporting an error.

Parameters
countThe number of retries for confirmed messages.
Returns
LORAWAN_STATUS_OK or a negative error code.
lorawan_status_t set_device_class ( const device_class_t device_class)

Change device class.

Change current device class.

Parameters
device_classThe device class
Returns
LORAWAN_STATUS_OK on success, LORAWAN_STATUS_UNSUPPORTED is requested class is not supported, or other negative error code if request failed.
lorawan_status_t set_link_check_request ( )

Send Link Check Request MAC command.

This API schedules a Link Check Request command (LinkCheckReq) for the network server and once the response, i.e., LinkCheckAns MAC command is received from the Network Server, an event is generated.

A callback function for the link check response must be set prior to using this API, otherwise a LORAWAN_STATUS_PARAMETER_INVALID error is thrown.

Returns
LORAWAN_STATUS_OK on successfully queuing a request, or a negative error code on failure.
lorawan_status_t set_lora_callbacks ( const lorawan_app_callbacks_t callbacks)

Sets all callbacks for the application.

Parameters
callbacksA pointer to the structure carrying callbacks.
Returns
LORAWAN_STATUS_OK on success, a negative error code on failure.
lorawan_status_t shutdown ( )

Shuts down the LoRaWAN protocol.

In response to the user call for disconnection, the stack shuts down itself.

Returns
LORAWAN_STATUS_DEVICE_OFF on successfully shutdown.
lorawan_status_t stop_sending ( void  )

Stops sending.

Stop sending any outstanding messages if they are not yet queued for transmission, i.e., if the backoff timer is nhot elapsed yet.

Returns
LORAWAN_STATUS_OK if the transmission is cancelled. LORAWAN_STATUS_BUSY otherwise.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.