Descriptions

Describing a Data Model

Sensors typically create a binary blob that is sensor data serialized as a mix of data types. PolySync writes these blobs, unmodified, as plog payloads inside of ps_byte_array_msg, ps_can_frame_msg, ps_image_data_msg, and others. The job of the transcoder is to decode these blobs into meaningful numbers in a generic, flexible way, and possibly write them back out in a more useful format.

Think of the TOML library as a uniform way to model every message type from any sensor supported by PolySync, encapsulated all the special domain knowledge of each sensor and it's programming manual.

In addition to using a PolySync provided library of models, other TOML models may be easily written and modified in the field by users. This matters when the sensor is proprietary, or if the user just wants the description immediately, rather than wait for PolySync or some other third party to write the model.

In TOML, each model contains two sections: description, and detector.

Description

Descriptions are just an array of fields. Each field is either a table with exactly two required entries: name, and type, or something special like skip reserved or padding bytes. Extra metadata may also be described; at the moment, the supported metadata fields are endian, which can only equal the value big, and format, which can hold the value hex. Setting the endian field to big instructs the decoder to swap the byte order on a little endian processor. The format field allows specialization of how to print the value; right now only hex is supported but formatters for various time formats is planned.

[ibeo.header]
    description = [
        { name = "magic", type = "uint32", endian="big", format="hex" },
        { name = "prev_size", type = "uint32", endian="big" },
        { name = "size", type = "uint32", endian="big" },
        { skip = 1 },
        { name = "device_id", type = "uint8" },
        { name = "data_type", type = "uint16", endian="big", format = "hex" },
        { name = "time", "type" = "uint64", endian="big", format="hex" }
    ]
    detector = ...