L2A Interface Functions

info

Acklio FullSDK provides a reference implementation of the L2A layer based on LoRaWAN technology.

The targets of the L2A reference implementation are either ST NUCLEO-L476RG microcontroller board or ST NUCLEO-WL55JC microcontroller board, both with the SX1276MB1MAS LoRaWAN shield and running Semtech 4.4.7 LoRa stack, in class A (or class C).

The header file for the L2A interface is fullsdkl2a.h.

The layer-two adaptation interface (also called L2A) is required to bind the Acklio FullSDK with the L2 stack (LoRa, etc).

Integration

The L2A layer is usually provided by the integrator who has to implement the list of functions available in the fullsdkl2a.h header file.

Note that these functions are only called by the Acklio FullSDK and must not be called directly from the application code.

See

The L2 AT Commands page for information on error messages.

Initialize

When the application calls the mgt_initialize() function (initialization by the Management interface), the l2a_initialize() function is implicitly called by Acklio FullSDK.

This function can be used by the integrator to initialize the L2 stack and to store the callback functions provided as parameters:

Callback Parameter	Description
l2a_processing_required	To be called by the integrator to inform the Acklio FullSDK when an asynchronous task needs to be handled by the layer. See l2a_process() function below for more details.
l2a_transmission_result	To be called by the integrator to inform the Acklio FullSDK when the uplink packet has been transmitted (with or without success) by the L2 stack.
l2a_data_received	To be called by the integrator to inform the Acklio FullSDK when a downlink packet is received from the L2 stack.
l2a_connectivity_lost	To be called by the integrator to inform the Acklio FullSDK when the L2 connectivity is lost.
l2a_connectivity_available	To be called by the integrator to inform the Acklio FullSDK when the L2 connectivity is available. For example, with LoRa it corresponds to the Join Accept reception.

l2a_initialize() returns a status code indicating whether the initialization is successful or not.

L2 Technology

Acklio FullSDK calls the l2a_get_technology() function to get information on the L2 stack used by the integrator.
The following technology profiles are supported:

Technology Profile	Description
L2A_DEFAULT	Recommended technology profile for LoRa with class C
L2A_DEFAULT_CLASS_A	Recommended technology profile for LoRa with class A
L2A_LORA	Technology profile described in RFC 9011
L2A_SIGFOX	Technology profile for Sigfox

Sending Data

Acklio FullSDK calls the l2a_send_data() function to transmit a packet to the L2 stack.
This function provides two parameters:

• The buffer containing the packet to be transmitted
• The size of the packet

Packet Transmission

The integrator should handle the transmission of the packet to the L2 stack.

When the size of the packet is set to 1 and the value is 0x00 in hexadecimal, the integrator must send an empty frame (see Polling in the Management interface functions).

MTU Size

Acklio FullSDK calls the l2a_get_mtu() function to get information on the maximum packet size (in bytes) that can be transmitted by the L2 stack.

Acklio FullSDK calls this function from time to time because the MTU may change. For example, with a LoRa L2 stack, the MTU may change when ADR is enabled according to the radio conditions.

It is up to the integrator to retrieve this value from the L2 stack.

Device IID

Acklio FullSDK calls the l2a_get_dev_iid() function when the IPv6 address of the device is derived from L2 stack information.

It is used for LoRaWAN technology and can be implemented according to the formula referenced in RFC 9011 (section 5.3).
For other technologies, it must be returned false.

Next Transmission Delay

Acklio FullSDK calls the l2a_get_next_tx_delay() function to get information on the next uplink transmission slot (in ms) according to the L2 stack type and its configuration.

The next uplink packet transmitted by Acklio FullSDK using l2a_send_data() (see above) will be based on this delay.

For example, with a LoRa L2 stack, there is duty cycle limitation to follow before emitting over the radio.

L2 Processing

Acklio FullSDK calls the l2a_process() function every time l2a_processing_required callback (see above) is called by the integrator.

This function is used to handle asynchronous events received from the L2 stack. Call the following callbacks inside l2a_process() :

Direction	Callback	Description
Uplink	l2a_transmission_result	When the event corresponding to the end of the transmission of an uplink packet is received from the L2 stack.
Downlink	l2a_data_received	When the event corresponding to the reception of a downlink packet is received from the L2 stack.

Handle in the same way any other asynchronous event (timer, etc.) that might need to be implemented by the integrator and can be processed here.