FullSDK Usage

This section describes the logic of initializing, configuring, and using the lab.SCHC FullSDK in different scenarios.

Role

The role of lab.SCHC FullSDK is to enable the SCHC compression and fragmentation mechanisms on device side, either by being fully embedded into an AT modem application that receives messages from an UDP client, or by being deployed on the device directly.

Layer integration

Lab.SCHC FullSDK integrates with both the underlying LPWAN technology and the upper application layer.

The configuration of lab.SCHC FullSDK at runtime, the exchange of packets or the adaptation with the Level2 layer are tasks assumed by interfaces, each provided in a dedicated header file.

Paradigm

One major structuring requirement for the lab.SCHC FullSDK is the ability to support low power modes. Consequently, its implementation allows it to be fully integrated in an event-driven environment.

1. When an event concerning the lab.SCHC FullSDK occurs (e.g. data reception, timeout, etc.), the application layer is informed by a callback.
2. Then, the application decides whether to let the Acklio FullSDK process the event or not. If yes, it calls a dedicated function.
3. Once an event has been processed (the dedicated function has returned), the lab.SCHC FullSDK does not perform any additional processing.

Sequence diagrams

The following sequence diagrams present some use cases.

Interface initialization and configuration

The above diagram presents the successive function calls that must be performed by the application layer to initialize and configure the interface that will be used, and resulting callbacks that will be called by the lab.SCHC FullSDK for related events.

In step 1, the application initializes the management layer and related interface. See the reference manual for details on the initialization of the datagram interface.

As soon as the management layer has been initialized, the callback signaling that the FullSDK needs some processing may be called. In response to this callback, the application layer must call the management layer function that will perform this processing. Step 2 presents one such dialog for this use case. More may occur.

The callback requesting processing is called in an interruption context. The processing function must not be called from this callback, as its execution may take some time. Consequently, the application layer has to decouple the call to the processing function from the activation of the callback. See the reference manual for more information.

In step 3, the SDK signals that the LPWAN connectivity is available. For instance, for a LoRaWAN network, this means that the Join procedure has been successfully performed.

The application layer has to wait for connectivity before interacting with an interface. In step 4, the interface is configured. See the reference manual for the configuration of the datagram interface.

Packet transmission with fragmentation

The above diagram presents the calls for the transmission of a packet involving SCHC fragmentation.

In step 1, the application layer requests the transmission of a packet.

In step 2, the lab.SCHC FullSDK signals that it needs some processing and the application layer calls the associated processing function. This interaction will happen several times.

The fragmentation procedure requires some timers. In step 3, the FullSDK signals that the execution environment must start a timer with id=1. This timer must have been created by the application layer beforehand. The timer duration is provided by a parameter of the callback. The timer must have been associated with the SDK function that must be called when the timer expires (timeout event).

In step 4, the timeout occurs. The timeout function associated with the timer must call the corresponding SDK timeout function, as explained above.

The timeout function may be called in an interrupt context. Later on, the timer must be started again.

In step 5, the SDK requires to stop timer id=1.

In step 6, the result of the transmission is returned. In this use case, if this result is positive, this means that the fragmentation process went well and that the packet has been transmitted successfully.

Packet reception without fragmentation

The diagram above presents the calls for the reception of a packet, without SCHC fragmentation.

In step 1, there is the usual request for processing. Again, even if it is presented only once on the diagram, it may occur several times.

In step 2, the application layer is provided with the received packet. The callback should save the received data to a safe place and should then return as soon as possible.

If fragmentation had been active, the timer functions would have been called as it is shown in the previous section.

L2A layer initialization and transmission handling

The following sequence diagram presents the initialization of the L2A layer:

In step 1, the FullSDK calls the initialization function.

In step 2, the L2A layer signals to the FullSDK that it needs to perform some processing. In response to this request, the SDK calls the function performing processing. The L2A layer may perform the number of calls of the callback requesting processing it requires.

In step 3, the L2A layer signals that connectivity is available. For instance, for a LoRaWAN layer two, this means that the Join procedure was successful. The FullSDK will not try to use L2A layer for transmission or reception as long as the callback informing about connectivity availability has not been called.

The following sequence diagram presents the handling of a transmission request:

In step 1, the FullSDK asks for the MTU that will be used in the next transmission. This request allows the SDK to support L2 technologies with variable MTU (e.g. LoRaWAN).

In step 2, the FullSDK requests the packet transmission. Soon afterward, the layer two will start transmitting the packet.

In step 3, when required, the L2A layer performs the usual request for processing. Even if it is presented only once on the diagram, it may occur several times.

In step 4, the layer two is back to idle state, ready to transmit again, unless there are duty cycle restrictions. L2A has to signal this event to the lab.SCHC FullSDK by calling the transmission result callback.

In step 5, the lab.SCHC FullSDK requests the time that it has to wait before requesting a new transmission. This request allows the FullSDK to support L2 technologies with duty cycle restrictions.

Bare metal projects

In a bare metal project, where lowering power consumption is important, the application architecture is usually similar to this one, based on a main loop:

After initialization, the main loop usually enters sleep mode. It exits from sleep mode when an interrupt occurs. Each interrupt service routine signals to the main loop that an event occured, and that some processing is required. It is then up to the main loop to call the function that performs such processing. Once required processing has been done, the main loop enters sleep mode again. The Acklio FullSDK can easily be integrated in such an architecture. The callback called by the Acklio FullSDK to signal that some processing has to be done can set a flag. This flag is checked by the main loop every time it has exited sleep mode. If the flag is set, the main loop calls the associated processing function.

RTOS projects

In an RTOS project, the developer can rely on the various features provided by the RTOS: threads, semaphores, etc.

In such a project, the lab.SCHC SDK would run in one thread. This thread would wait on a semaphore (for instance). The implementation of the callback requesting processing would give the semaphore.