Link Search Menu Expand Document
Libertas Things Documentation

Data Structures

Mostly Generated Code

Most of the code is automatically generated with our tool to ensure correctness and manageability. In addition, we keep track of the standard and release updated code periodically.

The attribute sets and commands are defined as C structs.

The generated code either takes no space (pure definition) or a little static flash memory (a few KB to cover the entire universe of IoT, as metadata of the attributes and commands).

There are only about 2,000 lines of handwritten code. The design only exposes a total of only about a dozen API calls. It is functionally complete yet very simple and efficient (in terms of CPU and memory).

Constant Enumerations

Constants are generated as C enums.

  • libertas_thing_id - 16 bits integer. device types.
  • libertas_cluster_id - 16 bits integer. The ID of clusters.
  • libertas_attr_id - 16 bits integer. The ID of attributes within each cluster.
  • libertas_cmd_id - 8 bits integer. The ID of commands within each cluster.

“`c typedef enum libertas_thing_id { LIBERTAS_THING_ON_OFF_SWITCH = 0x0000, LIBERTAS_THING_LEVEL_CONTROL_SWITCH = 0x0001, // … }; typedef enum libertas_cluster_id { LIBERTAS_CLUSTER_GEN_BASIC = 0x0000, LIBERTAS_CLUSTER_GEN_POWER_CFG = 0x0001, // … }; typedef enum libertas_attr_id { LIBERTAS_ATTR_BASIC_ZCL_VERSION = 0x0000, LIBERTAS_ATTR_BASIC_APPL_VERSION = 0x0001, // … }; typedef enum libertas_cmd_id { LIBERTAS_CMD_BASIC_RESET_FACT_DEFAULT = 0x00, LIBERTAS_CMD_IDENTIFY = 0x00, // … }


# Attribute Set

"Libertas Cluster Library" standardized attribute presentation and storage. This data model MUST be followed!

The attributes are grouped into sets. Attribute values in each set share the same properties. For example, attributes that are configurations and shall be persisted in flash memory can be arranged within the same set.

Attributes with one cluster may be grouped within more than one set. Furthermore, each cluster has an "attribute sets" structure defined.

For example, the "General Basic" cluster contains three attributes grouped into two sets, as defined below.

"`c
BYTE_ALIGNED(
typedef struct libertas_attr_set_gen_basic {
    uint8_t zcl_version;
    uint8_t hw_version;
}) libertas_attr_set_gen_basic;

BYTE_ALIGNED(
typedef struct libertas_attr_set_gen_basic_persistent {
    uint8_t device_enabled;
}) libertas_attr_set_gen_basic_persistent;

typedef struct libertas_cluster_attr_sets_gen_basic {
    libertas_attr_set_gen_basic* gen_basic;
    libertas_attr_set_gen_basic_persistent* gen_basic_persistent;
} libertas_cluster_attr_sets_gen_basic;

Command Definition

The command data structure is more flexible than attributes. Libertas may not provide a declaration to every command. You may need to perform encoding and decoding commands independently as a developer.

Nevertheless, Libertas still standardize all command IDs within each cluster. Messages with an unknown command ID will be automatically rejected. It is essential to talk to us if you want to experiment with your new command IDs.

Below is the “Move to Level” command definition in the “Level Control” cluster. It commands the device (e.g., a dimmer) to move the current level to a specified level within the “transion_time” * 1/10 seconds.

“c BYTE_ALIGNED( typedef struct libertas_cmd_level_move_to_level { uint8_t level; uint16_t transion_time; }) libertas_cmd_level_move_to_level; ``

Naming conventions

The naming convention of different types is obvious from the source code header files.