Chapter 16 — CDI (Configuration Description Information)

CDI is an XML document that describes a node's configuration memory layout. It allows configuration tools to automatically generate user interfaces for reading and writing node settings, without requiring tool-specific knowledge of each device type.

CDI data location: The CDI byte array is stored in the node's parameters->cdi[] field (typically in flash/ROM) and served via datagram reads from address space 0xFF.

16.1 What CDI Is

CDI is a self-description mechanism. Each node carries an XML document that tells a configuration tool:

What configuration variables exist (name, type, size, offset).
How they are organized into groups and segments.
What descriptions and default values apply.
Which address space each segment maps to.

A configuration tool reads the CDI, parses the XML, and presents a form-based UI to the user. Reads and writes to configuration memory are performed through the Datagram Protocol (Chapter 14).

16.2 Address Space 0xFF

CDI data is served from address space 0xFF (Configuration Description Information). When a configuration tool reads from space 0xFF, the datagram handler routes the request to the CDI read callback, which returns bytes from the node's parameters->cdi[] array.

sequenceDiagram participant Tool as Config Tool participant Node participant Datagram as Datagram Handler participant CDI as CDI Data (flash) Tool->>Node: Datagram Read (space=0xFF, addr=0, count=64) Node->>Datagram: Route to space 0xFF handler Datagram->>CDI: Read bytes from cdi[] array CDI-->>Datagram: 64 bytes of XML Datagram-->>Node: Datagram Read Reply OK Node-->>Tool: Response datagram (XML bytes) Note over Tool: Repeat until all CDI read

The CDI address space is read-only. Its properties are defined in the node's parameters->address_space_configuration_definition structure:

Property	Value
Space ID	0xFF
Read-only	Yes
Highest address	Length of CDI data - 1

16.3 CDI XML Structure

A CDI document follows the OpenLCB CDI schema. The key elements are:

<?xml version="1.0" encoding="utf-8"?>
<cdi xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="...">

  <identification>
    <manufacturer>...</manufacturer>
    <model>...</model>
    <hardwareVersion>...</hardwareVersion>
    <softwareVersion>...</softwareVersion>
  </identification>

  <acdi/>

  <segment space="0xFE" origin="0">
    <group>
      <name>User Settings</name>
      <int size="1">
        <name>Option A</name>
        <default>0</default>
      </int>
      <string size="32">
        <name>Label</name>
      </string>
    </group>
  </segment>

</cdi>

Element	Purpose
`<identification>`	Manufacturer, model, and version strings (mirrors SNIP data).
`<acdi/>`	Marker indicating ACDI user name/description fields are present.
`<segment>`	Maps to an address space. The `space` attribute identifies which space (e.g., 0xFE for configuration memory).
`<group>`	Logical grouping of variables (displayed as a section in the UI).
`<int>`	Integer variable with a given byte size.
`<string>`	String variable with a given byte size.
`<eventid>`	8-byte Event ID variable.

16.4 Relationship to Configuration Memory

CDI describes the layout; the actual data lives in configuration memory (address space 0xFE). The CDI tells a tool that "byte offset 0 is a 1-byte integer named Option A." The tool then uses Datagram Read/Write commands to address space 0xFE to access that byte.

flowchart LR A["CDI (space 0xFF)\nDescribes layout"] --> B["Config Memory (space 0xFE)\nStores actual values"] C["Config Tool"] --> A C --> B style A fill:#4a90d9,color:#fff style B fill:#27ae60,color:#fff

The CDI is read once by the configuration tool to build its UI. Subsequent reads and writes target configuration memory directly. The CDI itself is never written to by external tools (it is read-only in flash).

16.5 CDI Storage in This Implementation

The CDI byte array is defined by the application and referenced through the node parameters structure:

typedef struct node_parameters_TAG {
    ...
    uint8_t cdi[USER_DEFINED_CDI_LENGTH];
    ...
    user_address_space_info_t address_space_configuration_definition; // Space 0xFF
    ...
} node_parameters_t;

The USER_DEFINED_CDI_LENGTH macro controls the size of the CDI array. It must be defined in the application's openlcb_user_config.h. The CDI content is typically a C string literal stored as a const byte array in flash memory.

Application-defined: The library does not generate CDI automatically. The application developer must create the XML content that matches their configuration memory layout. Any mismatch between the CDI and the actual memory layout will cause configuration tools to read/write incorrect addresses.

16.6 FDI (Function Definition Information)

Train nodes also carry an FDI document in parameters->fdi[], served from address space 0xFA. FDI describes the train's available functions (headlight, bell, horn, etc.) using a similar XML schema. The FDI array size is controlled by USER_DEFINED_FDI_LENGTH.