wms_otap.h File Reference

Detailed Description

The Over-The-Air-Programming (OTAP) library allows reading and writing the OTAP scratchpad memory area of a Wirepas Mesh node. Using the OTAP library, it is possible to wirelessly upgrade the stack firmware and applications on a running network.

To gain better understanding of the OTAP library, getting familiar with concepts outlined in WP-RM-108 - OTAP Reference Manual is recommended.

Library services are accesses via lib_otap handle

Definition in file wms_otap.h.

Go to the source code of this file.

Typedefs
typedef uint8_t	app_lib_otap_seq_t
	Type for OTAP sequence number. More...
typedef size_t(*	app_lib_otap_get_max_num_bytes_f) (void)
	Get maximum scratchpad size. More...
typedef size_t(*	app_lib_otap_get_num_bytes_f) (void)
	Get stored scratchpad size. More...
typedef size_t(*	app_lib_otap_get_max_block_num_bytes_f) (void)
	Get maximum block size in bytes. More...
typedef app_lib_otap_seq_t(*	app_lib_otap_get_seq_f) (void)
	Get the OTAP sequence number. More...
typedef uint16_t(*	app_lib_otap_get_crc_f) (void)
	Get the 16-bit CRC of the stored scratchpad. More...
typedef app_lib_otap_type_e(*	app_lib_otap_get_type_f) (void)
	Get the type of the stored scratchpad. More...
typedef app_lib_otap_status_e(*	app_lib_otap_get_status_f) (void)
	Get the bootloader status of the stored scratchpad. More...
typedef size_t(*	app_lib_otap_get_processed_num_bytes_f) (void)
	Get the size of scratchpad, in bytes, that produced the running stack firmware. More...
typedef app_lib_otap_seq_t(*	app_lib_otap_get_processed_seq_f) (void)
	Get the OTAP sequence number of the scratchpad that produced the running stack firmware. More...
typedef uint16_t(*	app_lib_otap_get_processed_crc_f) (void)
	Get the 16-bit CRC of the scratchpad that produced the running stack firmware. More...
typedef uint32_t(*	app_lib_otap_get_processed_area_id_f) (void)
	Get the area ID of the file in the scratchpad that produced the running stack firmware. More...
typedef bool(*	app_lib_otap_is_valid_f) (void)
	Get the scratchpad validity status. More...
typedef bool(*	app_lib_otap_is_processed_f) (void)
	Check if the stored scratchpad has been processed by the bootloader. More...
typedef bool(*	app_lib_otap_is_set_to_be_processed_f) (void)
	Check if scratchpad is set to be processed. More...
typedef app_res_e(*	app_lib_otap_read_f) (uint32_t start, size_t num_bytes, void *bytes)
	Read a block of scratchpad. More...
typedef app_res_e(*	app_lib_otap_clear_f) (void)
	Erase a stored scratchpad from memory. More...
typedef app_res_e(*	app_lib_otap_begin_f) (size_t num_bytes, app_lib_otap_seq_t seq)
	Start writing a new scratchpad. More...
typedef app_lib_otap_write_res_e(*	app_lib_otap_write_f) (uint32_t start, size_t num_bytes, const void *bytes)
	Write a block of scratchpad. More...
typedef app_res_e(*	app_lib_otap_set_to_be_processed_f) (void)
	Mark the stored scratchpad to be eligible for processing by the bootloader. More...
typedef app_res_e(*	app_lib_otap_set_target_scratchpad_and_action_f) (app_lib_otap_seq_t target_sequence, uint16_t target_crc, app_lib_otap_action_e action, uint8_t delay)
	This service allows to set the information for scratchpad in the sink tree. What is the target scratchpad and what is the action to do with it. More...
typedef app_res_e(*	app_lib_otap_get_target_scratchpad_and_action_f) (app_lib_otap_seq_t *target_sequence, uint16_t *target_crc, app_lib_otap_action_e *action, uint8_t *delay)
	This service allows to get the information for scratchpad in the sink tree. What is the target scratchpad and what is the action to do with it. More...

Data Structures
struct	app_lib_otap_t

Enumerations
enum	app_lib_otap_type_e { APP_LIB_OTAP_TYPE_BLANK = 0, APP_LIB_OTAP_TYPE_PRESENT = 1, APP_LIB_OTAP_TYPE_PROCESS = 2 }
	Different scratchpad type. More...
enum	app_lib_otap_status_e { APP_LIB_OTAP_STATUS_OK = 0x00000000, APP_LIB_OTAP_STATUS_NEW = UINT32_MAX }
	Status code from the bootloader. More...
enum	app_lib_otap_write_res_e {   APP_LIB_OTAP_WRITE_RES_OK = 0, APP_LIB_OTAP_WRITE_RES_COMPLETED_OK = 1, APP_LIB_OTAP_WRITE_RES_COMPLETED_ERROR = 2, APP_LIB_OTAP_WRITE_RES_NOT_ONGOING = 3,   APP_LIB_OTAP_WRITE_RES_INVALID_START = 4, APP_LIB_OTAP_WRITE_RES_INVALID_NUM_BYTES = 5, APP_LIB_OTAP_WRITE_RES_INVALID_HEADER = 6, APP_LIB_OTAP_WRITE_RES_INVALID_NULL_BYTES = 7 }
	Write function return code. More...
enum	app_lib_otap_action_e {   APP_LIB_OTAP_ACTION_NO_OTAP = 0, APP_LIB_OTAP_ACTION_PROPAGATE_ONLY = 1, APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS = 2, APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS_WITH_DELAY = 3,   APP_LIB_OTAP_ACTION_LEGACY = 4 }
	Scratchpad possible actions. More...

Macros
#define	APP_LIB_OTAP_NAME   0x000f2338
	Library symbolic name More...
#define	APP_LIB_OTAP_VERSION   0x201
	Maximum supported library version. More...

Typedef Documentation

app_lib_otap_begin_f

typedef app_res_e(* app_lib_otap_begin_f) (size_t num_bytes, app_lib_otap_seq_t seq)

Start writing a new scratchpad.

Any old scratchpad is implicitly erased, which may take several seconds on some platforms.

Scratchpad can only be written when the stack is stopped. num_bytes must be divisible by four and a minimum of 96 bytes, which is the minimum valid scratchpad size. Maximum scratchpad size can be queried with the lib_otap->getMaxNumBytes() function.

When writing the scratchpad to a node, with the lib_otap->write() function described below, the bytes written contain a scratchpad header, with an OTAP sequence number field. The OTAP sequence number in that header is replaced with the seq parameter specified here.

Returns APP_RES_INVALID_STACK_STATE if stack is running. Returns APP_RES_INVALID_VALUE if num_bytes is invalid. Otherwise, returns APP_RES_OK.

Parameters

num_bytes	Total number of bytes to write
seq	Scratchpad sequence number

Returns

Result code, APP_RES_OK if successful, APP_RES_INVALID_VALUE if num_bytes or seq is invalid, APP_RES_INVALID_STACK_STATE if stack is running

Note

Scratchpad memory is implicitly cleared if this call succeeds

Definition at line 352 of file wms_otap.h.

app_lib_otap_clear_f

typedef app_res_e(* app_lib_otap_clear_f) (void)

Erase a stored scratchpad from memory.

Erasing the scratchpad is only possible when the stack is stopped.

When the stack is started, unless feature lock bits prevent it, a scratchpad may be received again depending on otap target in network

Returns

Result code, APP_RES_OK if successful, APP_RES_INVALID_STACK_STATE if stack is running

Note

On some platforms, this function may take several seconds to complete

Definition at line 321 of file wms_otap.h.

app_lib_otap_get_crc_f

typedef uint16_t(* app_lib_otap_get_crc_f) (void)

Get the 16-bit CRC of the stored scratchpad.

Returns

CRC of data in scratchpad, or zero if scratchpad is not valid

Note

Calling this function may take several tens of milliseconds

Calling this function for the first time after a scratchpad has changed may take several tens of milliseconds.

Definition at line 177 of file wms_otap.h.

app_lib_otap_get_max_block_num_bytes_f

typedef size_t(* app_lib_otap_get_max_block_num_bytes_f) (void)

Get maximum block size in bytes.

It is the maximum block size, in bytes, that can be fed to the lib_otap->write() function

Returns

Maximum number of bytes for read() or write()

Definition at line 154 of file wms_otap.h.

app_lib_otap_get_max_num_bytes_f

typedef size_t(* app_lib_otap_get_max_num_bytes_f) (void)

Get maximum scratchpad size.

Returns

Return the maximum possible scratchpad size in bytes.

Definition at line 135 of file wms_otap.h.

app_lib_otap_get_num_bytes_f

typedef size_t(* app_lib_otap_get_num_bytes_f) (void)

Get stored scratchpad size.

Returns

Number of bytes in scratchpad, or zero if scratchpad is not valid

Definition at line 143 of file wms_otap.h.

app_lib_otap_get_processed_area_id_f

typedef uint32_t(* app_lib_otap_get_processed_area_id_f) (void)

Get the area ID of the file in the scratchpad that produced the running stack firmware.

The bootloader stores this information in the stack firmware area, when it writes the firmware.

Returns

Area ID of running stack firmware, or zero if not known

Definition at line 242 of file wms_otap.h.

app_lib_otap_get_processed_crc_f

typedef uint16_t(* app_lib_otap_get_processed_crc_f) (void)

Get the 16-bit CRC of the scratchpad that produced the running stack firmware.

The bootloader stores this information in the stack firmware area, when it writes the firmware.

Returns

CRC of processed scratchpad, or zero if not known

Definition at line 230 of file wms_otap.h.

app_lib_otap_get_processed_num_bytes_f

typedef size_t(* app_lib_otap_get_processed_num_bytes_f) (void)

Get the size of scratchpad, in bytes, that produced the running stack firmware.

The bootloader stores this information in the stack firmware area, when it writes the firmware.

Returns

Number of bytes in processed scratchpad, or zero if not known

Definition at line 206 of file wms_otap.h.

app_lib_otap_get_processed_seq_f

typedef app_lib_otap_seq_t(* app_lib_otap_get_processed_seq_f) (void)

Get the OTAP sequence number of the scratchpad that produced the running stack firmware.

The bootloader stores this information in the stack firmware area, when it writes the firmware.

Returns

Sequence number of processed scratchpad, or zero if not known

Definition at line 218 of file wms_otap.h.

app_lib_otap_get_seq_f

typedef app_lib_otap_seq_t(* app_lib_otap_get_seq_f) (void)

Get the OTAP sequence number.

Get the OTAP sequence number app_lib_otap_seq_t of the stored scratchpad, or 0 if there is no stored scratchpad

Returns

Sequence number, or zero if scratchpad is not valid

Definition at line 165 of file wms_otap.h.

app_lib_otap_get_status_f

typedef app_lib_otap_status_e(* app_lib_otap_get_status_f) (void)

Get the bootloader status of the stored scratchpad.

Returns

Status, or APP_LIB_OTAP_STATUS_OK if scratchpad is not valid

Definition at line 194 of file wms_otap.h.

app_lib_otap_get_target_scratchpad_and_action_f

typedef app_res_e(* app_lib_otap_get_target_scratchpad_and_action_f) (app_lib_otap_seq_t *target_sequence, uint16_t *target_crc, app_lib_otap_action_e *action, uint8_t *delay)

This service allows to get the information for scratchpad in the sink tree. What is the target scratchpad and what is the action to do with it.

Parameters

target_sequence	The scratchpad target sequence for this sink tree.
target_crc	The scratchpad target crc for this sink tree.
action	The action to do with the target scratchpad
delay	The delay to process the scratchpad. Only needed if action is APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS_WITH_DELAY.

Returns

Result code, APP_RES_OK if successful

Definition at line 482 of file wms_otap.h.

app_lib_otap_get_type_f

typedef app_lib_otap_type_e(* app_lib_otap_get_type_f) (void)

Get the type of the stored scratchpad.

Returns

Type of stored scratchpad, app_lib_otap_type_e

Definition at line 185 of file wms_otap.h.

app_lib_otap_is_processed_f

typedef bool(* app_lib_otap_is_processed_f) (void)

Check if the stored scratchpad has been processed by the bootloader.

The same information is available via the more generic functions lib_otap->getType() and lib_otap->getStatus().

Returns

True, if the scratchpad has been processed by the bootloader

Definition at line 267 of file wms_otap.h.

app_lib_otap_is_set_to_be_processed_f

typedef bool(* app_lib_otap_is_set_to_be_processed_f) (void)

Check if scratchpad is set to be processed.

Returns

True, if scratchpad data is valid and marked to be processed

Definition at line 275 of file wms_otap.h.

app_lib_otap_is_valid_f

typedef bool(* app_lib_otap_is_valid_f) (void)

Get the scratchpad validity status.

The same information is available via the more generic function lib_otap->getType().

Returns

True, if data in scratchpad is valid

Note

Valid data isn't necessarily a firmware image

Definition at line 255 of file wms_otap.h.

app_lib_otap_read_f

typedef app_res_e(* app_lib_otap_read_f) (uint32_t start, size_t num_bytes, void *bytes)

Read a block of scratchpad.

Reading can be done in a random-access fashion and stack can remain running.

start is the byte offset within the scratchpad. num_bytes is the number of bytes to read. bytes must point to a buffer of suitable size. Maximum number of bytes to read at a time can be queried with the lib_otap->getMaxBlockNumBytes() function.

Simultaneous reading and writing of scratchpad is not supported. A lib_otap->begin() / lib_otap->write() cycle must not be ongoing when calling this function.

Parameters

start	Byte offset from the beginning of scratchpad memory
num_bytes	Number of bytes to read
bytes	Pointer to buffer for reading bytes

Returns

Result code, APP_RES_OK if successful, APP_RES_INVALID_VALUE if start or num_bytes is invalid, APP_RES_INVALID_NULL_POINTER if bytes is NULL, APP_RES_RESOURCE_UNAVAILABLE if scratchpad is not valid

Definition at line 303 of file wms_otap.h.

app_lib_otap_seq_t

typedef uint8_t app_lib_otap_seq_t

Type for OTAP sequence number.

Two numbers are special:

Value	Description
0	Node does not participate in OTAP
255	Node accepts any scratchpad from the network as newer

Definition at line 127 of file wms_otap.h.

app_lib_otap_set_target_scratchpad_and_action_f

typedef app_res_e(* app_lib_otap_set_target_scratchpad_and_action_f) (app_lib_otap_seq_t target_sequence, uint16_t target_crc, app_lib_otap_action_e action, uint8_t delay)

This service allows to set the information for scratchpad in the sink tree. What is the target scratchpad and what is the action to do with it.

Parameters

target_sequence	The scratchpad target sequence for this Sink tree. Only needed if action is APP_LIB_OTAP_ACTION_PROPAGATE_ONLY, APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS or APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS_WITH_DELAY. Valid values are 1..255.
target_crc	The scratchpad target crc for this Sink tree. Only needed if action is APP_LIB_OTAP_ACTION_PROPAGATE_ONLY, APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS or APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS_WITH_DELAY.
action	The action to do with the target scratchpad
delay	The delay to process the scratchpad. Only needed if action is APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS_WITH_DELAY. This delay can't be 0 minute/hour/day.

Returns

Result code, APP_RES_OK if successful.

Note

Returns APP_RES_INVALID_VALUE if delay is the same than the actual one when action is APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS_WITH_DELAY. This use case is invalid because setting the delay two consecutive times is ambiguous. In fact, as a node can switch from a sink to the other with the same delay, it must not reset its timer in this condition. So to be coherent, setting the same delay through the api is forbidden.

Example of use to load and set a scratcphad of N bytes with seq S to be processed in Sink tree

    // Write a scratchpad to the sink
    lib_otap->begin(N, S);
    while (res == APP_LIB_OTAP_WRITE_RES_COMPLETED_OK)
    {
       res = lib_otap->write(x,x,x)
    }
 
    // Check that scratchpad is correctly written
    ...
 
    lib_data->setTargetScratchpadAndAction(lib_otap->getSeq(),
                                           lib_otap->getCrc(),
                                           APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS,
                                           0 // Not used for this action);
}

The delay parameter is encoded as follows :

struct
{
    //Bits 0.. 5 - The time to delay.
    uint8_t delay :6;
    //Bits 6  .7 - Time unit used (1:Minutes, 2:Hours, 3:Days).
    uint8_t unit  :2;
};

Definition at line 459 of file wms_otap.h.

app_lib_otap_set_to_be_processed_f

typedef app_res_e(* app_lib_otap_set_to_be_processed_f) (void)

Mark the stored scratchpad to be eligible for processing by the bootloader.

Whenever the node will be rebooted, the bootloader will process the scratchpad. If the scratchpad was already marked for processing or was already processed, this function does nothing.

Returns

Result code, APP_RES_OK if successful, APP_RES_RESOURCE_UNAVAILABLE if scratchpad data is invalid

Note

Does nothing if scratchpad was already set to be bootable

Definition at line 395 of file wms_otap.h.

app_lib_otap_write_f

typedef app_lib_otap_write_res_e(* app_lib_otap_write_f) (uint32_t start, size_t num_bytes, const void *bytes)

Write a block of scratchpad.

Write must have been started with the lib_otap->begin() function.

start must follow the previous block exactly and num_bytes must be divisible by four. The first block must start from zero. Maximum number of bytes to write at a time can be queried with the lib_otap->getMaxBlockNumBytes() function.

Parameters

start	Byte offset from the beginning of scratchpad memory
num_bytes	Number of bytes to write
bytes	Pointer to bytes to write

Returns

A return code: app_lib_otap_write_res_e

Note

num_bytes needs to be divisible by four

start byte offset needs to be right after previous write, with no gaps or overlap

Definition at line 378 of file wms_otap.h.

---

Data Structure Documentation

app_lib_otap_t

struct app_lib_otap_t

The function table returned from app_open_library_f

Definition at line 491 of file wms_otap.h.

Data Fields
app_lib_otap_begin_f	begin
app_lib_otap_clear_f	clear
app_lib_otap_get_crc_f	getCrc
app_lib_otap_get_max_block_num_bytes_f	getMaxBlockNumBytes
app_lib_otap_get_max_num_bytes_f	getMaxNumBytes
app_lib_otap_get_num_bytes_f	getNumBytes
app_lib_otap_get_processed_area_id_f	getProcessedAreaId
app_lib_otap_get_processed_crc_f	getProcessedCrc
app_lib_otap_get_processed_num_bytes_f	getProcessedNumBytes
app_lib_otap_get_processed_seq_f	getProcessedSeq
app_lib_otap_get_seq_f	getSeq
app_lib_otap_get_status_f	getStatus
app_lib_otap_get_target_scratchpad_and_action_f	getTargetScratchpadAndAction
app_lib_otap_get_type_f	getType
app_lib_otap_is_processed_f	isProcessed
app_lib_otap_is_set_to_be_processed_f	isSetToBeProcessed
app_lib_otap_is_valid_f	isValid
app_lib_otap_read_f	read
app_lib_otap_set_target_scratchpad_and_action_f	setTargetScratchpadAndAction
app_lib_otap_set_to_be_processed_f	setToBeProcessed
app_lib_otap_write_f	write

Enumeration Type Documentation

app_lib_otap_action_e

enum app_lib_otap_action_e

Scratchpad possible actions.

Used with the lib_otap->setTargetScratchpadAndAction() function

Enumerator
APP_LIB_OTAP_ACTION_NO_OTAP	No otap in the sink tree.
APP_LIB_OTAP_ACTION_PROPAGATE_ONLY	Only propagate the target scratchpad but do not process it.
APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS	Propagate the target scratchpad and process it immediately.
APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS_WITH_DELAY	Same as previous except that the processing should happen after the given delay. Delay starts when node receive the information and the scratchpad is valid.
APP_LIB_OTAP_ACTION_LEGACY	Exchange and processing of scratchpad is managed the old way (sequence comparison).

Definition at line 100 of file wms_otap.h.

{
    APP_LIB_OTAP_ACTION_NO_OTAP = 0,
    APP_LIB_OTAP_ACTION_PROPAGATE_ONLY = 1,
    APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS = 2,
    APP_LIB_OTAP_ACTION_PROPAGATE_AND_PROCESS_WITH_DELAY = 3,
    APP_LIB_OTAP_ACTION_LEGACY = 4,
} app_lib_otap_action_e;

app_lib_otap_status_e

enum app_lib_otap_status_e

Status code from the bootloader.

Used with the lib_otap->getStatus() function

Note

Other small positive values may be returned as error codes from the bootloader.

Enumerator
APP_LIB_OTAP_STATUS_OK	The bootloader processed the scratchpad and everything went well
APP_LIB_OTAP_STATUS_NEW	The bootloader has not yet processed the scratchpad

Definition at line 61 of file wms_otap.h.

{
    APP_LIB_OTAP_STATUS_OK = 0x00000000,
    APP_LIB_OTAP_STATUS_NEW = UINT32_MAX,
} app_lib_otap_status_e;

app_lib_otap_type_e

enum app_lib_otap_type_e

Different scratchpad type.

Used with the lib_otap->getType() function

Enumerator
APP_LIB_OTAP_TYPE_BLANK	No valid scratchpad stored
APP_LIB_OTAP_TYPE_PRESENT	The is a valid scratchpad, but it has not yet been marked for processing
APP_LIB_OTAP_TYPE_PROCESS	There is a valid scratchpad and it has been marked for processing

Definition at line 41 of file wms_otap.h.

{
    APP_LIB_OTAP_TYPE_BLANK = 0,
    APP_LIB_OTAP_TYPE_PRESENT = 1,
    APP_LIB_OTAP_TYPE_PROCESS = 2,
} app_lib_otap_type_e;

app_lib_otap_write_res_e

enum app_lib_otap_write_res_e

Write function return code.

Used with the lib_otap->write() function

Enumerator
APP_LIB_OTAP_WRITE_RES_OK	Write succeeded
APP_LIB_OTAP_WRITE_RES_COMPLETED_OK	Write succeeded and was the last one
APP_LIB_OTAP_WRITE_RES_COMPLETED_ERROR	Error: write was the last one but the CRC check failed
APP_LIB_OTAP_WRITE_RES_NOT_ONGOING	Error: there is no write ongoing
APP_LIB_OTAP_WRITE_RES_INVALID_START	Error: start is invalid
APP_LIB_OTAP_WRITE_RES_INVALID_NUM_BYTES	Error: num_bytes is invalid
APP_LIB_OTAP_WRITE_RES_INVALID_HEADER	Error: header is invalid
APP_LIB_OTAP_WRITE_RES_INVALID_NULL_BYTES	Error: bytes is NULL

Definition at line 74 of file wms_otap.h.

{
    APP_LIB_OTAP_WRITE_RES_OK = 0,
    APP_LIB_OTAP_WRITE_RES_COMPLETED_OK = 1,
    APP_LIB_OTAP_WRITE_RES_COMPLETED_ERROR = 2,
    APP_LIB_OTAP_WRITE_RES_NOT_ONGOING = 3,
    APP_LIB_OTAP_WRITE_RES_INVALID_START = 4,
    APP_LIB_OTAP_WRITE_RES_INVALID_NUM_BYTES = 5,
    APP_LIB_OTAP_WRITE_RES_INVALID_HEADER = 6,
    APP_LIB_OTAP_WRITE_RES_INVALID_NULL_BYTES = 7,
} app_lib_otap_write_res_e;

Macro Definition Documentation

APP_LIB_OTAP_NAME

#define APP_LIB_OTAP_NAME   0x000f2338

Library symbolic name

"OTAP"

Definition at line 30 of file wms_otap.h.

APP_LIB_OTAP_VERSION

#define APP_LIB_OTAP_VERSION   0x201

Maximum supported library version.

Definition at line 33 of file wms_otap.h.