Wirepas SDK
wms_app.h File Reference

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.

Go to the source code of this file.

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
functionsPointer to a global function table, app_global_functions_t
reserved1Reserved for future use
reserved2Reserved for future use
ram_topPointer 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.

185 {
186  uint32_t version =
187  ((const get_api_version_compatible_f)*(const void **)global_cb)();
188  if (version < APP_API_V1_VERSION)
189  {
190  // Called function was actually the getCurrentRole() function,
191  // so the firmware only supports the v1 application API
192  return APP_API_V1_VERSION;
193  }
194  return version;
195 }

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
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_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.

234 {
236  APP_ADDR_ANYSINK = 0xfffffffeu,
245  APP_ADDR_BROADCAST = 0xffffffffu,
251  APP_ADDR_MULTICAST = 0x80000000u,
254  APP_ADDR_MULTICAST_LAST = 0x80ffffffu,

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,
if (lib_system == NULL)
{
// Could not open the System library
return;
}
...
}
Parameters
nameSymbolic name of library, a macro in library header file
versionRequested library version, a macro in library header file
Returns
Pointer to the function table of the library. Each library has its own function table. If a NULL is returned, the library could not be opened. Either it didn't exist, or the version is too old or new.
Note
There is no corresponding closeLibrary() call. Applications never close libraries they open.

Definition at line 152 of file wms_app.h.

app_lib_system_t
List of library functions.
Definition: wms_system.h:533
app_global_functions_t::openLibrary
app_open_library_f openLibrary
Definition: wms_app.h:161
APP_RES_RESOURCE_UNAVAILABLE
@ APP_RES_RESOURCE_UNAVAILABLE
Definition: wms_app.h:216
app_res_e
app_res_e
Definition: wms_app.h:201
APP_ADDR_BROADCAST
@ APP_ADDR_BROADCAST
Send packet as broadcast to all nodes.
Definition: wms_app.h:245
APP_RES_NOT_IMPLEMENTED
@ APP_RES_NOT_IMPLEMENTED
Definition: wms_app.h:208
APP_RES_ACCESS_DENIED
@ APP_RES_ACCESS_DENIED
Definition: wms_app.h:220
APP_API_V1_VERSION
#define APP_API_V1_VERSION
Definition: wms_app.h:45
APP_RES_OK
@ APP_RES_OK
Definition: wms_app.h:204
APP_RES_UNSPECIFIED_ERROR
@ APP_RES_UNSPECIFIED_ERROR
Definition: wms_app.h:206
APP_RES_INVALID_CONFIGURATION
@ APP_RES_INVALID_CONFIGURATION
Definition: wms_app.h:214
APP_LIB_SYSTEM_NAME
#define APP_LIB_SYSTEM_NAME
Library symbolic name.
Definition: wms_system.h:35
app_global_functions_t
List of global functions, passed to App_entrypoint()
Definition: wms_app.h:157
get_api_version_compatible_f
uint32_t(* get_api_version_compatible_f)(void)
Definition: wms_app.h:182
APP_ADDR_MULTICAST
@ APP_ADDR_MULTICAST
Definition: wms_app.h:251
APP_ADDR_MULTICAST_LAST
@ APP_ADDR_MULTICAST_LAST
Definition: wms_app.h:254
app_special_addr_e
app_special_addr_e
Special destination addresses for sending packets.
Definition: wms_app.h:233
APP_RES_INVALID_NULL_POINTER
@ APP_RES_INVALID_NULL_POINTER
Definition: wms_app.h:212
APP_ADDR_ANYSINK
@ APP_ADDR_ANYSINK
Definition: wms_app.h:236
APP_LIB_SYSTEM_VERSION
#define APP_LIB_SYSTEM_VERSION
Maximum supported library version.
Definition: wms_system.h:38
APP_RES_INVALID_STACK_STATE
@ APP_RES_INVALID_STACK_STATE
Definition: wms_app.h:218
APP_RES_INVALID_VALUE
@ APP_RES_INVALID_VALUE
Definition: wms_app.h:210