Configuration Schema
====================

Codec configuration files are YAML mappings.  Each field name maps to a field
configuration, and each field configuration needs a ``codec`` key unless it is
created by ROS field inference.

.. code-block:: yaml

   field_name:
     codec: string
     max_length: 16

Common Field Keys
-----------------

``codec``
   Codec alias used to encode the field.  See :doc:`codec_aliases`.

``fields``
   Nested field mapping for ``dict`` and ``msg`` codecs.

``min_value`` and ``max_value``
   Numeric bounds used by integer and quantized float codecs.

``precision``
   Number of decimal places preserved by the ``float`` codec.

``resolution``
   Step size for ``linspace_float`` values.  ``linspace_float`` can also be
   configured with ``num_values`` or ``num_bits`` instead.

``num_bits``
   Fixed bit width for ``fixedint`` and ``padding``.

``max_length``
   Maximum number of characters, bytes, or array elements for variable-length
   codecs.

``length``
   Number of elements for ``fixed_len_array``.

``element_type``
   Codec alias used for array elements.

``element_params``
   Nested configuration passed to the element codec for an array.

``nullable``
   When true on ``variable_len_array``, an empty list is encoded as a single
   absent/present bit.

``target_fields``
   Field mapping controlled by an ``optional`` field.

``ros_type``
   ROS message type for ``msg`` fields.  ROS 1 and ROS 2 type names are
   accepted.

Structured Fields
-----------------

Nested dictionaries use ``fields``:

.. code-block:: yaml

   status:
     codec: dict
     fields:
       mode:
         codec: uint8
       label:
         codec: string
         max_length: 12

Nested ROS messages use ``ros_type`` and may optionally provide ``fields``:

.. code-block:: yaml

   point:
     codec: msg
     ros_type: geometry_msgs/Point
     fields:
       x:
         codec: float32
       y:
         codec: float32
       z:
         codec: float32

Arrays
------

Variable-length arrays include a length prefix:

.. code-block:: yaml

   samples:
     codec: variable_len_array
     max_length: 8
     element_type: uint16

Fixed-length arrays omit the length prefix:

.. code-block:: yaml

   orientation:
     codec: fixed_len_array
     length: 4
     element_type: float32

Array element codecs that require their own settings use ``element_params``:

.. code-block:: yaml

   names:
     codec: variable_len_array
     max_length: 4
     element_type: string
     element_params:
       max_length: 16

Arrays of ROS messages use ``element_type: msg``:

.. code-block:: yaml

   points:
     codec: variable_len_array
     max_length: 5
     element_type: msg
     element_params:
       ros_type: geometry_msgs/Point
       fields:
         x:
           codec: float32
         y:
           codec: float32
         z:
           codec: float32

Top-Level Options
-----------------

:py:class:`ltcodecs.dict_codec.DictCodec` and
:py:class:`ltcodecs.ros_message_codec.RosMessageCodec` accept an optional
``checksum`` argument.  Supported values are ``crc8`` and ``crc32``.

.. code-block:: python

   codec = ltcodecs.DictCodec(fields, checksum="crc32")

The checksum is appended after the payload and validated during decoding.