Tools & Ecosystem

HCDF CLI (Rust)

The hcdf command-line tool converts HCDF, URDF, SDF, xacro, and the XSD-derived HCDF JSON view. Its validation commands check HCDF documents. It is a single compiled binary with no external runtime toolchain.

XML/JSON conversion is driven by the typed Rust model and the SHA-pinned HCDF 1.0 XSD embedded in the binary. It preserves modeled HCDF values, but emits canonical XML rather than preserving source formatting, comments, processing instructions, or the XML declaration. A schema or model change therefore requires rebuilding the tool. The development-only regen commands below read an explicit XSD to rebuild derived artifacts.

Build from source:

cargo build --release --manifest-path rust/hcdformat-rs/Cargo.toml --features cli --bin hcdf
# Binary at rust/hcdformat-rs/target/release/hcdf

The CLI also owns every generated artifact: the spec pages, the JSON Schema, the editor completion model, and the crate's own enum sources all regenerate from the XSD with no other toolchain:

Python Binding

The repository contains a maturin/PyO3 binding project under rust/hcdformat-py. Its wheel is the compiled Rust core itself: the hcdf package is a native extension module, accompanied by type stubs (py.typed + .pyi) and no Python implementation source. It exposes the same Rust CLI and conversion API to CPython. The package is not yet published on PyPI, so it must currently be built from source with maturin. Python is not used for the core implementation, schema generators, or either GUI application. 

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install 'maturin>=1.7,<2'
maturin develop --release --manifest-path rust/hcdformat-py/Cargo.toml

In-Browser Apps: HCDViz & Dendrite Build

HCDViz and Dendrite Build are separate Rust/WebAssembly web applications for working with HCDF. Both render HCDF descriptions as interactive 3D models: GLB/glTF visuals, collisions, frames, sensor FOVs, port locations, kinematic articulation with loop-closure solving, and the network/comms topology overlay.

The same application crates also build as native desktop binaries.

Optional Content Digests

HCDF provides SHA-256 fields for integrity-checking model files, stream profiles, included modules, connectivity models, and recorded software identity. These fields are optional in the core schema unless an external project policy makes them mandatory. When a resource hash is present, tooling can verify bytes before using them and can cache identical content under one digest. 

<!-- 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 name="firmware"><hash>abc123...</hash></software>

This enables:

A digest proves content identity and integrity, not publisher identity. Authentication and signature policy belong to the distribution system that publishes the HCDF document.

Firmware Identity and External Update Systems

The <software> element describes firmware running on each device. A deployment can record a firmware digest in HCDF and compare it with identity reported by MCUboot or another firmware-management system. HCDF carries the expected identity; it does not itself attest a running image or perform an OTA update. 

<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>

Building from Components

Hardware vendors can provide complete HCDF modules for their boards. System integrators compose those modules into a full robot description using <include>, optionally pinning the included bytes with a SHA-256 digest. The URI below is illustrative, not a hosted catalog entry.

Vendor-provided component

<!-- Vendor module: optical-flow.hcdf -->
<hcdf version="1.0" name="optical-flow-module">
  <comp name="optical-flow" role="sensor">
    <board>mr_mcxn_t1</board>
    <port name="eth0">
      <capabilities>
        <purpose value="communication"/>
        <carrier value="electrical"/>
        <rate min="100000000" max="100000000" nominal="100000000" unit="bit/s"/>
      </capabilities>
    </port>
  </comp>
</hcdf>

System integrator composition

<hcdf version="1.0" name="inspection-robot">
  <comp name="chassis"/>
  <include uri="https://example.org/hcdf/optical-flow.hcdf"
           sha="sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
           name="optical-flow-1" pose="0.2 0 0.1 0 0 0"/>
</hcdf>

Validation

HCDF schema-shape and semantic validation are separate CLI passes. The spec browser provides an interactive view of schema structure, attributes, cardinalities, and enumerations, and regenerates from the same Rust binary.

The standalone semantic command expects a flattened document. A document that still contains <include> entries needs an include-aware document-set loader before complete connectivity validation; its raw XML can still be checked with validate --xsd. 

# Validate the raw XML shape, typed structure, and enum literals
hcdf validate --xsd my-robot.hcdf

# Validate semantic references, networks, loops, and coverage rules
hcdf validate my-robot.hcdf

# Regenerate and view the spec browser
hcdf regen spec hcdf.xsd spec.html