Library API

Defines

JSMN_HEADER

TS_GET: GET request

TS_POST: POST request

TS_DELETE: DELETE request

TS_FETCH: FETCH request

TS_PATCH: PATCH request (actually iPATCH equivalent in CBOR)

TS_STATEMENT: STATEMENT message

TS_STATUS_CREATED: Success status 0x81: Created

TS_STATUS_DELETED: Success status 0x82: Deleted

TS_STATUS_VALID: Success status 0x83: Valid

TS_STATUS_CHANGED: Success status 0x84: Changed

TS_STATUS_CONTENT: Success status 0x85: Content

TS_STATUS_BAD_REQUEST: Client error 0xA0: Bad Request

TS_STATUS_UNAUTHORIZED: Client error 0xA1: Authentication required

TS_STATUS_FORBIDDEN: Client error 0xA3: Forbidden to write read-only value

TS_STATUS_NOT_FOUND: Client error 0xA4: Not found

TS_STATUS_METHOD_NOT_ALLOWED: Client error 0xA5: Method not allowed

TS_STATUS_REQUEST_INCOMPLETE: Client error 0xA8: Request incomplete

TS_STATUS_CONFLICT: Client error 0xA9: Conflict

TS_STATUS_REQUEST_TOO_LARGE: Client error 0xAD: Request too large

TS_STATUS_UNSUPPORTED_FORMAT: Client error 0xAF: Unsupported format

TS_STATUS_INTERNAL_SERVER_ERR: Server error 0xC0: Internal server error

TS_STATUS_NOT_IMPLEMENTED: Server error 0xC1: Not implemented

TS_STATUS_RESPONSE_TOO_LARGE: ThingSet error 0xE1: Response too large

TS_ID_ROOT: Data Object ID for root element

TS_ID_TIME: Data Object ID for timestamp (t_s)

TS_ID_IDS: Data Object ID to determine IDs from paths (_ids)

TS_ID_PATHS: Data Object ID to determine paths from IDs (_paths)

TS_ID_METADATAURL: Data Object ID for Metadata URL (cMetadataURL)

TS_ID_NODEID: Data Object ID for node ID (cNodeID)

TS_CAN_SOURCE_POS

TS_CAN_SOURCE_MASK

TS_CAN_SOURCE_SET(addr)

TS_CAN_SOURCE_GET(id)

TS_CAN_TARGET_POS

TS_CAN_TARGET_MASK

TS_CAN_TARGET_SET(addr)

TS_CAN_TARGET_GET(id)

TS_CAN_ADDR_MAX

TS_CAN_ADDR_ANONYMOUS

TS_CAN_ADDR_BROADCAST

TS_CAN_DATA_ID_POS

TS_CAN_DATA_ID_MASK

TS_CAN_DATA_ID_SET(id)

TS_CAN_DATA_ID_GET(id)

TS_CAN_BUS_ID_POS

TS_CAN_BUS_ID_MASK

TS_CAN_BUS_ID_SET(id)

TS_CAN_BUS_ID_GET(id)

TS_CAN_BUS_ID_DEFAULT

TS_CAN_RAND_SET

TS_CAN_RAND_GET

TS_CAN_TYPE_POS

TS_CAN_TYPE_MASK

TS_CAN_TYPE_REQRESP

TS_CAN_TYPE_PUBSUB

TS_CAN_TYPE_NETWORK

TS_CAN_PRIO_POS

TS_CAN_PRIO_MASK

TS_CAN_PRIO_SET(prio)

TS_CAN_PRIO_GET(id)

TS_CAN_PRIO_CONTROL_EMERGENCY

TS_CAN_PRIO_CONTROL_HIGH

TS_CAN_PRIO_CONTROL_LOW

TS_CAN_PRIO_NETWORK_MGMT

TS_CAN_PRIO_PUBSUB_HIGH

TS_CAN_PRIO_REQRESP

TS_CAN_PRIO_PUBSUB_LOW

TS_CAN_CONTROL(id)

TS_CAN_PUBSUB(id)

TS_CAN_REQRESP(id)

MAYBE_CONST

ts_array_info

TS_ITEM_BOOL(id, name, bool_ptr, parent_id, access, subsets): Create data item for bool variable.

TS_ITEM_UINT64(id, name, uint64_ptr, parent_id, access, subsets): Create data item for uint64_t variable.

TS_ITEM_INT64(id, name, int64_ptr, parent_id, access, subsets): Create data item for int64_t variable.

TS_ITEM_UINT32(id, name, uint32_ptr, parent_id, access, subsets): Create data item for uint32_t variable.

TS_ITEM_INT32(id, name, int32_ptr, parent_id, access, subsets): Create data item for int32_t variable.

TS_ITEM_UINT16(id, name, uint16_ptr, parent_id, access, subsets): Create data item for uint16_t variable.

TS_ITEM_INT16(id, name, int16_ptr, parent_id, access, subsets): Create data item for int16_t variable.

TS_ITEM_UINT8(id, name, uint8_ptr, parent_id, access, subsets): Create data item for uint8_t variable.

TS_ITEM_INT8(id, name, int8_ptr, parent_id, access, subsets): Create data item for int8_t variable.

TS_ITEM_FLOAT(id, name, float_ptr, digits, parent_id, access, subsets): Create data item for float variable.

TS_ITEM_DECFRAC(id, name, mantissa_ptr, exponent, parent_id, access, subsets): Create data item for decimal fraction variable. 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 (fixed) exponent.

TS_ITEM_STRING(id, name, char_ptr, buf_size, parent_id, access, subsets): Create data item for a string buffer. The string must be null-terminated and buf_size contains the maximum length of the buffer including the null-termination character.

TS_ITEM_BYTES(id, name, bytes_buffer_ptr, buf_size, parent_id, access, subsets): Create data item for a byte buffer containing arbitrary binary data. In contrast to string buffers, no null-termination is used.

TS_FN_VOID(id, name, void_function_ptr, parent_id, access): Create an executable data object (function) with void return value.

TS_FN_INT32(id, name, int32_function_ptr, parent_id, access): Create an executable data object (function) with int32_t return value.

TS_ITEM_ARRAY(id, name, array_info_ptr, digits, parent_id, access, subsets): Create a data object pointing to a struct ts_array.

TS_RECORDS(id, name, records_ptr, parent_id, access, subsets): Create a data object pointing to a struct ts_array.

TS_SUBSET(id, name, subset, parent_id, access): Create a subset data object for the provided subset flag.

TS_GROUP(id, name, void_function_cb_ptr, parent_id): Create a group for hierarchical structuring of the data.

TS_RECORD_ITEM_BOOL(id, name, struct_type, struct_member, parent_id): struct related macros Create data item for bool variable.

TS_RECORD_ITEM_UINT64(id, name, struct_type, struct_member, parent_id): Create data item for uint64_t variable.

TS_RECORD_ITEM_INT64(id, name, struct_type, struct_member, parent_id): Create data item for int64_t variable.

TS_RECORD_ITEM_UINT32(id, name, struct_type, struct_member, parent_id): Create data item for uint32_t variable.

TS_RECORD_ITEM_INT32(id, name, struct_type, struct_member, parent_id): Create data item for int32_t variable.

TS_RECORD_ITEM_UINT16(id, name, struct_type, struct_member, parent_id): Create data item for uint16_t variable.

TS_RECORD_ITEM_INT16(id, name, struct_type, struct_member, parent_id): Create data item for int16_t variable.

TS_RECORD_ITEM_UINT8(id, name, struct_type, struct_member, parent_id): Create data item for uint8_t variable.

TS_RECORD_ITEM_INT8(id, name, struct_type, struct_member, parent_id): Create data item for int8_t variable.

TS_RECORD_ITEM_FLOAT(id, name, struct_type, struct_member, digits, parent_id): Create data item for float variable.

TS_RECORD_ITEM_DECFRAC(id, name, struct_type, struct_member, exponent, parent_id): Create data item for decimal fraction variable.

TS_RECORD_ITEM_STRING(id, name, struct_type, struct_member, buf_size, parent_id): Create data item for string variable.

TS_RECORD_ITEM_BYTES(id, name, struct_type, struct_member, buf_size, parent_id): Create data item for bytes variable.

TS_NO_CALLBACK: No callback assigned to group

TS_USR_R: Read-only access for normal user

TS_EXP_R: Read-only access for expert user

TS_MKR_R: Read-only access for maker

TS_ANY_R: Read-only access for any user

TS_USR_W: Write-only access for normal user

TS_EXP_W: Write-only access for expert user

TS_MKR_W: Write-only access for maker

TS_ANY_W: Write-only access for any user

TS_USR_RW: Read/write access for normal user

TS_EXP_RW: Read/write access for expert user

TS_MKR_RW: Read/write access for maker

TS_ANY_RW: Read/write access for any user

Typedefs

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

Enums

enum TsType

Internal C data types (used to cast void* pointers)

Values:

enumerator TS_T_BOOL: bool

enumerator TS_T_UINT64: uint64_t

enumerator TS_T_INT64: int64_t

enumerator TS_T_UINT32: uint32_t

enumerator TS_T_INT32: int32_t

enumerator TS_T_UINT16: uint16_t

enumerator TS_T_INT16: int16_t

enumerator TS_T_UINT8: uint8_t

enumerator TS_T_INT8: int8_t

enumerator TS_T_FLOAT32: float

enumerator TS_T_STRING: String buffer (UTF-8 text)

enumerator TS_T_BYTES: Byte buffer (binary data)

enumerator TS_T_ARRAY: Array

enumerator TS_T_RECORDS: Records (array of arbitrary struct object)

enumerator TS_T_DECFRAC: CBOR decimal fraction

enumerator TS_T_GROUP: Internal object to describe data hierarchy

enumerator TS_T_SUBSET: Subset of data items

enumerator TS_T_FN_VOID: Function with void return value

enumerator TS_T_FN_INT32: Function with int32_t return value

Functions

int ts_init(struct ts_context *ts, struct ts_data_object *data, size_t num)

Initialize a ThingSet context.

Parameters:

ts – Pointer to ThingSet context.
data – Pointer to array of ThingSetDataObject type containing the entire object database
num – Number of elements in that array

int ts_process(struct ts_context *ts, const uint8_t *request, size_t request_len, uint8_t *response, size_t response_size)

Process ThingSet request.

This function also detects if JSON or CBOR format is used

Parameters:

ts – Pointer to ThingSet context.
request – Pointer to the ThingSet request buffer
request_len – Length of the data in the request buffer
response – Pointer to the buffer where the ThingSet response should be stored
response_size – Size of the response buffer, i.e. maximum allowed length of the response

Returns:

Actual length of the response written to the buffer or 0 in case of error or if no response message has been generated (e.g. because a statement was processed)

void ts_dump_json(struct ts_context *ts, ts_object_id_t obj_id, int level)

Print all data objects as a structured JSON text to stdout.

WARNING: This is a recursive function and might cause stack overflows if run in constrained devices with large data object tree. Use with care and for testing only!

Parameters:

ts – Pointer to ThingSet context.
obj_id – Root object ID where to start with printing
level – Indentation level (=depth inside the data object tree)

void ts_set_authentication(struct ts_context *ts, uint8_t flags)

Sets current authentication level.

The authentication flags must match with access flags specified in ThingSetDataObject to allow read/write access to a data object.

Parameters:

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

void ts_set_update_callback(struct ts_context *ts, const uint16_t subsets, void (*update_cb)(void))

Configures 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 ts_txt_export(struct ts_context *ts, char *buf, size_t buf_size, uint16_t subsets)

Retrieve data in JSON format 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.

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

Returns:

Actual length of the data written to the buffer or 0 in case of error

int ts_txt_statement(struct ts_context *ts, char *buf, size_t buf_size, struct ts_data_object *object)

Generate statement message in JSON format based on pointer to group or subset.

This is the fastest method to generate a statement as it does not require to search through the entire data objects array.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the publication message should be stored
buf_size – Size of the message buffer, i.e. maximum allowed length of the message
object – Group or subset object specifying the items to be published

Returns:

Actual length of the message written to the buffer or 0 in case of error

int ts_txt_statement_by_path(struct ts_context *ts, char *buf, size_t buf_size, const char *path)

Generate statement message in JSON format based on path.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the publication message should be stored
buf_size – Size of the message buffer, i.e. maximum allowed length of the message
path – Path to group or subset object specifying the items to be published

Returns:

Actual length of the message written to the buffer or 0 in case of error

int ts_txt_statement_by_id(struct ts_context *ts, char *buf, size_t buf_size, ts_object_id_t id)

Generate statement message in JSON format based on data object ID.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the publication message should be stored
buf_size – Size of the message buffer, i.e. maximum allowed length of the message
id – ID of group or subset object specifying the items to be published

Returns:

Actual length of the message written to the buffer or 0 in case of error

int ts_txt_statement_record(struct ts_context *ts, char *buf, size_t buf_size, struct ts_data_object *object, int record_index)

Generate statement message in JSON format based on pointer to group or subset.

This is the fastest method to generate a statement as it does not require to search through the entire data objects array.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the publication message should be stored
buf_size – Size of the message buffer, i.e. maximum allowed length of the message
object – Records object with the data to be published
record_index – Element number extracted from path (only used for records).

Returns:

Actual length of the message written to the buffer or 0 in case of error

int ts_bin_export(struct ts_context *ts, uint8_t *buf, size_t buf_size, uint16_t subsets)

Retrieve data in CBOR format for given subset(s).

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

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

Returns:

Actual length of the data written to the buffer or 0 in case of error

int ts_bin_statement(struct ts_context *ts, uint8_t *buf, size_t buf_size, struct ts_data_object *object)

Generate statement message in CBOR format based on pointer to group or subset.

This is the fastest method to generate a statement as it avoids searching through the entire data objects array.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the publication message should be stored
buf_size – Size of the message buffer, i.e. maximum allowed length of the message
object – Group or subset object specifying the items to be published

Returns:

Actual length of the message written to the buffer or 0 in case of error

int ts_bin_statement_by_path(struct ts_context *ts, uint8_t *buf, size_t buf_size, const char *path)

Generate statement message in CBOR format based on path.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the publication message should be stored
buf_size – Size of the message buffer, i.e. maximum allowed length of the message
path – Path to group or subset object specifying the items to be published

Returns:

Actual length of the message written to the buffer or 0 in case of error

int ts_bin_statement_by_id(struct ts_context *ts, uint8_t *buf, size_t buf_size, ts_object_id_t id)

Generate statement message in CBOR format based on data object ID.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the publication message should be stored
buf_size – Size of the message buffer, i.e. maximum allowed length of the message
id – ID of group or subset object specifying the items to be published

Returns:

Actual length of the message written to the buffer or 0 in case of error

int ts_bin_pub_can(struct ts_context *ts, int *start_pos, uint16_t subset, uint8_t can_dev_id, uint32_t *msg_id, uint8_t *msg_data)

Encode a publication message in CAN message format for supplied data object.

The data may only be 8 bytes long. If the actual length of a object exceeds the available length, the object is silently ignored and the function continues with the next one.

Parameters:

ts – Pointer to ThingSet context.
start_pos – Position in data_objects array to start searching This value is updated with the next object found to allow iterating over all objects for this channel. It should be set to 0 to start from the beginning.
subset – Flag to select which subset of data items should be published
can_dev_id – Device ID on the CAN bus
msg_id – reference to can message id storage
msg_data – reference to the buffer where the publication message should be stored

Returns:

Actual length of the message_data or -1 if not encodable / in case of error

int ts_bin_import(struct ts_context *ts, const uint8_t *data, size_t len, uint8_t auth_flags, uint16_t subsets)

Import data in CBOR format into data objects.

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

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)
subsets – Flags to select which subset(s) of data items should be imported

Returns:

ThingSet status code

int ts_bin_import_record(struct ts_context *ts, const uint8_t *data, size_t len, uint8_t auth_flags, uint16_t subsets, struct ts_data_object *object, int record_index)

Import data in CBOR format as a record.

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
auth_flags – Authentication flags to be used in this function (to override _auth_flags)
subsets – Flags to select which subset(s) of data items should be imported
object – Records object with the data to be published
record_index – Index of the record to which the data should be written.

Returns:

ThingSet status code

struct ts_data_object *ts_get_object_by_id(struct ts_context *ts, ts_object_id_t id)

Get data object by ID.

Parameters:

ts – Pointer to ThingSet context.
id – Data object ID

Returns:

Pointer to data object or NULL if object is not found

struct ts_data_object *ts_get_object_by_name(struct ts_context *ts, const char *name, size_t len, int32_t parent)

Get data object by name.

As the names are not necessarily unique in the entire data tree, the parent is needed

Parameters:

ts – Pointer to ThingSet context.
name – Data object name
len – Length of the object name
parent – Data object ID of the parent or -1 for global search

Returns:

Pointer to data object or NULL if object is not found

struct ts_data_object *ts_get_object_by_path(struct ts_context *ts, const char *path, size_t len)

Get data object by path.

Get the endpoint object of a provided path.

Parameters:

ts – Pointer to ThingSet context.
path – Path with multiple object names separated by forward slash.
len – Length of the entire path

Returns:

Pointer to data object or NULL if object is not found

struct ts_bytes_buffer

#include <thingset.h>

Data structure to specify a binary data buffer

Public Members

uint8_t *bytes: Pointer to the buffer

uint16_t num_bytes: Actual number of bytes in the buffer

struct ts_array

#include <thingset.h>

Data structure to specify an array data object

Public Members

void *elements: Pointer to the first element of the array

uint16_t max_elements: Maximum number of elements in the array

uint16_t num_elements: Actual number of elements in the array

uint8_t type: Type of the array elements

uint8_t type_size: Size of the array element type in bytes

struct ts_records

#include <thingset.h>

Data structure to specify a record data object for an arbitrary struct

Public Members

const void *data: 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

struct ts_data_object

#include <thingset.h>

ThingSet data object struct.

Public Members

const ts_object_id_t id: Data object ID

const ts_object_id_t parent: ID of parent object

const char *name: Data object name

void *const 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).

const uint32_t type: One of TS_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 (10^exponent = factor to convert to internal unit). 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 or BYTES: 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 publication messages)

struct ts_context

#include <thingset.h>

ThingSet context.

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

Public Members

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

size_t num_objects: Number of objects in the data_objects array

const uint8_t *req: Pointer to request buffer (provided in process function)

size_t req_len: Length of the request

uint8_t *resp: Pointer to response buffer (provided in process function)

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

char *json_str: Pointer to the start of JSON payload in the request

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

int tok_count: Number of JSON tokens parsed by JSMN

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