App Utility#

The App BT Mesh Utility provides collection of stateless utility functions and macros to solve recurring tasks in the BT Mesh components and examples. This component supports logging of missing application key binding and missing model publication data configuration errors. The logging level of these errors are configurable. This component is suitable for use in both NCP and SOC applications.

Functions#

sl_status_t

app_btmesh_nvm_init(void)

sl_status_t

app_btmesh_nvm_read(uint16_t key, void *buf, size_t *len)

sl_status_t

app_btmesh_nvm_write(uint16_t key, const void *buf, size_t len)

sl_status_t

app_btmesh_nvm_erase(uint16_t key)

sl_status_t

app_btmesh_nvm_erase_all(void)

const char *

app_btmesh_uuid_64_to_string(char *buffer, uint32_t buffer_size, const sl_bt_uuid_64_t *uuid_64, char separator, bool uppercase)

const char *

app_btmesh_bytes_to_hex(char *buffer, uint32_t buffer_size, const uint8_t *bytes, uint32_t bytes_size, char separator, bool uppercase)

Macros#

#define

app_btmesh_util_log_status_f (sc, ...)

Logs the btmesh API failures.

#define

APP_BTMESH_UTIL_COMPONENT_LOGGING undefined

This macro calculates the number of precompile logging enable request in the specific c file where the this header file is included from

#define

log_nl ()

#define

log (...)

#define

log_level (level, ...)

#define

log_debug (...)

#define

log_info (...)

#define

log_warning (...)

#define

log_error (...)

#define

log_critical (...)

#define

log_append (...)

#define

log_append_level (level, ...)

#define

log_append_debug (...)

#define

log_append_info (...)

#define

log_append_warning (...)

#define

log_append_error (...)

#define

log_append_critical (...)

#define

log_status_debug (sc)

#define

log_status_info (sc)

#define

log_status_warning (sc)

#define

log_status_error (sc)

#define

log_status_critical (sc)

#define

log_status_debug_f (sc, ...)

#define

log_status_info_f (sc, ...)

#define

log_status_warning_f (sc, ...)

#define

log_status_error_f (sc, ...)

#define

log_status_critical_f (sc, ...)

#define

log_status (sc)

#define

log_status_level (level, sc)

#define

log_status_f (sc, ...)

#define

log_status_level_f (level, sc, ...)

#define

log_btmesh_status_f (sc, ...)

#define

log_hexdump_debug (p_data, len)

#define

log_hexdump_info (p_data, len)

#define

log_hexdump_warning (p_data, len)

#define

log_hexdump_error (p_data, len)

#define

log_hexdump_critical (p_data, len)

#define

log_hexdump_level (level, p_data, len)

#define

log_hexdump_debug_s (separator, p_data, len)

#define

log_hexdump_info_s (separator, p_data, len)

#define

log_hexdump_warning_s (separator, p_data, len)

#define

log_hexdump_error_s (separator, p_data, len)

#define

log_hexdump_critical_s (separator, p_data, len)

#define

log_hexdump_level_s (level, separator, p_data, len)

#define

APP_BTMESH_UUID_64_STR_MAX_SIZE 24

Maximum size of UUID64 string representation with separators (including null char)

#define

NL APP_LOG_NL

#define

APP_BTMESH_UUID_64_TO_STRING (uuid_64, separator, uppercase)

Provides string representation of UUID64 in a compound literal

It is guaranteed that this macro returns a valid string even in case of invalid parameters.

Warnings

This macro calls app_btmesh_uuid_64_to_string function with a compound literal which means the lifetime of returned string representation is the same as the enclosing block so the return value shall not be referenced outside of the most enclosing block where this macro is called from. For example the macro value shall not be returned from the caller function.

This macro can be used in printf-like calls (e.g. log calls) directly because it returns a string under every circumstances and the lifetime of compound literal is not problematic if the value is passed as a parameter directly to another function.

Returns

String representation of UUID64 which has enclosing block lifetime

#define

SL_PROG_TO_PCT (_target, _progress)

Convert progress into percentage, based on target and current values

#define

SL_PROG_TO_PCT_INT (_target, _progress)

Convert progress into percentage, based on target and current values

#define

SL_ARRAY_LENGTH (array)

Calculates how many elements an array contains

#define

SLI_SILABS_CID_INT 0x02FF

Silicon Laboratories Company ID as integer

#define

SLI_SILABS_CID_STR_LE "\xFF\x02"

Silicon Laboratories Company ID as little-endian string

#define

SLI_SILABS_CID_STR_BE "\x02\xFF"

Silicon Laboratories Company ID as big-endian string

Function Documentation#

app_btmesh_nvm_init#

sl_status_t app_btmesh_nvm_init (void )

Parameters

Type	Direction	Argument Name	Description
void	N/A

Initializes the NVM interface.

Calls the default initializer of NVM3.

Returns

Status code

Return values

SL_STATUS_OK: In case of success
SL_STATUS_ALREADY_INITIALIZED: In case it was initialized earlier with parameters different from default

app_btmesh_nvm_read#

sl_status_t app_btmesh_nvm_read (uint16_t key, void * buf, size_t * len)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	key	Identifier of the data.
void *	[out]	buf	Buffer to the data to read.
size_t *	[inout]	len	Pointer to the length of the read data. As in input it takes the length of buffer. As an output it contains the length of the read data.

Reads data from NVM.

Returns

Status code

Return values

SL_STATUS_OK: In case of success
SL_STATUS_INVALID_STATE: In case NVM has not been initialized
SL_STATUS_INVALID_KEY: In case key is invalid
SL_STATUS_NOT_FOUND: In case key has not been found
SL_STATUS_INVALID_PARAMETER: In case any of the input parameters is invalid

app_btmesh_nvm_write#

sl_status_t app_btmesh_nvm_write (uint16_t key, const void * buf, size_t len)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	key	Identifier of the data.
const void *	[in]	buf	Buffer to the data to write.
size_t	[in]	len	Length of the data in the buffer.

Writes data into the NVM.

Returns

Status code

Return values

SL_STATUS_OK: In case of success
SL_STATUS_INVALID_STATE: In case NVM has not been initialized
SL_STATUS_FULL: In case NVM is full
SL_STATUS_NO_MORE_RESOURCE: In case NVM doesn't have the resources to store the data
SL_STATUS_FLASH_PROGRAM_FAILED: In case writing to NVM has failed
SL_STATUS_INVALID_PARAMETER: In case any of the input parameters is invalid

app_btmesh_nvm_erase#

sl_status_t app_btmesh_nvm_erase (uint16_t key)

Parameters

Type	Direction	Argument Name	Description
uint16_t	[in]	key	Identifier of the data.

Erases data from NVM.

Returns

Status code

Return values

SL_STATUS_OK: In case of success
SL_STATUS_INVALID_STATE: In case NVM has not been initialized
SL_STATUS_INVALID_KEY: In case key is invalid
SL_STATUS_NOT_FOUND: In case key has not been found
SL_STATUS_FLASH_PROGRAM_FAILED: In case writing to NVM has failed
SL_STATUS_INVALID_PARAMETER: In case any of the input parameters is invalid

app_btmesh_nvm_erase_all#

sl_status_t app_btmesh_nvm_erase_all (void )

Parameters

Type	Direction	Argument Name	Description
void	N/A

Erases all NVM data.

Returns

Status code

Return values

SL_STATUS_OK: In case of success
SL_STATUS_INVALID_STATE: In case NVM has not been initialized
SL_STATUS_INVALID_PARAMETER: In case any of the input parameters is invalid

app_btmesh_uuid_64_to_string#

const char * app_btmesh_uuid_64_to_string (char * buffer, uint32_t buffer_size, const sl_bt_uuid_64_t * uuid_64, char separator, bool uppercase)

Parameters

Type	Direction	Argument Name	Description
char *	[out]	buffer	Output buffer where the string representation is written
uint32_t	[in]	buffer_size	Size of output buffer
const sl_bt_uuid_64_t *	[in]	uuid_64	Input UUID64 which shall be converted to string
char	[in]	separator	Separator character to be used between two hex characters. If the separator is the null character then no separator is used.
bool	[in]	uppercase	If true hex characters are upper case otherwise lower case

Provides string representation of UUID64

It is guaranteed that this function returns a valid string even in case of invalid parameters.

Returns

Output buffer which contains the string representation of UUID64

Return values

INVALID: if an error occurs due to invalid parameters

app_btmesh_bytes_to_hex#

const char * app_btmesh_bytes_to_hex (char * buffer, uint32_t buffer_size, const uint8_t * bytes, uint32_t bytes_size, char separator, bool uppercase)

Parameters

Type	Direction	Argument Name	Description
char *	[out]	buffer	Output buffer where the hex representation is written
uint32_t	[in]	buffer_size	Size of output buffer
const uint8_t *	[in]	bytes	Input byte array which shall be converted to hex
uint32_t	[in]	bytes_size	Size of input byte array
char	[in]	separator	Separator character to be used between two hex characters. If the separator is the null character then no separator is used.
bool	[in]	uppercase	If true hex characters are upper case otherwise lower case

Provides hex representation of byte array as a string

It is guaranteed that this function returns a valid string even in case of invalid parameters.

Returns

Output buffer which contains the hex representation of byte array

Return values

INVALID: if an error occurs due to invalid parameters

Macro Definition Documentation#

app_btmesh_util_log_status_f#

#define app_btmesh_util_log_status_f

Value:

(sc, ...)

Logs the btmesh API failures.

There are two special errors which are related to missing model configuration. If the BT Mesh configurator (e.g. mobile app) does not bind application key to the model or does not configure the model publication data then publish or other API calls which leads to message sending fails. From the BT Mesh node perspective it can't be determined if the configurator missed these configuration steps on purpose or not so these errors are logged at a less severe log level.

APP_BTMESH_UTIL_COMPONENT_LOGGING#

#define APP_BTMESH_UTIL_COMPONENT_LOGGING

Value:

(SL_BTMESH_BLOB_STORAGE_LOGGING_CFG_VAL \

+ SL_BTMESH_BLOB_TRANSFER_CLIENT_LOGGING_CFG_VAL \

+ SL_BTMESH_BLOB_TRANSFER_SERVER_LOGGING_CFG_VAL \

+ SL_BTMESH_CTL_CLIENT_LOGGING_CFG_VAL \

+ SL_BTMESH_CTL_SERVER_LOGGING_CFG_VAL \

+ SL_BTMESH_FRIEND_LOGGING_CFG_VAL \

+ SL_BTMESH_FW_DIST_SERVER_LOGGING_CFG_VAL \

+ SL_BTMESH_FW_UPDATE_SERVER_LOGGING_CFG_VAL \

+ SL_BTMESH_GENERIC_LEVEL_CLIENT_EXT_LOGGING_CFG_VAL \

+ SL_BTMESH_GENERIC_ONOFF_SERVER_LOGGING_CFG_VAL \

+ SL_BTMESH_HSL_CLIENT_LOGGING_CFG_VAL \

+ SL_BTMESH_HSL_SERVER_LOGGING_CFG_VAL \

+ SL_BTMESH_IV_UPDATE_LOGGING_CFG_VAL \

+ SL_BTMESH_LC_SERVER_LOGGING_CFG_VAL \

+ SL_BTMESH_LIGHTING_CLIENT_LOGGING_CFG_VAL \

+ SL_BTMESH_LIGHTING_SERVER_LOGGING_CFG_VAL \

+ SL_BTMESH_LPN_LOGGING_CFG_VAL \

+ SL_BTMESH_PROVISIONEE_LOGGING_CFG_VAL \

+ SL_BTMESH_PROVISIONER_LOGGING_CFG_VAL \

+ SL_BTMESH_PROVISIONING_DECORATOR_LOGGING_CFG_VAL \

+ SL_BTMESH_REMOTE_PROVISIONING_CLIENT_LOGGING_CFG_VAL \

+ SL_BTMESH_REMOTE_PROVISIONING_SERVER_LOGGING_CFG_VAL \

+ SL_BTMESH_SCENE_CLIENT_LOGGING_CFG_VAL \

+ SL_BTMESH_SCHEDULER_SERVER_LOGGING_CFG_VAL \

+ SL_BTMESH_SELF_PROVISIONING_CLI_LOGGING_CFG_VAL \

+ SL_BTMESH_SENSOR_CLIENT_LOGGING_CFG_VAL \

+ SL_BTMESH_SENSOR_SERVER_LOGGING_CFG_VAL \

+ SL_BTMESH_TIME_SERVER_LOGGING_CFG_VAL \

+ SL_BTMESH_VENDOR_LOOPBACK_LOGGING_CFG_VAL)

This macro calculates the number of precompile logging enable request in the specific c file where the this header file is included from

log_nl#

#define log_nl

log#

#define log

log_level#

#define log_level

log_debug#

#define log_debug

log_info#

#define log_info

log_warning#

#define log_warning

log_error#

#define log_error

log_critical#

#define log_critical

log_append#

#define log_append

log_append_level#

#define log_append_level

log_append_debug#

#define log_append_debug

log_append_info#

#define log_append_info

log_append_warning#

#define log_append_warning

log_append_error#

#define log_append_error

log_append_critical#

#define log_append_critical

log_status_debug#

#define log_status_debug

Value:

(sc)

log_status_info#

#define log_status_info

Value:

(sc)

log_status_warning#

#define log_status_warning

Value:

(sc)

log_status_error#

#define log_status_error

Value:

(sc)

log_status_critical#

#define log_status_critical

Value:

(sc)

log_status_debug_f#

#define log_status_debug_f

Value:

(sc, ...)

log_status_info_f#

#define log_status_info_f

Value:

(sc, ...)

log_status_warning_f#

#define log_status_warning_f

Value:

(sc, ...)

log_status_error_f#

#define log_status_error_f

Value:

(sc, ...)

log_status_critical_f#

#define log_status_critical_f

Value:

(sc, ...)

log_status#

#define log_status

Value:

(sc)

log_status_level#

#define log_status_level

Value:

(level, sc)

log_status_f#

#define log_status_f

Value:

(sc, ...)

log_status_level_f#

#define log_status_level_f

Value:

(level, sc, ...)

log_btmesh_status_f#

#define log_btmesh_status_f

Value:

(sc, ...)

log_hexdump_debug#

#define log_hexdump_debug

log_hexdump_info#

#define log_hexdump_info

log_hexdump_warning#

#define log_hexdump_warning

log_hexdump_error#

#define log_hexdump_error

log_hexdump_critical#

#define log_hexdump_critical

log_hexdump_level#

#define log_hexdump_level

log_hexdump_debug_s#

#define log_hexdump_debug_s

log_hexdump_info_s#

#define log_hexdump_info_s

log_hexdump_warning_s#

#define log_hexdump_warning_s

log_hexdump_error_s#

#define log_hexdump_error_s

log_hexdump_critical_s#

#define log_hexdump_critical_s

log_hexdump_level_s#

#define log_hexdump_level_s

APP_BTMESH_UUID_64_STR_MAX_SIZE#

#define APP_BTMESH_UUID_64_STR_MAX_SIZE

Value:

Maximum size of UUID64 string representation with separators (including null char)

NL#

#define NL

Value:

APP_LOG_NL

APP_BTMESH_UUID_64_TO_STRING#

#define APP_BTMESH_UUID_64_TO_STRING

Value:

app_btmesh_uuid_64_to_string((char[APP_BTMESH_UUID_64_STR_MAX_SIZE]){ 0 }, \

sizeof((char[APP_BTMESH_UUID_64_STR_MAX_SIZE]){ 0 }), \

uuid_64, \

separator, \

uppercase)

Provides string representation of UUID64 in a compound literal

It is guaranteed that this macro returns a valid string even in case of invalid parameters.

Warnings

This macro calls app_btmesh_uuid_64_to_string function with a compound literal which means the lifetime of returned string representation is the same as the enclosing block so the return value shall not be referenced outside of the most enclosing block where this macro is called from. For example the macro value shall not be returned from the caller function.

Returns

String representation of UUID64 which has enclosing block lifetime

SL_PROG_TO_PCT#

#define SL_PROG_TO_PCT

Value:

(_target, _progress)

Convert progress into percentage, based on target and current values

SL_PROG_TO_PCT_INT#

#define SL_PROG_TO_PCT_INT

Value:

(_target, _progress)

Convert progress into percentage, based on target and current values

SL_ARRAY_LENGTH#

#define SL_ARRAY_LENGTH

Value:

(array)

Calculates how many elements an array contains

SLI_SILABS_CID_INT#

#define SLI_SILABS_CID_INT

Value:

0x02FF

Silicon Laboratories Company ID as integer

SLI_SILABS_CID_STR_LE#

#define SLI_SILABS_CID_STR_LE

Value:

"\xFF\x02"

Silicon Laboratories Company ID as little-endian string

SLI_SILABS_CID_STR_BE#

#define SLI_SILABS_CID_STR_BE

Value:

"\x02\xFF"

Silicon Laboratories Company ID as big-endian string