Library API

This page describes the user-facing API to use this ThingSet library in an application.

Defines

THINGSET_BIN_GET: Function code for GET request in binary mode.

THINGSET_BIN_EXEC: Function code for EXEC request in binary mode.

THINGSET_BIN_DELETE: Function code for DELETE request in binary mode.

THINGSET_BIN_FETCH: Function code for FETCH request in binary mode.

THINGSET_BIN_CREATE: Function code for CREATE request in binary mode.

THINGSET_BIN_UPDATE: Function code for UPDATE request in binary mode.

THINGSET_BIN_DESIRE: Function code for DESIRE in binary mode.

THINGSET_BIN_REPORT: Function code for REPORT in binary mode.

THINGSET_TXT_GET_FETCH: Function code for GET and FETCH requests in text mode.

THINGSET_TXT_EXEC: Function code for EXEC request in text mode.

THINGSET_TXT_DELETE: Function code for DELETE request in text mode.

THINGSET_TXT_CREATE: Function code for CREATE request in text mode.

THINGSET_TXT_UPDATE: Function code for UPDATE request in text mode.

THINGSET_TXT_DESIRE: Function code for DESIRE in text mode.

THINGSET_TXT_REPORT: Function code for REPORT in text mode.

THINGSET_STATUS_CREATED: Response code for successful CREATE requests.

THINGSET_STATUS_DELETED: Response code for successful DELETE requests.

THINGSET_STATUS_CHANGED: Response code for successful EXEC/UPDATE requests.

THINGSET_STATUS_CONTENT: Response code for successful GET/FETCH requests.

THINGSET_ERR_BAD_REQUEST: Error code: Bad request.

THINGSET_ERR_UNAUTHORIZED: Error code: Authentication needed.

THINGSET_ERR_FORBIDDEN: Error code: Access forbidden.

THINGSET_ERR_NOT_FOUND: Error code: Data object not found.

THINGSET_ERR_METHOD_NOT_ALLOWED: Error code: Method not allowed.

THINGSET_ERR_REQUEST_INCOMPLETE: Error code: Request incomplete.

THINGSET_ERR_CONFLICT: Error code: Conflict.

THINGSET_ERR_REQUEST_TOO_LARGE: Error code: Request not fitting into buffer.

THINGSET_ERR_UNSUPPORTED_FORMAT: Error code: Format for an item not supported.

THINGSET_ERR_INTERNAL_SERVER_ERR: Error code: Generic catch-all response.

THINGSET_ERR_NOT_IMPLEMENTED: Error code: Request method not implemented.

THINGSET_ERR_GATEWAY_TIMEOUT: Error code: Node cannot be reached.

THINGSET_ERR_NOT_A_GATEWAY: Error code: Node is not a gateway.

THINGSET_ERR_RESPONSE_TOO_LARGE: Error code: Response not fitting into buffer.

THINGSET_ERR_DESERIALIZATION_FINISHED: Internal indication: Parsing finished.

THINGSET_ERROR(code): Check if provided code indicates an error.

THINGSET_SUCCESS(code): Check if provided code indicates success.

THINGSET_ID_ROOT: Root object for a node (empty path)

THINGSET_ID_TIME: Unix timestamp t_s

THINGSET_ID_IDS: _Ids overlay

THINGSET_ID_PATHS: _Paths overlay

THINGSET_ID_METADATAURL: URL for extended metadata information: cMetadataURL

THINGSET_ID_METADATA: _Metadata overlay

THINGSET_ID_NODEID: String containing the node ID: cNodeID

THINGSET_ITEM_BOOL(parent_id, id, name, bool_ptr, access, subsets)

Initialize struct thingset_data_object to expose bool variable via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
bool_ptr – Pointer to the bool variable
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_ITEM_UINT8(parent_id, id, name, uint8_ptr, access, subsets)

Initialize struct thingset_data_object to expose uint8_t variable via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
uint8_ptr – Pointer to the uint8_t variable
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_ITEM_INT8(parent_id, id, name, int8_ptr, access, subsets)

Initialize struct thingset_data_object to expose int8_t variable via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
int8_ptr – Pointer to the int8_t variable
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_ITEM_UINT16(parent_id, id, name, uint16_ptr, access, subsets)

Initialize struct thingset_data_object to expose uint16_t variable via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
uint16_ptr – Pointer to the uint16_t variable
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_ITEM_INT16(parent_id, id, name, int16_ptr, access, subsets)

Initialize struct thingset_data_object to expose int16_t variable via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
int16_ptr – Pointer to the int16_t variable
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_ITEM_UINT32(parent_id, id, name, uint32_ptr, access, subsets)

Initialize struct thingset_data_object to expose uint32_t variable via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
uint32_ptr – Pointer to the uint32_t variable
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_ITEM_INT32(parent_id, id, name, int32_ptr, access, subsets)

Initialize struct thingset_data_object to expose int32_t variable via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
int32_ptr – Pointer to the int32_t variable
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_ITEM_UINT64(parent_id, id, name, uint64_ptr, access, subsets)

Initialize struct thingset_data_object to expose uint64_t variable via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
uint64_ptr – Pointer to the uint64_t variable
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_ITEM_INT64(parent_id, id, name, int64_ptr, access, subsets)

Initialize struct thingset_data_object to expose int64_t variable via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
int64_ptr – Pointer to the int64_t variable
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_ITEM_FLOAT(parent_id, id, name, float_ptr, decimals, access, subsets)

Initialize struct thingset_data_object to expose float variable via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
float_ptr – Pointer to the float variable
decimals – Number of decimal digits to be serialized in text mode
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_ITEM_DECFRAC(parent_id, id, name, mantissa_ptr, decimals, access, subsets)

Initialize struct thingset_data_object to expose decimal fraction variable via ThingSet.

The mantissa is internally stored as int32_t. The value is converted into a float (JSON) or decimal fraction type (CBOR) for the protocol, based on the specified number of decimal digits.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
mantissa_ptr – Pointer to the int32_t variable
decimals – Number of decimal digits to be serialized in text mode
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_ITEM_STRING(parent_id, id, name, char_ptr, buf_size, access, subsets)

Initialize struct thingset_data_object to expose a null-terminated character string buffer via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
char_ptr – Pointer to the char buffer
buf_size – Maximum length of the buffer including the null-termination character
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_ITEM_BYTES(parent_id, id, name, bytes_ptr, access, subsets)

Initialize struct thingset_data_object to expose a byte buffer containing arbitrary binary data via ThingSet.

In contrast to string buffers, no null-termination is used.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
bytes_ptr – Pointer to the struct thingset_bytes object
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_FN_VOID(parent_id, id, name, void_fn_ptr, access)

Initialize struct thingset_data_object to expose a function with void return value as an executable item via ThingSet.

If the function should have input parameters, child object with this object as their parent_id have to be defined.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
void_fn_ptr – Pointer to the void function
access – Flags to define read/write access for this data object

THINGSET_FN_INT32(parent_id, id, name, int32_fn_ptr, access)

Initialize struct thingset_data_object to expose a function with int32_t return value as an executable item via ThingSet.

If the function should have input parameters, child object with this object as their parent_id have to be defined.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
int32_fn_ptr – Pointer to the int32_t function
access – Flags to define read/write access for this data object

THINGSET_ITEM_ARRAY(parent_id, id, name, array_ptr, access, subsets)

Initialize struct thingset_data_object to expose an array of simple values via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
array_ptr – Pointer to the struct thingset_array object
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_RECORDS(parent_id, id, name, records_ptr, access, subsets)

Initialize struct thingset_data_object to expose records of similar data via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
records_ptr – Pointer to the struct thingset_records object
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_DYN_RECORDS(parent_id, id, name, records_ptr, access, subsets)

Initialize struct thingset_data_object to expose dynamic records of similar data via ThingSet.

In contrast to normal records, dynamic records don’t keep the data for all records in memory. Instead, the data must be retrieved dynamically in the THINGSET_CALLBACK_PRE_READ callback and stored in the referenced struct object. This type of records can be used to store large amounts of data in an external flash or EEPROM and only read the data on demand.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
records_ptr – Pointer to the struct thingset_records object
access – Flags to define read/write access for this data object
subsets – Subset(s) this data object belongs to

THINGSET_SUBSET(parent_id, id, name, subset_flag, access)

Initialize struct thingset_data_object to expose a subset item via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
subset_flag – Single subset flag to be used
access – Flags to define read/write access for this data object

THINGSET_GROUP(parent_id, id, name, update_callback)

Initialize struct thingset_data_object to group hierarchical data via ThingSet.

Parameters:

parent_id – ID of the parent data object of type GROUP
id – ID of this data object
name – String literal with the data object name
update_callback – Pointer to a function to be called before/after read/write operations.

THINGSET_RECORD_ITEM_BOOL(parent_id, id, name, struct_type, struct_member)

Initialize struct thingset_data_object to expose bool record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type bool used for this item

THINGSET_RECORD_ITEM_UINT64(parent_id, id, name, struct_type, struct_member)

Initialize struct thingset_data_object to expose uint64_t record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type uint64_t used for this item

THINGSET_RECORD_ITEM_INT64(parent_id, id, name, struct_type, struct_member)

Initialize struct thingset_data_object to expose int64_t record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type int64_t used for this item

THINGSET_RECORD_ITEM_UINT32(parent_id, id, name, struct_type, struct_member)

Initialize struct thingset_data_object to expose uint32_t record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type uint32_t used for this item

THINGSET_RECORD_ITEM_INT32(parent_id, id, name, struct_type, struct_member)

Initialize struct thingset_data_object to expose int32_t record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type int32_t used for this item

THINGSET_RECORD_ITEM_UINT16(parent_id, id, name, struct_type, struct_member)

Initialize struct thingset_data_object to expose uint16_t record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type uint16_t used for this item

THINGSET_RECORD_ITEM_INT16(parent_id, id, name, struct_type, struct_member)

Initialize struct thingset_data_object to expose int16_t record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type int16_t used for this item

THINGSET_RECORD_ITEM_UINT8(parent_id, id, name, struct_type, struct_member)

Initialize struct thingset_data_object to expose uint8_t record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type uint8_t used for this item

THINGSET_RECORD_ITEM_INT8(parent_id, id, name, struct_type, struct_member)

Initialize struct thingset_data_object to expose int8_t record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type int8_t used for this item

THINGSET_RECORD_ITEM_FLOAT(parent_id, id, name, struct_type, struct_member, decimals)

Initialize struct thingset_data_object to expose float record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type float used for this item
decimals – Number of decimal digits to be serialized in text mode

THINGSET_RECORD_ITEM_DECFRAC(parent_id, id, name, struct_type, struct_member, decimals)

Initialize struct thingset_data_object to expose decimal fraction record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type int32_t used as the mantissa for this item
decimals – Number of decimal digits to be serialized in text mode

THINGSET_RECORD_ITEM_STRING(parent_id, id, name, struct_type, struct_member, buf_size)

Initialize struct thingset_data_object to expose a null-terminated character string buffer record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type char * used for this item
buf_size – Maximum length of the buffer including the null-termination character

THINGSET_RECORD_ITEM_ARRAY(parent_id, id, name, array_ptr)

Initialize struct thingset_data_object to expose an array record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
array_ptr – Pointer to the struct thingset_array object

THINGSET_RECORD_ITEM_RECORD(parent_id, id, name, records_ptr)

Initialize struct thingset_data_object to expose a nested record item.

Parameters:

parent_id – ID of the parent data object of type RECORDS
id – ID of this data object (same for all records of this kind)
name – String literal with the data object name
records_ptr – Pointer to the struct thingset_records object

THINGSET_ADD_ITEM_BOOL(parent_id, id, ...)

Add data item for bool variable to global iterable section.

See THINGSET_ITEM_BOOL for parameter description.

THINGSET_ADD_ITEM_UINT64(parent_id, id, ...)

Add data item for uint64_t variable to global iterable section.

See THINGSET_ITEM_UINT64 for parameter description.

THINGSET_ADD_ITEM_INT64(parent_id, id, ...)

Add data item for int64_t variable to global iterable section.

See THINGSET_ITEM_INT64 for parameter description.

THINGSET_ADD_ITEM_UINT32(parent_id, id, ...)

Add data item for uint32_t variable to global iterable section.

See THINGSET_ITEM_UINT32 for parameter description.

THINGSET_ADD_ITEM_INT32(parent_id, id, ...)

Add data item for int32_t variable to global iterable section.

See THINGSET_ITEM_INT32 for parameter description.

THINGSET_ADD_ITEM_UINT16(parent_id, id, ...)

Add data item for uint16_t variable to global iterable section.

See THINGSET_ITEM_UINT16 for parameter description.

THINGSET_ADD_ITEM_INT16(parent_id, id, ...)

Add data item for int16_t variable to global iterable section.

See THINGSET_ITEM_INT16 for parameter description.

THINGSET_ADD_ITEM_UINT8(parent_id, id, ...)

Add data item for uint8_t variable to global iterable section.

See THINGSET_ITEM_UINT8 for parameter description.

THINGSET_ADD_ITEM_INT8(parent_id, id, ...)

Add data item for int8_t variable to global iterable section.

See THINGSET_ITEM_INT8 for parameter description.

THINGSET_ADD_ITEM_FLOAT(parent_id, id, ...)

Add data item for float variable to global iterable section.

See THINGSET_ITEM_FLOAT for parameter description.

THINGSET_ADD_ITEM_DECFRAC(parent_id, id, ...)

Add data item for decimal fraction variable to global iterable section.

See THINGSET_ITEM_DECFRAC for parameter description.

THINGSET_ADD_ITEM_STRING(parent_id, id, ...)

Add data item for character string buffer to global iterable section.

See THINGSET_ITEM_STRING for parameter description.

THINGSET_ADD_ITEM_BYTES(parent_id, id, ...)

Add data item for byte string buffer to global iterable section.

See THINGSET_ITEM_BYTES for parameter description.

THINGSET_ADD_ITEM_ARRAY(parent_id, id, ...)

Add data item for an array to global iterable section.

See THINGSET_ITEM_ARRAY for parameter description.

THINGSET_ADD_FN_VOID(parent_id, id, ...)

Add executable item for void function to global iterable section.

See THINGSET_FN_VOID for parameter description.

THINGSET_ADD_FN_INT32(parent_id, id, ...)

Add executable item for int32_t function to global iterable section.

See THINGSET_FN_INT32 for parameter description.

THINGSET_ADD_SUBSET(parent_id, id, ...)

Add subset item to global iterable section.

See THINGSET_SUBSET for parameter description.

THINGSET_ADD_GROUP(parent_id, id, ...)

Add group data object to global iterable section.

See THINGSET_GROUP for parameter description.

THINGSET_ADD_RECORDS(parent_id, id, ...)

Add records object to global iterable section.

See THINGSET_RECORDS for parameter description.

THINGSET_ADD_DYN_RECORDS(parent_id, id, ...)

Add dynamic records object to global iterable section.

See THINGSET_DYN_RECORDS for parameter description.

THINGSET_ADD_RECORD_ITEM_BOOL(parent_id, id, ...)

Add record member of type bool to global iterable section.

See THINGSET_RECORD_ITEM_BOOL for parameter description.

THINGSET_ADD_RECORD_ITEM_UINT64(parent_id, id, ...)

Add record member of type uint64_t to global iterable section.

See THINGSET_RECORD_ITEM_UINT64 for parameter description.

THINGSET_ADD_RECORD_ITEM_INT64(parent_id, id, ...)

Add record member of type int64_t to global iterable section.

See THINGSET_RECORD_ITEM_INT64 for parameter description.

THINGSET_ADD_RECORD_ITEM_UINT32(parent_id, id, ...)

Add record member of type uint32_t to global iterable section.

See THINGSET_RECORD_ITEM_UINT32 for parameter description.

THINGSET_ADD_RECORD_ITEM_INT32(parent_id, id, ...)

Add record member of type int32_t to global iterable section.

See THINGSET_RECORD_ITEM_INT32 for parameter description.

THINGSET_ADD_RECORD_ITEM_UINT16(parent_id, id, ...)

Add record member of type uint16_t to global iterable section.

See THINGSET_RECORD_ITEM_UINT16 for parameter description.

THINGSET_ADD_RECORD_ITEM_INT16(parent_id, id, ...)

Add record member of type int16_t to global iterable section.

See THINGSET_RECORD_ITEM_INT16 for parameter description.

THINGSET_ADD_RECORD_ITEM_UINT8(parent_id, id, ...)

Add record member of type uint8_t to global iterable section.

See THINGSET_RECORD_ITEM_UINT8 for parameter description.

THINGSET_ADD_RECORD_ITEM_INT8(parent_id, id, ...)

Add record member of type int8_t to global iterable section.

See THINGSET_RECORD_ITEM_INT8 for parameter description.

THINGSET_ADD_RECORD_ITEM_FLOAT(parent_id, id, ...)

Add record member of type float to global iterable section.

See THINGSET_RECORD_ITEM_FLOAT for parameter description.

THINGSET_ADD_RECORD_ITEM_DECFRAC(parent_id, id, ...)

Add record member of type decimal fraction to global iterable section.

See THINGSET_RECORD_ITEM_DECFRAC for parameter description.

THINGSET_ADD_RECORD_ITEM_STRING(parent_id, id, ...)

Add record member of type char * to global iterable section.

See THINGSET_RECORD_ITEM_STRING for parameter description.

THINGSET_ADD_RECORD_ITEM_ARRAY(parent_id, id, ...)

Add record member of type array to global iterable section.

See THINGSET_RECORD_ITEM_ARRAY for parameter description.

THINGSET_ADD_RECORD_ITEM_RECORD(parent_id, id, ...)

Add record member of type record to global iterable section.

Seee THINGSET_RECORD_ITEM_RECORD for parameter description.

THINGSET_DEFINE_BYTES(var_name, buffer, used_bytes)

Define a struct thingset_bytes to be used with THINGSET_ITEM_BYTES

Parameters:

var_name – Name of the created variable of struct thingset_bytes
buffer – Existing uint8_t array (must be an array, pointer not allowed)
used_bytes – Currently used elements in the buffer

THINGSET_DEFINE_BOOL_ARRAY(var_name, array, used_elements)

Define a struct thingset_array to expose bool arrays with THINGSET_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
array – Existing fixed-size array of type bool (must be an array and not a pointer)
used_elements – Currently used elements in the array

THINGSET_DEFINE_UINT8_ARRAY(var_name, array, used_elements)

Define a struct thingset_array to expose uint8_t arrays with THINGSET_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
array – Existing fixed-size array of type uint8_t (must be an array and not a pointer)
used_elements – Currently used elements in the array

THINGSET_DEFINE_INT8_ARRAY(var_name, array, used_elements)

Define a struct thingset_array to expose int8_t arrays with THINGSET_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
array – Existing fixed-size array of type int8_t (must be an array and not a pointer)
used_elements – Currently used elements in the array

THINGSET_DEFINE_UINT16_ARRAY(var_name, array, used_elements)

Define a struct thingset_array to expose uint16_t arrays with THINGSET_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
array – Existing fixed-size array of type uint16_t (must be an array and not a pointer)
used_elements – Currently used elements in the array

THINGSET_DEFINE_INT16_ARRAY(var_name, array, used_elements)

Define a struct thingset_array to expose int16_t arrays with THINGSET_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
array – Existing fixed-size array of type int16_t (must be an array and not a pointer)
used_elements – Currently used elements in the array

THINGSET_DEFINE_UINT32_ARRAY(var_name, array, used_elements)

Define a struct thingset_array to expose uint32_t arrays with THINGSET_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
array – Existing fixed-size array of type uint32_t (must be an array and not a pointer)
used_elements – Currently used elements in the array

THINGSET_DEFINE_INT32_ARRAY(var_name, array, used_elements)

Define a struct thingset_array to expose int32_t arrays with THINGSET_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
array – Existing fixed-size array of type int32_t (must be an array and not a pointer)
used_elements – Currently used elements in the array

THINGSET_DEFINE_UINT64_ARRAY(var_name, array, used_elements)

Define a struct thingset_array to expose uint64_t arrays with THINGSET_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
array – Existing fixed-size array of type uint64_t (must be an array and not a pointer)
used_elements – Currently used elements in the array

THINGSET_DEFINE_INT64_ARRAY(var_name, array, used_elements)

Define a struct thingset_array to expose int64_t arrays with THINGSET_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
array – Existing fixed-size array of type int64_t (must be an array and not a pointer)
used_elements – Currently used elements in the array

THINGSET_DEFINE_FLOAT_ARRAY(var_name, decimals, array, used_elements)

Define a struct thingset_array to expose float arrays with THINGSET_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
decimals – Number of decimal digits to be serialized in text mode
array – Existing fixed-size array of type float (must be an array and not a pointer)
used_elements – Currently used elements in the array

THINGSET_DEFINE_DECFRAC_ARRAY(var_name, decimals, array, used_elements)

Define a struct thingset_array to expose decimal fraction arrays with THINGSET_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
decimals – Number of decimal digits to be serialized in text mode
array – Existing fixed-size array of type int32_t (must be an array and not a pointer)
used_elements – Currently used elements in the array

THINGSET_DEFINE_RECORD_BOOL_ARRAY(var_name, struct_type, struct_member)

Define a struct thingset_array to expose bool arrays with THINGSET_RECORD_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type bool array used for this item

THINGSET_DEFINE_RECORD_UINT8_ARRAY(var_name, struct_type, struct_member)

Define a struct thingset_array to expose uint8_t arrays with THINGSET_RECORD_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type uint8_t array used for this item

THINGSET_DEFINE_RECORD_INT8_ARRAY(var_name, struct_type, struct_member)

Define a struct thingset_array to expose int8_t arrays with THINGSET_RECORD_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type int8_t array used for this item

THINGSET_DEFINE_RECORD_UINT16_ARRAY(var_name, struct_type, struct_member)

Define a struct thingset_array to expose uint16_t arrays with THINGSET_RECORD_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type uint16_t array used for this item

THINGSET_DEFINE_RECORD_INT16_ARRAY(var_name, struct_type, struct_member)

Define a struct thingset_array to expose int16_t arrays with THINGSET_RECORD_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type int16_t array used for this item

THINGSET_DEFINE_RECORD_UINT32_ARRAY(var_name, struct_type, struct_member)

Define a struct thingset_array to expose uint32_t arrays with THINGSET_RECORD_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type uint32_t array used for this item

THINGSET_DEFINE_RECORD_INT32_ARRAY(var_name, struct_type, struct_member)

Define a struct thingset_array to expose int32_t arrays with THINGSET_RECORD_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type int32_t array used for this item

THINGSET_DEFINE_RECORD_UINT64_ARRAY(var_name, struct_type, struct_member)

Define a struct thingset_array to expose uint64_t arrays with THINGSET_RECORD_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type uint64_t array used for this item

THINGSET_DEFINE_RECORD_INT64_ARRAY(var_name, struct_type, struct_member)

Define a struct thingset_array to expose int64_t arrays with THINGSET_RECORD_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type int64_t array used for this item

THINGSET_DEFINE_RECORD_FLOAT_ARRAY(var_name, decimals, struct_type, struct_member)

Define a struct thingset_array to expose float arrays with THINGSET_RECORD_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
decimals – Number of decimal digits to be serialized in text mode
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type float array used for this item

THINGSET_DEFINE_RECORD_DECFRAC_ARRAY(var_name, decfrac, struct_type, struct_member)

Define a struct thingset_array to expose decimal fraction arrays with THINGSET_RECORD_ITEM_ARRAY

Parameters:

var_name – Name of the created struct thingset_array variable
decimals – Number of decimal digits to be serialized in text mode
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member of type int32_t array used for this item

THINGSET_DEFINE_RECORD_RECORDS(var_name, struct_type, struct_member)

Define a struct thingset_records to expose a nested array of records.

Parameters:

var_name – Name of the created struct thingset_records variable
struct_type – Type of the struct used for the records (e.g. struct my_record)
struct_member – Struct member used for this item

THINGSET_DEFINE_RECORDS(var_name, records, used_records)

Define a struct thingset_records to be used with THINGSET_RECORDS

Parameters:

var_name – Name of the created struct thingset_records variable
records – Existing fixed-size array of custom struct containing the records
used_records – Number of currently used records

THINGSET_DEFINE_DYN_RECORDS(var_name, record, available_records, callback)

Define a struct thingset_records to be used with THINGSET_DYN_RECORDS

Parameters:

var_name – Name of the created struct thingset_records variable
record – Pointer to existing struct object containing the dynamically created data
available_records – Number of available records
callback – Pointer to a function to be called before/after read/write operations.

THINGSET_NO_CALLBACK: No callback assigned to group

THINGSET_USR_R: Read-only access for normal user

THINGSET_EXP_R: Read-only access for expert user

THINGSET_MFR_R: Read-only access for manufacturer

THINGSET_ANY_R: Read-only access for any user

THINGSET_USR_W: Write-only access for normal user

THINGSET_EXP_W: Write-only access for expert user

THINGSET_MFR_W: Write-only access for manuf.

THINGSET_ANY_W: Write-only access for any user

THINGSET_USR_RW: Read/write access for normal user

THINGSET_EXP_RW: Read/write access for expert user

THINGSET_MFR_RW: Read/write access for manufacturer

THINGSET_ANY_RW: Read/write access for any user

THINGSET_ENDPOINT_INDEX_NONE: No index provided for endpoint

THINGSET_ENDPOINT_INDEX_NEW: Non-existent element behind the last element

THINGSET_CONTEXT_LOCK_TIMEOUT_MS

Typedefs

typedef uint16_t thingset_object_id_t: ThingSet data object ID (16-bit)

typedef void (*thingset_group_callback_t)(enum thingset_callback_reason cb_reason): Function to be called before/after read/write operations to groups.

typedef void (*thingset_records_callback_t)(enum thingset_callback_reason cb_reason, int index): Function to be called before/after read/write operations to records.

Enums

enum thingset_callback_reason

Indication for which reason a callback assigned to a group was called.

The reason is passed to the callback as a parameter, such that the application can perform desired actions, e.g. update data from ADC before it is read/serialized or write data to an EEPROM after it was written/deserialized.

Values:

enumerator THINGSET_CALLBACK_PRE_READ: Function was called before serializing data of the group

enumerator THINGSET_CALLBACK_POST_READ: Function was called after serializing data of the group

enumerator THINGSET_CALLBACK_PRE_WRITE: Function was called before deserializing data of the group

enumerator THINGSET_CALLBACK_POST_WRITE: Function was called after deserializing data of the group

enum thingset_data_format

Enum to define ThingSet data format (used by export/import and report functions).

Values:

enumerator THINGSET_TXT_NAMES_VALUES: Text names and values (JSON)

enumerator THINGSET_TXT_NAMES_ONLY: Text names only (JSON)

enumerator THINGSET_TXT_VALUES_ONLY: Text values only (JSON)

enumerator THINGSET_BIN_IDS_VALUES: Binary IDs and values (CBOR)

enumerator THINGSET_BIN_NAMES_VALUES: Binary names and values (CBOR)

enumerator THINGSET_BIN_IDS_ONLY: Binary IDs only (CBOR)

enumerator THINGSET_BIN_VALUES_ONLY: Binary values only (CBOR)

Functions

void thingset_init(struct thingset_context *ts, struct thingset_data_object *objects, size_t num_objects)

Initialize a ThingSet context.

Parameters:

ts – Pointer to ThingSet context.
objects – Pointer to array containing the ThingSet object database
num_objects – Number of elements in that array

void thingset_init_global(struct thingset_context *ts)

Initialize a ThingSet context using Zephyr iterable sections.

Data objects defined using THINGSET_ADD_* macros will be magically added to the object database by the linker.

Parameters:

ts – Pointer to ThingSet context.

int thingset_process_message(struct thingset_context *ts, const uint8_t *msg, size_t msg_len, uint8_t *rsp, size_t rsp_size)

Process ThingSet request or desire.

This function also detects if text mode (JSON) or binary mode (CBOR) is used.

The string in the buffer will be null-terminated in case of text mode, but the termination character is not included in the returned length.

Parameters:

ts – Pointer to ThingSet context.
msg – Pointer to the ThingSet message (request or desire)
msg_len – Length of the message
rsp – Pointer to the buffer where the response should be stored (if any)
rsp_size – Size of the response buffer

Return values:

rsp_len – Length of the response written to the buffer after processing a request
0 – If the message was empty or a desire was processed successfully (no response)
err – Negative ThingSet response code if a desire could not be processed successfully

int thingset_export_subsets(struct thingset_context *ts, uint8_t *buf, size_t buf_size, uint16_t subsets, enum thingset_data_format format)

Retrieve data for given subset(s).

This function does not return a complete ThingSet message, but only the payload data as a name/value map. It can be used e.g. to store data in the EEPROM or other non-volatile memory.

The string in the buffer will be null-terminated, but the termination character is not included in the returned length.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the data should be stored
buf_size – Size of the buffer, i.e. maximum allowed length of the data
subsets – Flags to select which subset(s) of data items should be exported
format – Protocol data format to be used (text, binary with IDs or binary with names)

Returns:

Actual length of the data or negative ThingSet response code in case of error.

int thingset_export_subsets_progressively(struct thingset_context *ts, uint8_t *buf, size_t buf_size, uint16_t subsets, enum thingset_data_format format, unsigned int *index, size_t *len)

EXPERIMENTAL

Exports object data for the given subset to the supplied buffer in the specified format starting at the given object index. At present, only binary formats are supported.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the data should be stored
buf_size – Size of the buffer, i.e. maximum allowed length of the data
subsets – Flags to select which subset(s) of data items should be exported
format – Protocol data format to be used (text, binary with IDs or binary with names)
index – Pointer to an integer which tracks the current object being exported
len – Number of bytes written to the buffer

Returns:

1 if there are more objects to export, 0 when complete or negative if an error.

int thingset_export_item(struct thingset_context *ts, uint8_t *buf, size_t buf_size, const struct thingset_data_object *obj, enum thingset_data_format format)

Export id, value and/or name of a single data item.

This function is typically used together with thingset_iterate_subsets to export items of a subset one by one, e.g. for publishing them via CAN.

The string in the buffer will be null-terminated, but the termination character is not included in the returned length.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the data should be stored
buf_size – Size of the buffer, i.e. maximum allowed length of the data
obj – Pointer to data item which should be exported
format – Protocol data format to be used (text, binary with IDs or binary with names)

Returns:

Actual length of the data or negative ThingSet response code in case of error.

struct thingset_data_object *thingset_iterate_subsets(struct thingset_context *ts, uint16_t subset, struct thingset_data_object *start_obj)

Iterate over all objects of given subset(s).

Parameters:

ts – Pointer to ThingSet context.
subsets – Flags to select which subset(s) of data items should be iterated over
start_obj – Data object to start searching (use NULL to start at the beginning)

Returns:

Pointer to the next object found or NULL if end of data objects was reached

int thingset_import_data(struct thingset_context *ts, const uint8_t *data, size_t len, uint8_t auth_flags, enum thingset_data_format format)

Import data into data objects.

This function can be used to initialize data objects from previously exported data (using thingset_export_subsets function) and stored in the EEPROM or other non-volatile memory.

Unknown data items are silently ignored.

Parameters:

ts – Pointer to ThingSet context.
data – Buffer containing ID/value map that should be written to the data objects
len – Length of the data in the buffer
auth_flags – Authentication flags to be used in this function (to override auth_flags)
format – Protocol data format to be used (text, binary with IDs or binary with names)

Returns:

0 for success or negative ThingSet response code in case of error

int thingset_import_data_progressively(struct thingset_context *ts, const uint8_t *data, size_t len, enum thingset_data_format format, uint8_t auth_flags, uint32_t *last_id, size_t *consumed)

EXPERIMENTAL

Import data from a buffer into data objects.

This function can be used to initialize data objects from previously exported data (using thingset_export_subsets function) and stored in the EEPROM or other non-volatile memory.

Unknown data items are silently ignored.

Parameters:

ts – Pointer to ThingSet context.
data – Buffer containing ID/value map that should be written to the data objects
len – Length of the data in the buffer
format – Protocol data format to be used (text, binary with IDs or binary with names)
auth_flags – Authentication flags to be used in this function (to override auth_flags)
last_id – ID of last object successfully processed. This must be 0 for the first call.
consumed – When the method returns, contains the number of bytes consumed. This may be less than size.

Returns:

0 for success, 1 if more data is required or negative ThingSet response code in case of error

int thingset_import_data_progressively_end(struct thingset_context *ts)

Completes the import of data from the buffer passed to thingset_begin_import_data_progressively into data objects. Call this method if an import completes without errors.

Parameters:

ts – Pointer to ThingSet context.

Returns:

0 for success

int thingset_import_record(struct thingset_context *ts, const uint8_t *data, size_t len, struct thingset_endpoint *endpoint, enum thingset_data_format format)

Import data into a record.

Unknown data items are silently ignored.

Parameters:

ts – Pointer to ThingSet context.
data – Buffer containing ID/value map that should be written to the record
len – Length of the data in the buffer
endpoint – Records endpoint (including index) to be used
format – Protocol data format to be used (text, binary with IDs or binary with names)

Returns:

0 for success or negative ThingSet response code in case of error

int thingset_report_path(struct thingset_context *ts, char *buf, size_t buf_size, const char *path, enum thingset_data_format format)

Generate a report for a given path.

The string in the buffer will be null-terminated, but the termination character is not included in the returned length.

Note

Searching the object database to find the path and items to be published based on the path provides the most user-friendly API, but is not the most efficient way to generate the report. A more efficient method which caches the pointers to the data objects may be added in the future.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the report should be stored
buf_size – Size of the buffer, i.e. maximum allowed length of the report
path – Path of subset/group/record to be published
format – Protocol data format to be used (text, binary with IDs or binary with names)

Returns:

Actual length of the report or negative ThingSet response code in case of error

void thingset_set_authentication(struct thingset_context *ts, uint8_t flags)

Set current authentication level.

The authentication flags must match with read/write access flags of the a data objects.

Parameters:

ts – Pointer to ThingSet context.
flags – Flags to define authentication level (1 = access allowed)

void thingset_set_update_callback(struct thingset_context *ts, const uint16_t subsets, void (*update_cb)(void))

Configure a callback for notification if data belonging to specified subset(s) was updated.

Parameters:

ts – Pointer to ThingSet context.
subsets – Flags to select which subset(s) of data items should be considered
update_cb – Callback to be called after an update.

int thingset_endpoint_by_path(struct thingset_context *ts, struct thingset_endpoint *endpoint, const char *path, size_t len)

Get the endpoint from a provided path.

Parameters:

ts – Pointer to ThingSet context.
endpoint – Pointer to the struct thingset_endpoint to store the result.
path – Relative path with multiple object names separated by forward slash.
len – Length of the entire path.

Returns:

0 if successful or negative ThingSet error code to be reported

int thingset_endpoint_by_id(struct thingset_context *ts, struct thingset_endpoint *endpoint, uint16_t id)

Get the endpoint from a provided ID.

Parameters:

ts – Pointer to ThingSet context.
endpoint – Pointer to the struct thingset_endpoint to store the result.
id – Numeric ID of the ThingSet object.

Returns:

0 if successful or negative ThingSet error code to be reported

struct thingset_bytes

#include <thingset.h>

Data structure to specify a binary data buffer

Public Members

uint8_t *bytes: Pointer to the bytes buffer

const uint16_t max_bytes: Maximum number of bytes in the buffer

uint16_t num_bytes: Actual number of bytes in the buffer

struct thingset_array

#include <thingset.h>

Data structure to specify an array data object

Public Members

const union thingset_data_pointer elements: Pointer to the first element of the array

enum thingset_type element_type: Type of the array elements (enum thingset_type)

const int16_t decimals: See detail in struct thingset_data_object

const uint16_t max_elements: Maximum number of elements in the array

uint16_t num_elements: Actual number of elements in the array

struct thingset_records

#include <thingset.h>

Data structure to specify records of an arbitrary struct

Public Members

const void *records: Pointer to the first record

const size_t record_size: Size of one record in bytes

const uint16_t max_records: Maximum number of records in the array

uint16_t num_records: Actual number of records in the array

thingset_records_callback_t callback

struct thingset_data_object

#include <thingset.h>

ThingSet data object struct.

Public Members

const thingset_object_id_t parent_id: ID of parent object

const thingset_object_id_t id: Data object ID

const char *name: Data object name

const union thingset_data_pointer data

Pointer to the variable containing the data. The variable type must match the type as specified.

For record items, the offset of this item inside the struct is stored (in bytes).

enum thingset_type type: One of THINGSET_TYPE_INT32, _FLOAT, …

const int32_t detail

Variable storing different detail information depending on the data type

FLOAT32: Decimal digits (precision) to use during serialization to JSON.
DECFRAC: Exponent for conversion between internal unit and unit exposed via ThingSet (equivalent to decimal digits for FLOAT32). Formula: internal value = 10^exponent * ThingSet value Example: If a voltage measurement is internally stored as an integer in mV, use exponent 3 to convert to the SI base unit V as exposed via ThingSet.
STRING: Size of the internal buffer in bytes.

const uint32_t access: Flags to define read/write access

MAYBE_CONST uint32_t subsets: Flags to assign data item to different data item subsets (e.g. for reports)

struct thingset_endpoint

#include <thingset.h>

Data to describe the endpoint parsed from a ThingSet request

Public Members

struct thingset_data_object *object: Pointer to the data object in memory (must never be NULL)

int32_t index: Index number or THINGSET_ENDPOINT_INDEX_NONE or THINGSET_ENDPOINT_INDEX_NEW

bool use_ids: Use names or IDs (relevant for binary mode)

struct thingset_context

#include <thingset.h>

ThingSet context.

Stores and handles all data objects exposed to different communication interfaces.

Public Members

struct thingset_data_object *data_objects: Array of objects database provided during initialization

size_t num_objects: Number of objects in the data_objects array

struct k_sem lock: Semaphore to lock this context and avoid race conditions if the context may be used by multiple threads in parallel.

const uint8_t *msg: Pointer to the incoming message buffer (request or desire, provided by process function)

size_t msg_len: Length of the incoming message

size_t msg_pos: Position in the message currently being parsed

const uint8_t *msg_payload: Pointer to the start of the payload in the message buffer

uint8_t *rsp: Pointer to the response buffer (provided by process function)

size_t rsp_size: Size of response buffer (i.e. maximum length)

size_t rsp_pos: Current position inside the response (equivalent to length of the response at end of processing)

struct thingset_api *api: Function pointers to mode-specific implementation (text or binary)

jsmntok_t tokens[CONFIG_THINGSET_NUM_JSON_TOKENS]: JSON tokens in msg_payload parsed by JSMN

size_t tok_count: Number of JSON tokens parsed by JSMN

size_t tok_pos: Current position of the parsing process

zcbor_state_t encoder[CONFIG_THINGSET_BINARY_MAX_DEPTH]: CBOR encoder states for binary mode

zcbor_state_t decoder[CONFIG_THINGSET_BINARY_MAX_DEPTH]: CBOR decoder states for binary mode

union thingset_context.[anonymous] [anonymous]: State information for data processing, either for text mode or binary mode depending on the assigned api.

uint8_t auth_flags: Stores current authentication status (authentication as “normal” user as default)

uint8_t update_subsets: Stores current authentication status (authentication as “normal” user as default)

void (*update_cb)(void): Callback to be called from patch function if a value belonging to update_subsets was changed

struct thingset_endpoint endpoint: Endpoint used for the current message