 |
Wirepas SDK
|
|
Wirepas SDK
|
API is split into following areas:
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:
| Header file | Handle | Description |
|---|---|---|
| wms_advertiser.h | lib_advertiser | Application library for direct advertiser functionality |
| wms_app.h | NA | The global macros, types and functions available to applications can be found in the wms_app.h header |
| wms_beacon_rx.h | lib_beacon_rx | Application library for Bluetooth LE beacon RX |
| wms_beacon_tx.h | lib_beacon_tx | Transmission of Bluetooth LE compatible beacons |
| wms_data.h | lib_data | Sending and receiving data packets |
| wms_hardware.h | lib_hw | Sharing of hardware peripherals between stack and application |
| wms_joining.h | lib_joining | Wirepas Open Joining protocol |
| wms_memory_area.h | lib_memory_area | Access to non-volatile memory areas |
| wms_otap.h | lib_otap | The Over-The-Air-Programming (OTAP) library |
| wms_radio_config.h | lib_radio_config | Application library for radio power and front end module control |
| wms_settings.h | lib_settings | Access to node settings, which are stored in nonvolatile memory |
| wms_sleep.h | lib_sleep | Sleep Wirepas Mesh stack for time periods |
| wms_state.h | lib_state | Viewing and controlling stack runtime state |
| wms_storage.h | lib_storage | Small Non-volatile storage area to use for application |
| wms_system.h | lib_system | Low-level functions such as application scheduling, interrupt handling, critical sections and power management |
| wms_time.h | lib_time | Keeping track of time and comparing timestamps |
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:
openLibrary() with an old version number. Then, stack returns an emulated version of the old library, which just calls functions in the new library.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.
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.
Following table, summarize these libraries:
| Name | Description |
|---|---|
| app_persistent | Managing persistent data area |
| dualmcu | Scheduling of multiple application tasks |
| local_provisioning | Local provisioning feature built on top of more generic provisioning library |
| positioning | Positioning related logic for anchor and tags |
| provisioning | Provisioning |
| scheduler | Scheduling of multiple application tasks |
| shared_data | Handling of data packets between different modules |
| shared_appconfig | Register for app config following Wirepas TLV format |
| shared_offline | Manages the NRLS setting between different modules |
| stack_state | Allows module to start/stop stack and be notified when such event happens |
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 architecture | File | File description |
|---|---|---|
| EFR32 | board/efr32_template/board.h | Board definition |
| EFR32 | board/efr32_template/config.mk | Board Configuration |
| EFR32 | board/efr32_template/bootloader/early_init_efr32.c | Board DCDC configuration |
| nRF52 | board/nrf52_template/board.h | Board definition |
| nRF52 | board/nrf52_template/config.mk | Board 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 architecture | DCDC enabled | DCDC disabled |
|---|---|---|
| EFR32 | Leave following code line commented in early_init_efr32.c: //#define MCU_NO_DCDC
| Uncomment the line in #define MCU_NO_DCDC
|
| nRF52 | Uncomment line in board.h: // The board supports DCDC
#define BOARD_SUPPORT_DCDC
| Comment line in // The board supports DCDC
//#define BOARD_SUPPORT_DCDC
|
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:
| Name | Description |
|---|---|
| early_init.h | Hooks called early during boot process |
| external_flash.h | External flash operation |
This folder contain hardware-specific services.
This page contains following sections:
This folder contains common files for all hardware platforms.
This page contains following sections:
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.
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:
| Name (related to mcu/hal_api folder) | Description |
|---|---|
| ds.h | Deep sleep control module |
| radio.h | Radio FEM (front-end module) |
| hal_api.h | Initialization of HAL services |
| hw_delay.h | Hardware delay module |
| i2c.h | Simple minimal I2C master driver |
| gpio.h | GPIO functions |
| button.h | Button functions |
| led.h | LED functions |
| power.h | Enabling of DCDC converter |
| spi.h | Simple minimal SPI master driver |
| usart.h | USART block handling |
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 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.
gcc_bl_*.ld are for bootloader and they should never be modified!This page contains following sections:
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:
RAM memory is configured in linker file. Value is fixed and should not be modified.
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.
| Name | Description |
|---|---|
| api.h | Global API for Wirepas library services |
| crc.h | Implementation of "bad CRC-16 CCITT" algorithm |
| doublebuffer.h | Managing of double buffering |
| node_configuration.h | Helper function to initially setup a node if not already configured. This configuration can be modified later with remote API. |
| pack.h | Little Endian bytes to native integers packing and unpacking |
| random.h | Random number generator |
| ringbuffer.h | Ring buffers |
| sl_list.h | Single Linked List |
| tlv.h | Encoding/decoding of TLV (Type Length Value) format |
| util.h | Miscellaneous helper functions |