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.

Return

The computed CRC16 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

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.

Return

The computed CRC8 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

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.

Return

The computed CRC16 value

Parameters
  • seed: Value to seed the CRC with

  • src: Input bytes for the computation

  • len: Length of the input in bytes

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

Return

The computed CRC16 value

Parameters
  • seed: Value to seed the CRC with

  • src: Input bytes for the computation

  • len: Length of the input in bytes

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.

Return

The computed CRC16 value

Parameters
  • src: Input bytes for the computation

  • len: Length of the input in bytes

uint32_t crc32_ieee(const uint8_t *data, size_t len)

Generate IEEE conform CRC32 checksum.

Return

CRC32 value.

Parameters
  • *data: Pointer to data on which the CRC should be calculated.

  • len: Data length.

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

Update an IEEE conforming CRC32 checksum.

Return

CRC32 value.

Parameters
  • crc: CRC32 checksum that needs to be updated.

  • *data: Pointer to data on which the CRC should be calculated.

  • len: Data length.

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.

Return

The computed CRC8 value

Parameters
  • initial_value: Initial value for the CRC computation

  • buf: Input bytes for the computation

  • len: Length of the input in bytes

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.

Return

The computed CRC7 value

Parameters
  • seed: Value to seed the CRC with

  • src: Input bytes for the computation

  • len: Length of the input in bytes

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

JSON_OBJ_DESCR_PRIM

Parameters
  • struct_: Struct packing the values.

  • json_field_name_: String, field name in JSON strings

  • struct_field_name_: Field name in the struct

  • type_: Token type for JSON value corresponding to a primitive type.

JSON_OBJ_DESCR_OBJECT_NAMED(struct_, json_field_name_, struct_field_name_, sub_descr_)

Variant of JSON_OBJ_DESCR_OBJECT 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

JSON_OBJ_DESCR_OBJECT

Parameters
  • struct_: Struct packing the values

  • json_field_name_: String, field name in JSON strings

  • struct_field_name_: Field name in the struct

  • sub_descr_: Array of json_obj_descr describing the subobject

JSON_OBJ_DESCR_ARRAY_NAMED(struct_, json_field_name_, struct_field_name_, max_len_, len_field_, elem_type_)

Variant of JSON_OBJ_DESCR_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.

See

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.

Return

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.

Parameters
  • bytes: Contents to write to the output

  • len: Number of bytes to append to output

  • data: User-provided pointer

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
enumerator JSON_TOK_TRUE
enumerator JSON_TOK_FALSE
enumerator JSON_TOK_NULL
enumerator JSON_TOK_ERROR
enumerator JSON_TOK_EOF

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).

Return

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

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

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.

Return

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

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

size_t json_calc_escaped_len(const char *str, size_t len)

Calculates the JSON-escaped string length.

Return

The length str would have if it were escaped

Parameters
  • str: The string to analyze

  • len: String size

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.

Return

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

Parameters
  • descr: Pointer to the descriptor array

  • descr_len: Number of elements in the descriptor array

  • val: Struct holding the values

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.

Return

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

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

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.

Return

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

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

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.

Return

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

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.

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.

Return

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

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.

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.

Return Value
  • 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().