Detailed Description

The global macros, types and functions available to applications can be found in the wms_app.h header.

Definition in file wms_app.h.

Typedefs
typedef uint32_t(*	app_get_api_version_f) (void)

typedef app_firmware_version_t(*	app_get_stack_firmware_version_f) (void)
	Get stack firmware version. More...

typedef uint32_t(*	get_api_version_compatible_f) (void)

typedef uint32_t	app_addr_t

Functions
intptr_t	App_entrypoint (const void functions, size_t reserved1, const void reserved2, void *ram_top)
	Application initial entrypoint. More...

static uint32_t	App_getApiVersion (const void *const global_cb)

Data Structures
union	app_v2_tag_t

struct	app_information_header_t
	Application information header. More...

union	app_firmware_version_t

struct	app_global_functions_t
	List of global functions, passed to App_entrypoint() More...

struct	app_firmware_version_t.__unnamed__

Enumerations
enum	app_res_e { APP_RES_OK = 0, APP_RES_UNSPECIFIED_ERROR = 1, APP_RES_NOT_IMPLEMENTED = 2, APP_RES_INVALID_VALUE = 3, APP_RES_INVALID_NULL_POINTER = 4, APP_RES_INVALID_CONFIGURATION = 5, APP_RES_RESOURCE_UNAVAILABLE = 6, APP_RES_INVALID_STACK_STATE = 7, APP_RES_ACCESS_DENIED = 8 }

enum	app_special_addr_e { APP_ADDR_ANYSINK = 0xfffffffeu, APP_ADDR_BROADCAST = 0xffffffffu, APP_ADDR_MULTICAST = 0x80000000u, APP_ADDR_MULTICAST_LAST = 0x80ffffffu }
	Special destination addresses for sending packets. More...

Macros
#define	__STATIC_INLINE static inline

#define	APP_API_VERSION 0x200

#define	APP_V2_TAG

#define	APP_V2_TAG_LENGTH 16

#define	APP_V2_TAG_OFFSET 48

#define	APP_V2_TAG_MIN_API_VERSION 0x200

#define	APP_API_V1_VERSION 0x100

Variables
const typedef void (	app_open_library_f )(uint32_t name, uint32_t version)
	Open a library. More...

Typedef Documentation

◆ app_addr_t

typedef uint32_t app_addr_t

Node address. Each node must have a unique address in the network. There are special addresses that can be used as destination addresses, see app_special_addr_e. For various addressing modes, see addressing.

Definition at line 228 of file wms_app.h.

◆ app_get_api_version_f

typedef uint32_t(* app_get_api_version_f) (void)

Get the global API version, which may be greater than the APP_API_VERSION macro if the stack firmware is newer than the SDK used to compile the application. It is up to the stack firmware to be backward compatible with any global API changes, or not run the application at all.

Returns: Supported application API version, APP_API_VERSION

Definition at line 102 of file wms_app.h.

◆ app_get_stack_firmware_version_f

typedef app_firmware_version_t(* app_get_stack_firmware_version_f) (void)

Get stack firmware version.

Returns: Stack firmware version

Definition at line 108 of file wms_app.h.

◆ get_api_version_compatible_f

typedef uint32_t(* get_api_version_compatible_f) (void)

A function to safely call either getApiVersion() or getCurrentRole()

Definition at line 182 of file wms_app.h.

Function Documentation

◆ App_entrypoint()

intptr_t App_entrypoint	(	const void *	functions,
		size_t	reserved1,
		const void **	reserved2,
		void **	ram_top
	)

Application initial entrypoint.

Parameters

functions	Pointer to a global function table, app_global_functions_t
reserved1	Reserved for future use
reserved2	Reserved for future use
ram_top	Pointer to a pointer of first free RAM address. The application may reduce this value, if it does not need all the RAM provided to it

◆ App_getApiVersion()

static uint32_t App_getApiVersion ( const void *const global_cb )

inlinestatic

Definition at line 184 of file wms_app.h.

 {
     uint32_t version =
         ((const get_api_version_compatible_f)*(const void **)global_cb)();
     if (version < APP_API_V1_VERSION)
     {
         // Called function was actually the getCurrentRole() function,
         // so the firmware only supports the v1 application API
         return APP_API_V1_VERSION;
     }
     return version;
 }

Data Structure Documentation

◆ app_v2_tag_t

union app_v2_tag_t

Container for APP_V2_TAG, for pointer arithmetic

Definition at line 48 of file wms_app.h.

Data Fields
uint32_t	array[16/4]
uint8_t	bytes[16]

◆ app_information_header_t

struct app_information_header_t

Application information header.

If an application is compiled to support application API v2, this header can found in the beginning of the application memory area. It is placed right after the APP_V2_TAG, which is at APP_V2_TAG_OFFSET.

Definition at line 61 of file wms_app.h.

Data Fields
uint32_t	api_version	Expected API version of application
uint32_t	length	Total number of bytes used in the application memory area
uint32_t	start_address	Expected start address of application memory area, for sanity checks
uint32_t	start_ram_address	First address used in RAM area (was forced to be 0 before)

◆ app_firmware_version_t

union app_firmware_version_t

Firmware version type, returned from app_global_functions_t::getStackFirmwareVersion(). The individual sub-fields can be accessed, or the whole 32-bit value can be read all at once, using the version field.

Definition at line 79 of file wms_app.h.

Data Fields
struct app_firmware_version_t	__unnamed__
uint32_t	version

◆ app_global_functions_t

struct app_global_functions_t

List of global functions, passed to App_entrypoint()

Examples: aes/app.c, appconfig/app.c, basic_interrupt/app.c, ble_scanner/app.c, ble_tx/app.c, blink/app.c, custom_app/app.c, dualmcu_app/app.c, minimal_app/app.c, nfc/app.c, positioning_app/app.c, provisioning_joining_node/app.c, provisioning_proxy/app.c, ruuvi_evk/app.c, scheduler/app.c, shared_data/app.c, and tinycbor/app.c.

Definition at line 157 of file wms_app.h.

Data Fields
app_get_api_version_f	getApiVersion
app_get_stack_firmware_version_f	getStackFirmwareVersion
app_open_library_f	openLibrary

◆ app_firmware_version_t.unnamed

struct app_firmware_version_t.__unnamed__

Definition at line 81 of file wms_app.h.

Data Fields
uint8_t	devel	Firmware development version number component
uint8_t	maint	Firmware maintenance version number component
uint8_t	major	Firmware major version number component
uint8_t	minor	Firmware minor version number component

Enumeration Type Documentation

◆ app_res_e

enum app_res_e

This is the most common return type from library functions. Functions use these return values, unless more specific return values are required.

Enumerator
APP_RES_OK	Everything is OK
APP_RES_UNSPECIFIED_ERROR	Error: Other or internal error
APP_RES_NOT_IMPLEMENTED	Error: Feature is not implemented
APP_RES_INVALID_VALUE	Error: One or more parameter value is invalid
APP_RES_INVALID_NULL_POINTER	Error: One or more required pointer parameter is NULL
APP_RES_INVALID_CONFIGURATION	Error: Current configuration does not support the requested operation
APP_RES_RESOURCE_UNAVAILABLE	Error: Requested resource is not available
APP_RES_INVALID_STACK_STATE	Error: Stack is in invalid state for the requested operation
APP_RES_ACCESS_DENIED	Error: Feature lock bits forbid the requested operation

Definition at line 201 of file wms_app.h.

 {
     APP_RES_OK = 0,
     APP_RES_UNSPECIFIED_ERROR = 1,
     APP_RES_NOT_IMPLEMENTED = 2,
     APP_RES_INVALID_VALUE = 3,
     APP_RES_INVALID_NULL_POINTER = 4,
     APP_RES_INVALID_CONFIGURATION = 5,
     APP_RES_RESOURCE_UNAVAILABLE = 6,
     APP_RES_INVALID_STACK_STATE = 7,
     APP_RES_ACCESS_DENIED = 8,
 } app_res_e;

◆ app_special_addr_e

enum app_special_addr_e

Special destination addresses for sending packets.

Enumerator
APP_ADDR_ANYSINK	Send packet to the best available sink
APP_ADDR_BROADCAST	Send packet as broadcast to all nodes. Note When transmitting from a sink, note that a broadcast will only be transmitted to the nodes directly under the sink's routing tree. To reach all nodes on the network, it is necessary to send the broadcast from all sinks.
APP_ADDR_MULTICAST	This is a bitmask that should be ORed with group address to send data packet to the multicast group. For example: 0x80000002 address sends packet to the multicast group #2.
APP_ADDR_MULTICAST_LAST	This is last valid multicast address. Addresses larger than this (until APP_ADDR_ANYSINK) are unicast addresses.

Definition at line 233 of file wms_app.h.

 {
     APP_ADDR_ANYSINK     = 0xfffffffeu,
     APP_ADDR_BROADCAST   = 0xffffffffu,
     APP_ADDR_MULTICAST   = 0x80000000u,
     APP_ADDR_MULTICAST_LAST = 0x80ffffffu,
 } app_special_addr_e;

Macro Definition Documentation

◆ __STATIC_INLINE

#define __STATIC_INLINE static inline

Definition at line 20 of file wms_app.h.

◆ APP_API_V1_VERSION

#define APP_API_V1_VERSION 0x100

Application API version when no tag present: v1

Definition at line 45 of file wms_app.h.

◆ APP_API_VERSION

#define APP_API_VERSION 0x200

Global application API version. This is incremented if the global function table format changes in an incompatible way. The value of this macro is placed in the application header, so that the stack can detect and handle the situation.

Definition at line 28 of file wms_app.h.

◆ APP_V2_TAG

#define APP_V2_TAG

Value:

("APP2\171\306\073\165" \

"\263\303\334\322\035\266\006\115")

Magic 16-byte string for locating a v2 application in Flash

Definition at line 31 of file wms_app.h.

◆ APP_V2_TAG_LENGTH

#define APP_V2_TAG_LENGTH 16

Length of APP_V2_TAG, in bytes

Definition at line 35 of file wms_app.h.

◆ APP_V2_TAG_MIN_API_VERSION

#define APP_V2_TAG_MIN_API_VERSION 0x200

Minimum supported application API version, when a tag is present: v2

Definition at line 42 of file wms_app.h.

◆ APP_V2_TAG_OFFSET

#define APP_V2_TAG_OFFSET 48

Byte offset of APP_V2_TAG from the start of application memory area

Definition at line 38 of file wms_app.h.

Variable Documentation

◆ app_open_library_f

const typedef void*(* app_open_library_f) (uint32_t name, uint32_t version)

Open a library.

This is the most important function of the Single-MCU API. All other functions are in libraries, opened using the this function. Parameters are the name and version of the library. The name is actually a 32-bit value, which is defined in each library header as a macro: APP_LIB_LIBRARY_NAME. The library version is also a macro defined in the same library header: APP_LIB_LIBRARY_VERSION.

Example of opening a library:

// The System library
static const app_lib_system_t * lib_system = NULL;
 
...
 
void App_init(const app_global_functions_t * functions)
{
    lib_system = functions->openLibrary(APP_LIB_SYSTEM_NAME,
                                        APP_LIB_SYSTEM_VERSION);
    if (lib_system == NULL)
    {
        // Could not open the System library
        return;
    }
    ...
}