Skip to content

Interfaces#

Four interfaces have to be considered: management interface, datagram and network interfaces, and layer-two adaptation interface.

Management interface#

The management interface is used to configure the lab.SCHC FullSDK at runtime, to provide some hardware resources (memory and timers) that have to be allocated by the execution environment, and to notify the application about information regarding the FullSDK ongoing state.

Object Management
Processing Power Whenever the SDK needs to perform processing, it signals it to the application layer that will call a dedicated function.
Timers Resolving a timer must be done in 1 ms. The execution environment must provide a callback that starts the time for n ms, and a callback that stops it. When the timeout is triggered, a dedicated function must be called.
Volatile memory (RAM) Lab.SCHC FullSDK is flexible in terms of memory management. The application must allocate, then provide memory to the SDK. The amount of memory required depends on both the MTU and the maximum payload the application expects to send and receive.
Ongoing state The connectivity state, i.e. whether layer 2 may send or receive data, is signaled to the application layer using a callback. The application layer should not request to send a packet before connectivity is reported as operational.

Info: All the callbacks are defined when initializing the layers.

Datagram interface#

The datagram interface is used to send data packets to a remote application, and to receive data packets from it.

In a way similar to a Berkeley datagram socket, the following operations have to be performed to send a packet:

  1. Initialize the interface (IPv6/v4).
  2. Create a socket.
  3. Bind it to a local port.
  4. Send a data packet to the remote application, using the socket as a context. The remote application is defined by its IPv6/v4 address and its port.

The send operation is non-blocking and asynchronous:

  • It requests a transmission operation and returns immediately.
  • The result of the transmission (success or failure) is received later, thanks to a callback declared at interface initialization.

Depending on the packet size and LPWAN technology, a send operation can be quite long. For instance, if the packet size is larger than the LPWAN maximum transmission unit (MTU), it will be fragmented and sent in several chunks. Furthermore, duty cycle limitation may increase the overall transmission time. Packet reception is also handled by a callback declared at interface initialization.

In the current version of the lab.SCHC FullSDK, a maximum of three sockets can be created by default. The number of available sockets can be changed at compilation time.

Network interface#

The network interface is used to send and receive raw IPv6/UDP data packets to and from a remote application.

The following operations have to be performed to send a packet: - Initialize interface configure network. - Information thanks to extension API - Send a raw IPv6/UDP data packet to the remote application

The send operation is non-blocking and asynchronous: - It requests a transmission operation and returns immediately - The result of the transmission (success or failure) is received later, thanks to a callback declared at initialization time

Depending on packet size and LPWAN technology, a send operation can be quite long. For instance, if packet size is larger than the LPWAN's maximum transmission unit (MTU), it will be fragmented and sent in several chunks. Furthermore, duty cycle limitation may increase overall transmission time.

Packet reception is handled by a callback declared at initialization time.

Layer-two adaptation interface#

The L2A layer allows the FullSDK to be independent of the layer two stack.

Since L2A layer does depend on the underlying LPWAN technology, it is usually provided by the integrator. It must comply with a predefined interface which stipulates the following elements:

  • A set of callbacks, defined at layer initialization time, that must be called for the following events:
    • the layer requires some processing.
    • a packet transmission has been done.
    • a packet has been received.
    • connectivity is available.
    • connectivity is unavailable (may be optional).
  • A function that must provide the L2 technology.
    • l2a_get_technology
  • A function that must provide the MTU for the next packet to be sent.
    • l2a_get_mtu
  • A function that must provide the time to wait before a new packet can be sent (for duty cycle handling).
    • l2a_get_next_tx_delay
  • A function that must request the transmission of a packet. It must be non-blocking, as the result is provided with the transmission_result callback.
    • l2a_send_data
  • A function that performs processing. It will be called after the callback signals that the layer requires some processing.
    • l2a_process
  • A function that must provide the device IID. Can return false if not implemented. This function is mandatory only to be compliant with RFC9011.
    • l2a_get_dev_iid

The transmission_result callback signalling the end of a packet transmission must be called only when the communication module / board can switch again to transmission mode (without taking into account possible duty cycle restrictions).

The function that provides the time to wait before a new packet can be sent will be called by the FullSDK as soon as the end of packet transmission has been signaled.

The current version of the lab.SCHC FullSDK provides a reference implementation of the L2A layer for the ST NUCLEO-L476RG microcontroller board and the SX1276MB1MAS LoRaWAN shield using Semtech LoRaMac-Node stack.