Skip to main content

Lixel OpenAPI Manual · v1.1.0 · Page 3 of 15

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:

MarkerMeaningTopic segment
REQRequest (client → device)request
RSPResponse (device → client)response
RPTReport (device → client)report

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.

XGRIDS documentation, reproduced as published and captured on October 27, 2026. Read this page on docs.xgrids.com

Stuck on a Step?

QRC supports every scanner and software seat it sells. Send us the page you are on and we will walk you through it.

Contact Us
Request a Quote