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

#include <LoRaWANStack.h>

Inheritance diagram for 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

◆ bind_phy_and_radio_driver()

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

radio	LoRaRadio object, i.e., the radio driver
phy	LoRaPHY object.

◆ initialize_mac_layer()

lorawan_status_t initialize_mac_layer ( events::EventQueue * queue )

End device initialization.

Parameters

queue A pointer to an EventQueue passed from the application.

Returns: LORAWAN_STATUS_OK on success, a negative error code on failure.

◆ set_lora_callbacks()

lorawan_status_t set_lora_callbacks ( const lorawan_app_callbacks_t * callbacks )

Sets all callbacks for the application.

Parameters

callbacks A pointer to the structure carrying callbacks.

Returns: LORAWAN_STATUS_OK on success, a negative error code on failure.

◆ connect() [1/2]

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.

◆ connect() [2/2]

lorawan_status_t connect ( const lorawan_connect_t & connect )

Connect OTAA or ABP with parameters.

Parameters

connect Options 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.

◆ add_channels()

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_plan A list of channels or a single channel.

Returns: LORAWAN_STATUS_OK on success, a negative error code on failure.

◆ remove_a_channel()

lorawan_status_t remove_a_channel ( uint8_t channel_id )

Removes a channel from the list.

Parameters

channel_id Index of the channel being removed

Returns: LORAWAN_STATUS_OK on success, a negative error code on failure.

◆ drop_channel_list()

lorawan_status_t drop_channel_list ( )

Removes a previously set channel plan.

Returns: LORAWAN_STATUS_OK on success, a negative error code on failure.

◆ get_enabled_channels()

lorawan_status_t get_enabled_channels ( lorawan_channelplan_t & channel_plan )

Gets a list of currently enabled channels .

Parameters

channel_plan The channel plan structure to store final result.

Returns: LORAWAN_STATUS_OK on success, a negative error code on failure.

◆ set_confirmed_msg_retry()

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

count The number of retries for confirmed messages.

Returns: LORAWAN_STATUS_OK or a negative error code.

◆ set_channel_data_rate()

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_rate The 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.

◆ enable_adaptive_datarate()

lorawan_status_t enable_adaptive_datarate ( bool adr_enabled )

Enables ADR.

Parameters

adr_enabled 0 ADR disabled, 1 ADR enabled.

Returns: LORAWAN_STATUS_OK on success, a negative error code on failure.

◆ handle_tx()

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

port	The 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.
data	A pointer to the data being sent. The ownership of the buffer is not transferred. The data is copied to the internal buffers.
length	The size of data in bytes.
flags	A 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_allowed	Internal use only. Needed for sending empty packet having CONFIRMED bit on.
allow_port_0	Internal 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.

◆ handle_rx()

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

data	A pointer to buffer where the received data will be stored.
length	The size of data in bytes
port	The 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

flags A 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_params If 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.

◆ set_link_check_request()

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.

◆ remove_link_check_request()

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.

◆ shutdown()

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.

◆ set_device_class()

lorawan_status_t set_device_class ( const device_class_t & device_class )

Change device class.

Change current device class.

Parameters

device_class The 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.

◆ acquire_tx_metadata()

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

metadata A 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

◆ acquire_rx_metadata()

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

metadata A 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

◆ acquire_backoff_metadata()

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

backoff A 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

◆ stop_sending()

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.

Public Member Functions

Detailed Description

Member Function Documentation

◆ bind_phy_and_radio_driver()

◆ initialize_mac_layer()

◆ set_lora_callbacks()

◆ connect() [1/2]

◆ connect() [2/2]

◆ add_channels()

◆ remove_a_channel()

◆ drop_channel_list()

◆ get_enabled_channels()

◆ set_confirmed_msg_retry()

◆ set_channel_data_rate()

◆ enable_adaptive_datarate()

◆ handle_tx()

◆ handle_rx()

◆ set_link_check_request()

◆ remove_link_check_request()

◆ shutdown()

◆ set_device_class()

◆ acquire_tx_metadata()

◆ acquire_rx_metadata()

◆ acquire_backoff_metadata()

◆ stop_sending()