Wirepas SDK
API

API is split into following areas:

Stack Libraries

The Wirepas Mesh stack (hereafter referred to as the stack) runs on ARM Cortex M based microcontrollers. Hence, the stack and the application both follow the Procedure Call Standard for the ARM Architecture. The stack and the application communicate with each other by calling functions on each other.

The protocol stack is in control of program execution. Application can request to be called periodically, or when certain events happen. Applications can also directly access hardware peripherals that are not used by the stack. Applications can have interrupt handlers, but the service routines must be kept short so they do not interfere with the timing of the Wirepas Mesh protocol.

To keep features in logically separate units, stack functions are collected into libraries. The application opens each library it needs and calls functions in the library via function pointers. A global list of functions is given to the application when it is first called, so that it can open libraries and find out details about the environment in which it is running.

The following table contains following information on libraries:

  • Name of the library
  • Library handle set by API_Open() function. Application can use this handle to access the services.
  • Short description of the library
Header fileHandleDescription
wms_advertiser.hlib_advertiser Application library for direct advertiser functionality
wms_app.hNAThe global macros, types and functions available to applications can be found in the wms_app.h header
wms_beacon_rx.hlib_beacon_rx Application library for Bluetooth LE beacon RX
wms_beacon_tx.hlib_beacon_tx Transmission of Bluetooth LE compatible beacons
wms_data.hlib_dataSending and receiving data packets
wms_hardware.hlib_hwSharing of hardware peripherals between stack and application
wms_joining.hlib_joiningWirepas Open Joining protocol
wms_memory_area.hlib_memory_area Access to non-volatile memory areas
wms_otap.hlib_otapThe Over-The-Air-Programming (OTAP) library
wms_radio_config.hlib_radio_config Application library for radio power and front end module control
wms_settings.hlib_settingsAccess to node settings, which are stored in nonvolatile memory
wms_sleep.hlib_sleepSleep Wirepas Mesh stack for time periods
wms_state.hlib_stateViewing and controlling stack runtime state
wms_storage.hlib_storageSmall Non-volatile storage area to use for application
wms_system.hlib_systemLow-level functions such as application scheduling, interrupt handling, critical sections and power management
wms_time.hlib_timeKeeping track of time and comparing timestamps
Note
Not all of the services are available in every platform!

Application and Library Versioning

To keep features in logically separate units and allow each unit to be updated in a backward- and forward-compatible manner, stack functions are collected into libraries. When an application requests a specific version of a library and no exact version is found, the stack can do one of three things:

  1. Return a newer, compatible library: This works if the newer library version has new features that have been added in such a way that the old API still works as expected. This is ideally the way new firmware releases add features to the libraries.
  2. Emulate the old library: If the new firmware has the library, but it has an incompatible API and application calls openLibrary() with an old version number. Then, stack returns an emulated version of the old library, which just calls functions in the new library.
  3. Fail to open the library: Old, obsoleted features can be phased out by simply failing to open a library that is too old. Stack firmware release notes will list the obsoleted libraries for each release. Then, the associated library handle will be NULL.

In addition of library versioning, applications also have an API version number, APP_API_VERSION, placed in their header. The SDK places the version number there to indicate which version of the low-level application API the application supports. If there is a mismatch between the low-level API versions of the stack and the application, the stack may choose to not run the application.

SDK Libraries

There are numerous services that are given as a source code as part of the SDK. They are for various purposes, like higher API level or application services implemented by Wirepas. They are only present in the generated binaries if they are used.

They are abstractions of single mcu api to ease the implementation. They are located in libraries folder.

Note
When a library is enabled, some single mcu api cannot be used anymore directly from application. It would result in undefined behavior. Those api are listed in each library init function description.

Following table, summarize these libraries:

NameDescription
app_persistentManaging persistent data area
dualmcuScheduling of multiple application tasks
local_provisioningLocal provisioning feature built on top of more generic provisioning library
positioningPositioning related logic for anchor and tags
provisioningProvisioning
schedulerScheduling of multiple application tasks
shared_dataHandling of data packets between different modules
shared_appconfigRegister for app config following Wirepas TLV format
shared_offlineManages the NRLS setting between different modules
stack_stateAllows module to start/stop stack and be notified when such event happens

Board definitions

This folder contains definitions for various boards. Board approach allows executing same application in different radio boards. Mainly, board definition define GPIO pins for various purposes, such as serial port pins, leds and buttons.

Each subdirectory name defines the name of the board used in the build process (see here for how to enable application to use specific board).

Especially, there are two template boards that contain the documentation of the board definitions, according to processor architecture:

Processor architectureFile

File description

EFR32board/efr32_template/board.h

Board definition

EFR32board/efr32_template/config.mk

Board Configuration

EFR32board/efr32_template/bootloader/early_init_efr32.c

Board DCDC configuration

nRF52board/nrf52_template/board.h

Board definition

nRF52board/nrf52_template/config.mkBoard Configuration

DCDC converter configuration

DCDC converter configuration is very important topic, especially if low energy consumption is desired. In following table, the configuration is summarized for all processor architectures.

Processor architectureDCDC enabled

DCDC disabled

EFR32Leave following code line commented in early_init_efr32.c:
//#define MCU_NO_DCDC

Uncomment the line in early_init_efr32.c

#define MCU_NO_DCDC

nRF52Uncomment line in board.h:
// The board supports DCDC
#define BOARD_SUPPORT_DCDC

Comment line in board.h:

// The board supports DCDC
//#define BOARD_SUPPORT_DCDC

Bootloader configuration

This folder contains configuration mechanisms for bootloader operations. By default, they are weak symbols implementing stub functions. THey can be overridden in the application, if desired.

Following files are present:

NameDescription
early_init.h Hooks called early during boot process
external_flash.h External flash operation

Low level hardware services (HAL)

This folder contain hardware-specific services.

This page contains following sections:

mcu/common Common MCU files

This folder contains common files for all hardware platforms.

This page contains following sections:

start.c

This file is present in all applications. It positions the application entry point at the correct place in memory and do basic initialization: it loads the initialized data from flash to RAM, sets the bss area to 0 in RAM, and calls the application initialization function defined in app.c.

It also manages compatibility with the stack to avoid issues when running an application built for an old stack to a newer stack. Running an application built with a SDK newer than the stack version is not allowed.

mcu/hal_api Low level hardware API

Second group of services is low level (HAL) hardware services. They contain the implementations of various hardware peripherals for various hardware platforms and boards.

Relevant services are located in mcu/hal_api folder. Services are following:

Note
Not all of the services are available in every platform!
Name (related to mcu/hal_api folder)Description
ds.hDeep sleep control module
radio.hRadio FEM (front-end module)
hal_api.hInitialization of HAL services
hw_delay.hHardware delay module
i2c.hSimple minimal I2C master driver
gpio.hGPIO functions
button.hButton functions
led.hLED functions
power.hEnabling of DCDC converter
spi.hSimple minimal SPI master driver
usart.hUSART block handling

mcu/<hardware>

These folders contain mcu specific files to ease and factorize application development. Header files (.h) from this folder can be included in applications directly.

Linker file

Linker files are located in mcu/<processor>/linker folder. Linker file is linker script. It ensures that the application is loadable in its dedicated area in Flash. Particularly, it sets the application entry point at the beginning of the area.

Note
Linker files named gcc_bl_*.ld are for bootloader and they should never be modified!

This page contains following sections:

Flash Memory

As described with more details in OTAP documentation, the application shares by default its flash memory area with the scratchpad area. There is no strict limit for the size of the application but if the application is too big, it will prevent the OTAP to store its scratchpad in the remaining free space.

The default maximum size for an application is 40kB to ensure the above statement but can be extended from linker script:

Example:

MEMORY
{
FLASH (rx) : ORIGIN = 0x00040000, LENGTH = 40K
...
}

RAM memory

RAM memory is configured in linker file. Value is fixed and should not be modified.

Utility and helper services

Thirs group of services is utility and helper functions. They are various, hardware-independent, functions solely to ease the implementation. They are located in util folder.

NameDescription
api.hGlobal API for Wirepas library services
crc.hImplementation of "bad CRC-16 CCITT" algorithm
doublebuffer.hManaging of double buffering
node_configuration.hHelper function to initially setup a node if not already configured. This configuration can be modified later with remote API.
pack.hLittle Endian bytes to native integers packing and unpacking
random.hRandom number generator
ringbuffer.hRing buffers
sl_list.hSingle Linked List
tlv.hEncoding/decoding of TLV (Type Length Value) format
util.hMiscellaneous helper functions