Tools & Ecosystem

HCDF CLI (Rust)

The hcdf command-line tool provides XML and JSON conversion, file inspection, and schema analysis. It is a single compiled binary with no runtime dependencies.

hcdf convert -i file.hcdf -o file.json converts XML to JSON
hcdf convert -i file.json -o file.hcdf --xsd hcdf.xsd converts JSON back to XML (lossless roundtrip)
hcdf info file.hcdf prints a summary: component count, joints, networks, sensors, motors
hcdf schema --xsd hcdf.xsd reports type and enum counts

The converter uses a generic tree-walking approach (not hardcoded structs) so it automatically supports any schema changes without recompilation. JSON to XML conversion is XSD-aware: it reads the schema to correctly distinguish attributes from child elements, handling type inheritance and mixed content types.

Build from source:

cd tools/hcdf-cli && cargo build --release
# Binary at tools/hcdf-cli/target/release/hcdf

Python Tools

Python tools are provided for validation, spec generation, JSON Schema generation, and XML/JSON conversion. All require lxml (pip install lxml).

python3 validate.py hcdf.xsd file.hcdf validates against the XSD
python3 convert.py file.hcdf file.json bidirectional XML/JSON conversion
python3 generate_spec_html.py hcdf.xsd spec.html generates the interactive spec browser
python3 generate_json_schema.py hcdf.xsd hcdf.schema.json generates JSON Schema from XSD

The Python converter uses the same context-aware XSD type walker as the Rust version, ensuring identical roundtrip behavior. Both support bidirectional XML to JSON conversion with full schema fidelity.

Dendrite: HCDF Visualization & Builder

Dendrite is a Rust-based 3D visualization tool that renders HCDF descriptions as interactive 3D models. It serves as both a viewer and an editor for HCDF files within the CogniPilot ecosystem.

Fetches HCDF components from hcdf.cognipilot.org with SHA verification
Renders GLB/glTF models referenced in <visual> elements
Displays port locations, sensor FOVs, and network topology
Shows device discovery state (which devices are online)
Supports editing poses and configurations

SHA-Based Content Addressing

HCDF uses SHA256 hashes for verified distribution of all referenced artifacts. Every model file, stream profile, included component, and firmware image carries a hash that enables integrity verification and efficient caching.

<!-- Model files -->
<model uri="models/abc123-board.glb" sha="abc123..."/>

<!-- Stream profiles -->
<stream-profile uri="profiles/operational.streams.xml" sha="..."/>

<!-- Included components -->
<include uri="components/sensor.hcdf" sha="..."/>

<!-- Firmware -->
<software><hash>abc123...</hash></software>

This enables:

Cache deduplication: same content produces the same hash, stored once
Integrity verification: detect corrupted or tampered downloads
Version pinning: a specific SHA corresponds to a specific version
Vendor trust: a published hash represents vendor-verified content

Firmware Integration with MCUboot

The <software> element describes firmware running on each device. MCUboot image hashes match the HCDF hash, allowing agents to verify firmware identity and detect mismatches that require OTA updates.

<software name="cerebri">
  <version>1.2.3</version>
  <hash>a1b2c3d4...</hash>
  <firmware-manifest-uri>https://firmware.cognipilot.org/mr_mcxn_t1/optical-flow</firmware-manifest-uri>
</software>

MCUboot image hash matches the HCDF hash; agent verifies firmware identity
Firmware manifest URI enables OTA update checking
An agent can detect firmware mismatches and trigger updates automatically

Building from Components

Hardware vendors provide HCDF components for their boards. System integrators compose these components into a full robot description using the <include> element with SHA integrity verification.

Vendor-provided component

<!-- Vendor provides: mr_mcxn_t1/optical-flow.hcdf -->
<comp name="optical-flow" role="sensor">
  <board>mr_mcxn_t1</board>
  <port name="ETH0" type="ethernet">...</port>
  <sensor name="imu0">...</sensor>
  ...
</comp>

System integrator composition

<hcdf version="1.0">
  <!-- Include vendor-provided components -->
  <include uri="https://hcdf.cognipilot.org/mr_mcxn_t1/optical-flow/optical-flow.hcdf"
           sha="d9507e38..." name="optical-flow-1"/>
  <include uri="https://hcdf.cognipilot.org/navq95/default/default.hcdf"
           sha="e4559866..." name="navq95"/>

  <!-- System-level: joints, networks, groups, states -->
  <joint name="mount" type="fixed">
    <parent comp="navq95"/><child comp="optical-flow-1"/>
  </joint>
  <network name="sensor-bus">
    <link name="nav_to_of">
      <wired standard="100base-t1">
        <port>navq95/eth0:2</port>
        <port>optical-flow-1/ETH0</port>
      </wired>
    </link>
  </network>
</hcdf>

Validation

HCDF files can be validated against the XSD schema using the included Python validator. The spec browser provides an interactive view of every element, attribute, type, and enumeration in the schema.

# Validate against schema
python3 validate.py hcdf.xsd my-robot.hcdf

# Generate and view spec browser
python3 generate_spec_html.py hcdf.xsd spec.html
python3 -m http.server 8080