Message Model & Codec

This page explains what a message goes through, from a dict in your code to the binary on the device, and back to the dict you receive.

Topic naming rules

All business topics use a three-segment scheme with the common prefix lixel/application/:

lixel/<domain>/<type>/<name>

• domain: business domain, mainly application.
• type: message direction.
  • request: client → device (request)
  • response: device → client (reply to a request)
  • report: device → client (active push)
• name: specific feature, e.g. device_info, modeling, lio_pose.

For example, to query device info, the request goes to lixel/application/request/device_info and the response comes from lixel/application/response/device_info.

Message payload

Except for the heartbeat, every message payload is Protobuf binary, with the proto package openapi.aiot_msgs. The heartbeat is the only message carried as JSON text, which makes it possible to discover a device and read the protocol version without parsing Protobuf.

Compiling the proto

Use the bundled script to compile the proto definition into a Python module:

python python/src/generate_proto.py

Note: generation uses the current environment's grpc_tools.protoc, keeping the gencode version consistent with the runtime protobuf version. At runtime it is recommended to set PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python to avoid C-extension incompatibilities across environments.

JSON ↔ Protobuf

The project's client wrapper provides ProtoCodec, based on google.protobuf.json_format, to convert between dict/JSON and Protobuf binary:

from example.core import ProtoCodec

codec = ProtoCodec()

# Encode: dict → Protobuf binary
data = codec.encode("DeviceControlRequest", {"action": "AC_SYSTEM_REBOOT"})

# Decode: Protobuf binary → dict
result = codec.decode("DeviceControlResponse", data)

# Generate a default template (with all fields)
template = codec.default_json("ModelingRequest")

Notes:

• Enum fields accept the enum name string (e.g. "AC_START") or the integer value.
• bytes fields appear as base64 strings in the dict.
• Field names keep the proto snake_case.

Message direction markers

The interface catalog uses three markers for the message direction, reused in later chapters:

Error carrier

Request-response messages carry the result in the Error error = 15 field of the response:

message Error {
    uint32 code = 1; // error code
    string desc = 2; // descriptor
}

For the error code categories and meanings, see Error Codes.