This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

Miscellaneous APIs¶

Checksum APIs¶

CRC¶

group crc

Functions

uint16_t crc16(const uint8_t *src, size_t len, uint16_t polynomial, uint16_t initial_value, bool pad)¶

Generic function for computing CRC 16.

Compute CRC 16 by passing in the address of the input, the input length and polynomial used in addition to the initial value.

Parameters

src – Input bytes for the computation
len – Length of the input in bytes
polynomial – The polynomial to use omitting the leading x^16 coefficient
initial_value – Initial value for the CRC computation
pad – Adds padding with zeros at the end of input bytes

Returns

The computed CRC16 value

uint8_t crc8(const uint8_t *src, size_t len, uint8_t polynomial, uint8_t initial_value, bool reversed)¶

Generic function for computing CRC 8.

Compute CRC 8 by passing in the address of the input, the input length and polynomial used in addition to the initial value.

Parameters

src – Input bytes for the computation
len – Length of the input in bytes
polynomial – The polynomial to use omitting the leading x^8 coefficient
initial_value – Initial value for the CRC computation
reversed – Should we use reflected/reversed values or not

Returns

The computed CRC8 value

uint16_t crc16_ccitt(uint16_t seed, const uint8_t *src, size_t len)¶

Compute the CRC-16/CCITT checksum of a buffer.

See ITU-T Recommendation V.41 (November 1988). Uses 0x1021 as the polynomial, reflects the input, and reflects the output.

To calculate the CRC across non-contiguous blocks use the return value from block N-1 as the seed for block N.

For CRC-16/CCITT, use 0 as the initial seed. Other checksums in the same family can be calculated by changing the seed and/or XORing the final value. Examples include:

X-25 (used in PPP): seed=0xffff, xor=0xffff, residual=0xf0b8

Note

API changed in Zephyr 1.11.

Parameters

seed – Value to seed the CRC with
src – Input bytes for the computation
len – Length of the input in bytes

Returns

The computed CRC16 value

uint16_t crc16_itu_t(uint16_t seed, const uint8_t *src, size_t len)¶

Compute the CRC-16/XMODEM checksum of a buffer.

The MSB first version of ITU-T Recommendation V.41 (November 1988). Uses 0x1021 as the polynomial with no reflection.

To calculate the CRC across non-contiguous blocks use the return value from block N-1 as the seed for block N.

For CRC-16/XMODEM, use 0 as the initial seed. Other checksums in the same family can be calculated by changing the seed and/or XORing the final value. Examples include:

CCIITT-FALSE: seed=0xffff
GSM: seed=0, xorout=0xffff, residue=0x1d0f

Parameters

seed – Value to seed the CRC with
src – Input bytes for the computation
len – Length of the input in bytes

Returns

The computed CRC16 value

static inline uint16_t crc16_ansi(const uint8_t *src, size_t len)¶

Compute ANSI variant of CRC 16.

ANSI variant of CRC 16 is using 0x8005 as its polynomial with the initial value set to 0xffff.

Parameters

src – Input bytes for the computation
len – Length of the input in bytes

Returns

The computed CRC16 value

uint32_t crc32_ieee(const uint8_t *data, size_t len)¶

Generate IEEE conform CRC32 checksum.

Parameters

*data – Pointer to data on which the CRC should be calculated.
len – Data length.

Returns

CRC32 value.

uint32_t crc32_ieee_update(uint32_t crc, const uint8_t *data, size_t len)¶

Update an IEEE conforming CRC32 checksum.

Parameters

crc – CRC32 checksum that needs to be updated.
*data – Pointer to data on which the CRC should be calculated.
len – Data length.

Returns

CRC32 value.

uint32_t crc32_c(uint32_t crc, const uint8_t *data, size_t len, bool first_pkt, bool last_pkt)¶

Calculate CRC32C (Castagnoli) checksum.

Parameters

crc – CRC32C checksum that needs to be updated.
*data – Pointer to data on which the CRC should be calculated.
len – Data length.
first_pkt – Whether this is the first packet in the stream.
last_pkt – Whether this is the last packet in the stream.

Returns

CRC32 value.

uint8_t crc8_ccitt(uint8_t initial_value, const void *buf, size_t len)¶

Compute CCITT variant of CRC 8.

Normal CCITT variant of CRC 8 is using 0x07.

Parameters

initial_value – Initial value for the CRC computation
buf – Input bytes for the computation
len – Length of the input in bytes

Returns

The computed CRC8 value

uint8_t crc7_be(uint8_t seed, const uint8_t *src, size_t len)¶

Compute the CRC-7 checksum of a buffer.

See JESD84-A441. Used by the MMC protocol. Uses 0x09 as the polynomial with no reflection. The CRC is left justified, so bit 7 of the result is bit 6 of the CRC.

Parameters

seed – Value to seed the CRC with
src – Input bytes for the computation
len – Length of the input in bytes

Returns

The computed CRC7 value

Structured Data APIs¶

JSON¶

group json

Defines

JSON_OBJ_DESCR_PRIM(struct_, field_name_, type_)¶

Helper macro to declare a descriptor for supported primitive values.

Here’s an example of use:

struct foo {
    int some_int;
};

struct json_obj_descr foo[] = {
    JSON_OBJ_DESCR_PRIM(struct foo, some_int, JSON_TOK_NUMBER),
};

Parameters

struct_ – Struct packing the values
field_name_ – Field name in the struct
type_ – Token type for JSON value corresponding to a primitive type. Must be one of: JSON_TOK_STRING for strings, JSON_TOK_NUMBER for numbers, JSON_TOK_TRUE (or JSON_TOK_FALSE) for booleans.

JSON_OBJ_DESCR_OBJECT(struct_, field_name_, sub_descr_)¶

Helper macro to declare a descriptor for an object value.

Here’s an example of use:

 struct nested {
     int foo;
     struct {
        int baz;
     } bar;
 };

 struct json_obj_descr nested_bar[] = {
     { ... declare bar.baz descriptor ... },
 };
 struct json_obj_descr nested[] = {
     { ... declare foo descriptor ... },
     JSON_OBJ_DESCR_OBJECT(struct nested, bar, nested_bar),
 };

Parameters

struct_ – Struct packing the values
field_name_ – Field name in the struct
sub_descr_ – Array of json_obj_descr describing the subobject

JSON_OBJ_DESCR_ARRAY(struct_, field_name_, max_len_, len_field_, elem_type_)¶

Helper macro to declare a descriptor for an array of primitives.

Here’s an example of use:

 struct example {
     int foo[10];
     size_t foo_len;
 };

 struct json_obj_descr array[] = {
      JSON_OBJ_DESCR_ARRAY(struct example, foo, 10, foo_len,
                           JSON_TOK_NUMBER)
 };

Parameters

struct_ – Struct packing the values
field_name_ – Field name in the struct
max_len_ – Maximum number of elements in array
len_field_ – Field name in the struct for the number of elements in the array
elem_type_ – Element type, must be a primitive type

JSON_OBJ_DESCR_OBJ_ARRAY(struct_, field_name_, max_len_, len_field_, elem_descr_, elem_descr_len_)¶

Helper macro to declare a descriptor for an array of objects.

Here’s an example of use:

 struct person_height {
     const char *name;
     int height;
 };

 struct people_heights {
     struct person_height heights[10];
     size_t heights_len;
 };

 struct json_obj_descr person_height_descr[] = {
      JSON_OBJ_DESCR_PRIM(struct person_height, name, JSON_TOK_STRING),
      JSON_OBJ_DESCR_PRIM(struct person_height, height, JSON_TOK_NUMBER),
 };

 struct json_obj_descr array[] = {
      JSON_OBJ_DESCR_OBJ_ARRAY(struct people_heights, heights, 10,
                               heights_len, person_height_descr,
                               ARRAY_SIZE(person_height_descr)),
 };

Parameters

struct_ – Struct packing the values
field_name_ – Field name in the struct containing the array
max_len_ – Maximum number of elements in the array
len_field_ – Field name in the struct for the number of elements in the array
elem_descr_ – Element descriptor, pointer to a descriptor array
elem_descr_len_ – Number of elements in elem_descr_

JSON_OBJ_DESCR_ARRAY_ARRAY(struct_, field_name_, max_len_, len_field_, elem_descr_, elem_descr_len_)¶

Helper macro to declare a descriptor for an array of array.

Here’s an example of use:

 struct person_height {
     const char *name;
     int height;
 };

 struct person_heights_array {
     struct person_height heights;
 }

 struct people_heights {
     struct person_height_array heights[10];
     size_t heights_len;
 };

 struct json_obj_descr person_height_descr[] = {
     JSON_OBJ_DESCR_PRIM(struct person_height, name, JSON_TOK_STRING),
     JSON_OBJ_DESCR_PRIM(struct person_height, height, JSON_TOK_NUMBER),
 };

 struct json_obj_descr person_height_array_descr[] = {
     JSON_OBJ_DESCR_OBJECT(struct person_heights_array,
                           heights, person_heigth_descr),
 };

 struct json_obj_descr array_array[] = {
      JSON_OBJ_DESCR_ARRAY_ARRAY(struct people_heights, heights, 10,
                                 heights_len, person_height_array_descr,
                                 ARRAY_SIZE(person_height_array_descr)),
 };

Parameters

struct_ – Struct packing the values
field_name_ – Field name in the struct containing the array
max_len_ – Maximum number of elements in the array
len_field_ – Field name in the struct for the number of elements in the array
elem_descr_ – Element descriptor, pointer to a descriptor array
elem_descr_len_ – Number of elements in elem_descr_

JSON_OBJ_DESCR_PRIM_NAMED(struct_, json_field_name_, struct_field_name_, type_)¶

Variant of JSON_OBJ_DESCR_PRIM that can be used when the structure and JSON field names differ.

This is useful when the JSON field is not a valid C identifier.

See also

JSON_OBJ_DESCR_ARRAY

Parameters

struct_ – Struct packing the values
json_field_name_ – String, field name in JSON strings
struct_field_name_ – Field name in the struct
max_len_ – Maximum number of elements in array
len_field_ – Field name in the struct for the number of elements in the array
elem_type_ – Element type, must be a primitive type

JSON_OBJ_DESCR_OBJ_ARRAY_NAMED(struct_, json_field_name_, struct_field_name_, max_len_, len_field_, elem_descr_, elem_descr_len_)¶

Variant of JSON_OBJ_DESCR_OBJ_ARRAY that can be used when the structure and JSON field names differ.

This is useful when the JSON field is not a valid C identifier.

Here’s an example of use:

 struct person_height {
     const char *name;
     int height;
 };

 struct people_heights {
     struct person_height heights[10];
     size_t heights_len;
 };

 struct json_obj_descr person_height_descr[] = {
      JSON_OBJ_DESCR_PRIM(struct person_height, name, JSON_TOK_STRING),
      JSON_OBJ_DESCR_PRIM(struct person_height, height, JSON_TOK_NUMBER),
 };

 struct json_obj_descr array[] = {
      JSON_OBJ_DESCR_OBJ_ARRAY_NAMED(struct people_heights,
                                     "people-heights", heights,
                                     10, heights_len,
                                     person_height_descr,
                                     ARRAY_SIZE(person_height_descr)),
 };

Parameters

struct_ – Struct packing the values
json_field_name_ – String, field name of the array in JSON strings
struct_field_name_ – Field name in the struct containing the array
max_len_ – Maximum number of elements in the array
len_field_ – Field name in the struct for the number of elements in the array
elem_descr_ – Element descriptor, pointer to a descriptor array
elem_descr_len_ – Number of elements in elem_descr_

Typedefs

typedef int (*json_append_bytes_t)(const char *bytes, size_t len, void *data)¶

Function pointer type to append bytes to a buffer while encoding JSON data.

Parameters

bytes – Contents to write to the output
len – Number of bytes to append to output
data – User-provided pointer

Returns

This callback function should return a negative number on error (which will be propagated to the return value of json_obj_encode()), or 0 on success.

Enums

enum json_tokens¶

Values:

enumerator JSON_TOK_NONE = '_'¶

enumerator JSON_TOK_OBJECT_START = '{'¶

enumerator JSON_TOK_OBJECT_END = '}'¶

enumerator JSON_TOK_LIST_START = '['¶

enumerator JSON_TOK_LIST_END = ']'¶

enumerator JSON_TOK_STRING = '"'¶

enumerator JSON_TOK_COLON = ':'¶

enumerator JSON_TOK_COMMA = ','¶

enumerator JSON_TOK_NUMBER = '0'¶

enumerator JSON_TOK_TRUE = 't'¶

enumerator JSON_TOK_FALSE = 'f'¶

enumerator JSON_TOK_NULL = 'n'¶

enumerator JSON_TOK_ERROR = '!'¶

enumerator JSON_TOK_EOF = '\0'¶

Functions

int json_obj_parse(char *json, size_t len, const struct json_obj_descr *descr, size_t descr_len, void *val)¶

Parses the JSON-encoded object pointer to by json, with size len, according to the descriptor pointed to by descr. Values are stored in a struct pointed to by val. Set up the descriptor like this:

struct s { int foo; char *bar; } struct json_obj_descr descr[] = { JSON_OBJ_DESCR_PRIM(struct s, foo, JSON_TOK_NUMBER), JSON_OBJ_DESCR_PRIM(struct s, bar, JSON_TOK_STRING), };

Since this parser is designed for machine-to-machine communications, some liberties were taken to simplify the design: (1) strings are not unescaped (but only valid escape sequences are accepted); (2) no UTF-8 validation is performed; and (3) only integer numbers are supported (no strtod() in the minimal libc).

Parameters

json – Pointer to JSON-encoded value to be parsed
len – Length of JSON-encoded value
descr – Pointer to the descriptor array
descr_len – Number of elements in the descriptor array. Must be less than 31 due to implementation detail reasons (if more fields are necessary, use two descriptors)
val – Pointer to the struct to hold the decoded values

Returns

< 0 if error, bitmap of decoded fields on success (bit 0 is set if first field in the descriptor has been properly decoded, etc).

ssize_t json_escape(char *str, size_t *len, size_t buf_size)¶

Escapes the string so it can be used to encode JSON objects.

Parameters

str – The string to escape; the escape string is stored the buffer pointed to by this parameter
len – Points to a size_t containing the size before and after the escaping process
buf_size – The size of buffer str points to

Returns

0 if string has been escaped properly, or -ENOMEM if there was not enough space to escape the buffer

size_t json_calc_escaped_len(const char *str, size_t len)¶

Calculates the JSON-escaped string length.

Parameters

str – The string to analyze
len – String size

Returns

The length str would have if it were escaped

ssize_t json_calc_encoded_len(const struct json_obj_descr *descr, size_t descr_len, const void *val)¶

Calculates the string length to fully encode an object.

Parameters

descr – Pointer to the descriptor array
descr_len – Number of elements in the descriptor array
val – Struct holding the values

Returns

Number of bytes necessary to encode the values if >0, an error code is returned.

int json_obj_encode_buf(const struct json_obj_descr *descr, size_t descr_len, const void *val, char *buffer, size_t buf_size)¶

Encodes an object in a contiguous memory location.

Parameters

descr – Pointer to the descriptor array
descr_len – Number of elements in the descriptor array
val – Struct holding the values
buffer – Buffer to store the JSON data
buf_size – Size of buffer, in bytes, with space for the terminating NUL character

Returns

0 if object has been successfully encoded. A negative value indicates an error (as defined on errno.h).

int json_arr_encode_buf(const struct json_obj_descr *descr, const void *val, char *buffer, size_t buf_size)¶

Encodes an array in a contiguous memory location.

Parameters

descr – Pointer to the descriptor array
val – Struct holding the values
buffer – Buffer to store the JSON data
buf_size – Size of buffer, in bytes, with space for the terminating NUL character

Returns

0 if object has been successfully encoded. A negative value indicates an error (as defined on errno.h).

int json_obj_encode(const struct json_obj_descr *descr, size_t descr_len, const void *val, json_append_bytes_t append_bytes, void *data)¶

Encodes an object using an arbitrary writer function.

Parameters

descr – Pointer to the descriptor array
descr_len – Number of elements in the descriptor array
val – Struct holding the values
append_bytes – Function to append bytes to the output
data – Data pointer to be passed to the append_bytes callback function.

Returns

0 if object has been successfully encoded. A negative value indicates an error.

int json_arr_encode(const struct json_obj_descr *descr, const void *val, json_append_bytes_t append_bytes, void *data)¶

Encodes an array using an arbitrary writer function.

Parameters

descr – Pointer to the descriptor array
val – Struct holding the values
append_bytes – Function to append bytes to the output
data – Data pointer to be passed to the append_bytes callback function.

Returns

0 if object has been successfully encoded. A negative value indicates an error.

struct json_obj_descr¶: #include <json.h>

JWT¶

JSON Web Tokens (JWT) are an open, industry standard [RFC 7519](https://tools.ietf.org/html/rfc7519) method for representing claims securely between two parties. Although JWT is fairly flexible, this API is limited to creating the simplistic tokens needed to authenticate with the Google Core IoT infrastructure.

group jwt

JSON Web Token (JWT)

Functions

int jwt_init_builder(struct jwt_builder *builder, char *buffer, size_t buffer_size)¶

Initialize the JWT builder.

Initialize the given JWT builder for the creation of a fresh token. The buffer size should at least be as long as JWT_BUILDER_MAX_SIZE returns.

Parameters

builder – The builder to initialize.
buffer – The buffer to write the token to.
buffer_size – The size of this buffer. The token will be NULL terminated, which needs to be allowed for in this size.

Returns

0 – Success
-ENOSPC – Buffer is insufficient to initialize

int jwt_add_payload(struct jwt_builder *builder, int32_t exp, int32_t iat, const char *aud)¶: add JWT primary payload.

int jwt_sign(struct jwt_builder *builder, const char *der_key, size_t der_key_len)¶: Sign the JWT token.

static inline size_t jwt_payload_len(struct jwt_builder *builder)¶

struct jwt_builder¶

#include <jwt.h>

JWT data tracking.

JSON Web Tokens contain several sections, each encoded in base-64. This structure tracks the token as it is being built, including limits on the amount of available space. It should be initialized with jwt_init().

Public Members

char *base¶: The base of the buffer we are writing to.

char *buf¶: The place in this buffer where we are currently writing.

size_t len¶: The length remaining to write.

bool overflowed¶: Flag that is set if we try to write past the end of the buffer. If set, the token is not valid.