Wirepas SDK
Application Examples and Tools

Application examples

Applications exist in source/ subfolders, named after application name. Note that not all applications exist for every processor architecture.

Applications are categorized into two categories:

  • Example applications which can be used as a template for own application development. They are simple applications targeted to specific use case. They also include unitary apps.
  • Demos and production apps. They are applications that are dedicated to specific purpose. Compared to example applications, they are relatively complex and mainly to be used as such.

Example and unitary applications are:

Application nameDescription

Notes

battery_voltage_read_app Battery voltage reading demo app

ble_scanner How to receive BLE beacons

Only 2.4GHz devices

control_node To be used with control_router, switch in lighting example

control_router To be used with control_node, lighting fixture

custom_app Simple data transmission and reception

evaluation_app Wirepas Massive discovery application

inventory_app_router Inventory application using directed-advertiser for headnodes

inventory_app_tag Inventory application using directed-advertiser for advertisers

low_latency_app Low-latency mode demonstration app

minimal_app Minimal app that just starts the stack

ruuvi_evk Send sensor data

Only Ruuvitag

aes Test software AES library

app_persistent App persistent feature demo

appconfig Receiving application configuration

basic_interrupt How to use interrupt service

Only Nordic nRF52xx

ble_tx How to transmit BLE beacons

Only 2.4GHz devices

blink Very simple blink/hello world application

diradv Direct Advertiser demo app

local_provisioning Local provisioning demo app

nfc NFC peripheral usage

Only Nordic nRF52xx

provisioning_joining_node Using provisioning for a joining node

provisioning_proxy Using provisioning for a proxy node

scheduler How to use Application scheduler

shared_data How to use shared_data.h

tinycbor use of the tiny cbor library

Production apps are following:

Application nameDescription

Notes

dualmcu_app Implementation of dual-MCU API interface, used most commonly in sinks

positioning_app Application to acquire network data for the positioning use case

Only Nordic nRF52xx

This page contains following sections:

app.c

This file is present in all applications. Application init function and its application callback functions should be implemented here as defined in the app.h file.

config.mk

config.mk file is used to configure application compilation. Here, the contents of that file have been described. Only fields that are common to all applications are described here! Some applications may have own, application-specific fields which are out of the scope of this documentation. For example, content of the file could be following:

# Define a specific application area_id
app_specific_area_id=0x8CEC79
# App version
app_major=1
app_minor=0
app_maintenance=0
app_development=0

This page contains following sections:

app_specific_area_id

Wirepas network supports Over The Air (OTAP) updates of devices on the network.

A network can contain heterogenous devices (different types of sensors, for example), so various different kinds of applications can coexist simultaneously in a network.

Even when upgrading a subset of nodes in the network (just nodes with a specific type of sensor, for example), all nodes will receive the update image. This is to ensure that all nodes on the network receive the update image, due to the multi-hop nature of the network. Consequently, it is crucial for a node to know if the received image, called a scratchpad, contains any updates for the node in question. This is the purpose of the application area ID.

More information about Over The Air Protocol can be found in [1].

Each new application must define its own app_specific_area_id in its config.mk file. It is a random 24-bit field that must have its most significant bit set to 1 (MSB to 0 is reserved for Wirepas):

# Define a specific application area_id
app_specific_area_id=0x83744C

This specific area ID will be used in two different places:

  • The bootloader, which contains a list of area IDs that it accepts, when a new scratchpad is processed. All the nodes that will be flashed with the image generated from an application build (containing the bootloader) will only accept updates of the application matching the specific area ID defined in config.mk.
  • In the scratchpad generation tool (genscratchpad.py), where it identifies the application scratchpad image. All the *.otap images generated from this application build will be only accepted by nodes flashed with a bootloader matching this area ID.

The app_specific_area_id is only part of the scratchpad area id existing on the device. The whole scratchpad area id is composed on 4 bytes, as following:

byte #content
MSB byte 0app_specific_area_id MSB byte 0
byte 1app_specific area id byte 1
byte 2app_specific area id LSB byte 2
byte 3 LSB hardware magic (see app_lib_system_hardware_magic_e)

For example, if app_specific_area_id has value of 0x83744C and used hardware is Nordic nRF52 (i.e. app_lib_system_hardware_magic_e is APP_LIB_SYSTEM_HARDWARE_MAGIC_NRF52832_SP_2), the resulted area id stored in the devices is:

(0x83744C << 8) | 3 = 0x83744C03

To summarize, in order to have unique scratchpad image on the device, the image must have*

  • Unique app_specific_area_id OR
  • Unique processor architecture.

If, however, same application is built on different board (but having same processor architecture), it will result same area id and otap mechanism cannot disinguish the images from others.

Note
It is up to each customer to maintain its own set of app_area_id to avoid mismatch between its applications.

Application version

Following definitions:

# App version
app_major=1
app_minor=0
app_maintenance=0
app_development=0

define the version of the application software. It is different from stack software and is application- specific. This information can be used to pinpoint which version of the application is running on the device.

TARGET_BOARDS

This configuration defines the boards which application supports. Configuration is optional.

Note
If configuration is not present, it equals that it is supported on every board available. Usually that is not the case so it is better to ensure that only boards supported are listed here. Then, if incorrect board is tried to be compiled, it is ensured that compilation fails.

Example:

TARGET_BOARDS := pca10056 pca10059 pca10040 wirepas_brd4254a silabs_brd4254a tbsense2 ublox_b204 promistel_rpi_hat

makefile

Application specific makefile contains application-specific build recipes. Here, the common features are documented:

This page contains following sections:

APP_PRINTING

Enabling of uart_print.h app debug prints can be done with this configuration.

Example:

# Enable application debug prints
APP_PRINTING=yes

APP_SCHEDULER

Using of app scheduler can be done by using this flag.

Example:

# Use App Scheduler. Declare 4 tasks
APP_SCHEDULER=yes
APP_SCHEDULER_TASKS=4

CFLAGS

Introducing custom compilation flags for compilation can be done by extending this list.

Example:

CFLAGS += -DOWN_FLAG
Note
Commonly this is used in many applications to propagate network address and network channel defined in config.mk file to compilation flags:
# Define default network settings
CFLAGS += -DNETWORK_ADDRESS=$(default_network_address)
CFLAGS += -DNETWORK_CHANNEL=$(default_network_channel)

HAL_GPIO

Using of HAL for GPIOs can be done by this flag.

Example:

# This application use HAL for GPIOs
HAL_GPIO=yes
Note
: in order for application to be able to drive GPIOs, they must be defined in specific board.

HAL_BUTTON

Using of HAL for buttons can be done by this flag.

Example:

# This application use HAL for buttons
HAL_BUTTON=yes
Note
: in order for application to be able to drive buttons, they must be defined in specific board.

HAL_HW_DELAY

Using of HAL for hardware delay can be done by this flag.

Example:

HAL_HW_DELAY=yes

HAL_I2C

Using of HAL for I2C interface can be done by this flag.

Example:

HAL_I2C=yes
Note
This option is supported only on nRF52 architectures.

HAL_LED

Using of HAL for led driving can be done by this flag.

Example:

# This application use HAL for leds
HAL_LED=yes
Note
: in order for application to be able to drive LEDs, they must be defined in specific board.

HAL_PERSISTENT_MEMORY

Using of HAL for persistent memory can be done by this flag.

Note
You need to define -DUSE_PERSISTENT_MEMORY by using CLAGS option.

Example:

# Use persistent memeory
HAL_PERSISTENT_MEMORY=yes
CFLAGS += -DUSE_PERSISTENT_MEMORY

HAL_SPI

Using of HAL for SPI interface can be done by this flag.

Example:

HAL_SPI=yes
Note
This option is supported only on nRF52 architectures.

HAL_UART

Using of HAL for UART interface can be done by this flag.

Example:

HAL_UART=yes
Note
: in order for application to be able to UART, they must be defined in specific board.

There is also related flag UART_USE_DMA that can be used to enable DMA functionality.

Example:

HAL_UART=yes
UART_USE_DMA=yes

INCLUDES

Extending to to include folders for include search paths can be done by extending this list.

Example:

INCLUDES +=

LDFLAGS

Introducing custom linker flags for ld can be done by extending this list.

Example:

#Link standard C math library
LDFLAGS += -lm

LIBS

Introducing of precompiled libraries (.a files) for compilation can be done by extending this list.

Example:

LIBS +=

PROVISIONING

Using of provisioning library can be done by using this flag.

Example:

# Use Provisioning
PROVISIONING=yes

PROVISIONING_PROXY

Using of provisioning library (for the existing node) can be done by using this flag.

Example:

# Use Provisioning Proxy
PROVISIONING_PROXY=yes

SHARED_DATA

Using of shared data library can be done by using this flag.

Example:

# Use Shared Data
SHARED_DATA=yes

SRCS

Introducing of new source files can be done by extending this list.

Example:

SRCS +=

SW_AES

Software AES library can be enabled by using this configuration.

Example:

# Enable software AES
SW_AES=yes

Tools

This folder contains various tools, mainly implemented in Python, used during build process of the application.

This page contains following sections:

genscratchpad.py

This tool, used by the Makefile, allows the scratchpad binary generation for the OTAP update. It uses the ini file in the same directory

INI_FILE

All scratchpad images received Over The Air are compressed and encrypted.

The bootloader authenticates the image and decrypts it, so authentication and encryption keys used to generate a scratchpad must match the ones stored in the bootloader.

The list of keys stored in bootloader can be configured at the end of tools/scratchpad_<mcu>.ini file. The bootloader can contain several keys and will decrypt a received scratchpad, if it can be authenticated with any of the listed keys.

By default, each application uses the same .ini file stored in tools/scratchpad_<mcu>.ini but it can be copied to the application folder and modified as needed. The new .ini file can be specified from the application as following:

# Define a specific scratchpad ini
INI_FILE = $(APP_SRCS_PATH)/scratchpad_custom.ini

The scratchpad generated from an application build use the key named default from the .ini file. It can be changed by adding the –keyname option to the invocation of genscratchpad.py script from makefile.