Skip to content

Management interface functions#

The header file for the Management interface is fullsdkmgt.h.

The management interface has two roles:

  • Configure the lab.SCHC FullSDK stack.
  • Provide the stack with resources required at execution time: processing time, memory and timers.

Note: The management interface functions must be used to configure the stack before any functions of any interface are called.

Initialization#

The first function that must be called is mgt_initialize().

This function must be provided with:

  • A list of callbacks
  • A pointer to a memory block
  • The maximum MTU size
  • The maximum payload size

List of Callbacks#

Each callback will be called for a specific event.

Callback Event
mgt_processing_required Informs the application that one of the layers in the FullSDK stack has to perform some processing. The application must call the mgt_process() function as soon as possible but not from within the callback.
mgt_connectivity_state Informs the application about any modification of the connectivity state. The application should not try to send a message until connectivity is available.
mgt_start_timer Informs the application that a timer should be started. Timer period and ID are specified by the callback parameters. When the timer period expires, the mgt_timer_timeout() function must be called with the same ID used for the start timer.
mgt_stop_timer Informs the application that a timer must be stopped. Timer ID is specified by the callback parameter.
mgt_sync_bootstrap_result (optional) Informs the application about the result of the synchronization with the SCHC gateway. This callback is triggered when a response is received following a call to mgt_sync_boostrap(). Note that synchronization is an extended feature of lab.SCHC FullSDK. This callback can be omitted (i.e. set to NULL) when Sync is not used or when the SCHC gateway does not support it.

Memory block pointer#

The initialization function must be provided with a pointer to a memory block allocated for the stack and the size of the memory block.

The application that integrates Lab.SCHC FullSDK stack has to allocate some memory (based on a formula, see below) from the volatile memory of the execution environment, and then provide it to the stack.

The formula is the following:

(4 * (max_mtu_size + max_app_payload_len + max_proto_size))

where:

  • max_mtu_size is the maximum MTU size of the L2 technology used;
  • max_app_payload_len is the maximum payload length that the application expects to send and receive;
  • max_proto_size is predefined as MGT_PROTO_SIZE in fullsdkmgt.h.

Maximum sizes#

Finally, the initialization function must be completed with:

  • The maximum MTU size of the L2 technology used;
  • The maximum payload size that the application expects to send and receive.

Synchronization bootstrap#

This function is used to synchronize the SDK with the SCHC gateway. It is optional, and only compatible with Actility's SCHC IPCore.

mgt_sync_bootstrap() must be provided with the following parameters:

  • retransmission_delay: The delay (in ms) between each request retransmission.
  • max_retrans: The maximum number of request retransmission before considering that the synchronization has failed.

Processing#

This section refers to the FullSDK paradigm.

Every time a layer of the FullSDK stack needs to perform a processing as the result of some event, the mgt_processing_required callback is called.

It is then up to the application to call the mgt_process() function as soon as possible, but not from within the callback. In fact, a callback called by the lab.SCHC FullSDK must not call any lab.SCHC FullSDK function.

Polling#

While using L2 technology having quasi-bidirectional links, which is the case with LoRaWAN in class A, polling packets must be send in order to trigger downlink packet reception.

Two functions are dedicated for that purpose:

  • mgt_enable_polling() function must be called once after mgt_initialize() to activate implicit polling mechanism inside the lab.SCHC FullSDK stack. The aim being to retrieve the downlink packets, in particular when they are fragmented.
  • mgt_trigger_polling() function must be called every time the application wants to trigger explicitly a polling frame. The aim being to generate a downlink possibility (fport: 0 with no payload for LoRaWAN, etc.).

These functions have no use for Class C and the Class B is not supported.

Version#

The mgt_get_version() function returns the version of the FullSDK library as a null-terminated string.

Extension of the Management interface#

The header file for the extension of the Management interface is fullsdkextapi.h, located in full-sdk/api/<api>, depending on the application API.

The extension API provisions SCHC compression and fragmentation rules in binary format.

Header rules#

This function should be called only when the FullSDK library is compiled using dynamic rule loading.

The mgt_provision_header_rules() function provisions the header rules, and considers the following parameters:

  • bin_rules: SCHC rules in binary format.
  • bin_rules_len: The length of bin_rules, in bytes.
  • memory: A memory area or buffer that can be used by the parser.
  • memory_len: The length in bytes of the memory area.

Payload rules#

The mgt_provision_payload_rules() function provisions payload pattern rules in a binary format. The following parameters must be provided:

  • bin_rules: Payload pattern rules in a binary format.
  • bin_rules_len: The length of bin_rules, in bytes.
  • memory: A memory area or buffer that can be used by the parser.
  • memory_len: The length of the memory area.

Fragmentation rules#

The mgt_provision_frag_profile() function provisions the fragmentation rule for a single direction. In order to set a specific fragmentation profile for both directions (uplink and downlink), this function must be called twice with the selected rules.

The function must be provided with the following parameters:

  • buffer: Fragmentation rule in a binary format.
  • size: The length of the fragmentation rule, in bytes.

Template parameters#

Template parameters can be set with mgt_set_template_param() using the following parameters:

  • index: 0-based index corresponding to the template parameters to set.
  • value: The value to associate to the index.
  • size: The size of the given value in bytes.

Template parameters can also be retrieved using the mgt_get_template_param() function by providing the corresponding parameter index in the template.

Other functions related to templates include:

  • mgt_get_nb_template_params(): gives the number of configurable parameters in the provided template.
  • mgt_get_template_id(): retrieves the template ID of the current template.
  • mgt_reset_template_params(): clears the template parameters in the memory.

Refer to the fullsdkextapi.h header files for more details.