Design Decisions
HCDF was designed to fill a gap: existing robot description formats (URDF, SDF, MJCF) describe the physical structure of robots but ignore the cyber infrastructure that controls them. A real robot is more than joints and geometry. It has network topology, wired and wireless connectivity, deterministic scheduling, link security, power distribution and energy storage, firmware identity, device discovery, sensor hardware with noise characteristics and sampling configuration, motor datasheets with load curves and thermal limits, dynamic surfaces like propellers and control surfaces, human-machine interfaces, and the ability for an autonomous agent to read, reason about, and configure the entire system. HCDF describes all of this in a single validated schema: the physical structure, the cyber infrastructure, the sensor and actuator hardware, the energy architecture, and the operational configuration.
Why HCDF?
URDF describes a kinematic tree of links and joints and is used broadly in ROS, not just for simulation, but also for visualization (RViz), motion planning (MoveIt), control (ros2_control), and real hardware drivers. SDF extends this with additional simulation features such as sensors, plugins, and world models. However, neither format describes the Ethernet switches, CAN buses, power buses, or network schedules that a real robot needs. A humanoid with 19 devices and 5 networks has as much complexity in its networking as in its kinematics. HCDF puts both in one file so that an agent (human or AI) can reason about the complete system: "If I add a camera to the left wrist, which switch port does it connect to, what bandwidth is available on that 802.3dm chain, and does the Qbv schedule have room for the video stream?"
HCDF also addresses the "component" vs "link" problem. In URDF, a link is a rigid body in a
kinematic tree. In HCDF, a <comp> is a physical device: it has ports, sensors,
motors, switches, antennas, and firmware. A comp is more like a circuit board than a geometric
shape. Geometry (visual, collision) is optional; networking is first-class.
Topology Types
HCDF defines three network topology primitives that cover the wiring patterns found in real robots. Each maps to different hardware and has different latency, bandwidth, and redundancy characteristics.
| Topology | Element | Use Case | Example |
|---|---|---|---|
| Link | <link> |
Point-to-point connection between two ports | 25G backbone between S32N79 and AGX Thor |
| Bus | <bus> |
Shared medium with multiple participants | CAN-FD bus for wheel drives and BMS |
| Chain | <chain> |
Daisy-chain with switched hops (pass-through or bridged) | 802.3dm arm chain with camera spurs |
Chains are the most novel element. An 802.3dm chain carries 10G upstream and 100M downstream on a single twisted pair, with each hop containing a bridging switch. This is how modern automotive and robotics Ethernet works: you don't run a separate cable to every actuator. Spurs branch off the chain (e.g., a camera at the wrist with a different VLAN and QoS class).
<chain name="left-arm-chain" type="802.3dm" mode="switched">
<vlan id="10" pcp="5"/>
<hop device="s32n79" port="xfi_left" role="root"/>
<hop device="mcn1-l" ingress="eth0" egress="eth1"/>
<hop device="mcn2-l" ingress="eth0" egress="eth1"/>
<hop device="mcn3-l" ingress="eth0" egress="eth1">
<spur device="cam-l" port="eth0" via="eth2">
<vlan id="20" pcp="3"/>
</spur>
</hop>
<hop device="mcn4-l" ingress="eth0" role="tail"/>
</chain>Network Architecture
A <network> is a self-contained networking domain. It groups the physical
topology (links, buses, chains) with the configuration that runs on that topology: gPTP time
synchronization, traffic class definitions, Qbv gate schedules, MACsec security policy, EEE
energy savings policy, and stream profile references. A robot typically has multiple networks
(backbone, arm chains, base peripherals, power distribution) that are configured independently.
This design matches how real network stacks work. Each network has its own gPTP domain, its own set of schedules, its own MACsec key store. The S32N79 switch fabric bridges between networks at the hardware level; HCDF describes the logical separation.
Sensor Model
HCDF sensors are categorized by measurement principle, not by product type. The sensor model covers 11 categories: inertial (accelerometer, gyroscope), optical (camera, thermal, ToF, LiDAR, optical flow), electromagnetic (magnetometer, Hall effect, fluxgate), RF (radar, GNSS, UWB, radio altimeter), force (pressure, strain, torque, load cell), chemical (gas, pH, humidity), encoder (incremental, absolute, linear: optical, magnetic, inductive), temperature (thermistor, RTD, thermocouple, IR), radiation (Geiger, scintillation, neutron, dosimeter), audio (microphone, ultrasonic, sonar, hydrophone), and tactile (capacitive, resistive, piezoelectric, barometric, optical gel).
Each sensor type carries its own parameters. An IMU has range, resolution, ODR, bandwidth, FIFO depth, noise model (Gaussian with mean, stddev, bias), and driver info (chip name, axis alignment). A camera has intrinsics (fx, fy, cx, cy), FOV geometry (frustum shape), data output bandwidth, and camera-specific params (shutter type, HDR, compression, trigger mode). These parameters are what navigation filters and perception pipelines actually need.
<sensor name="imu0" update-rate="1000">
<inertial type="accel_gyro">
<driver name="icm45686">
<axis-align x="Y" y="-X" z="Z"/>
</driver>
<accel>
<range unit="g">16</range>
<noise type="gaussian">
<stddev>0.003</stddev>
<bias-mean>0.01</bias-mean>
</noise>
</accel>
</inertial>
</sensor>Visualization and Materials
HCDF delegates visual rendering to glTF/GLB, the industry standard for 3D assets supported
by Bevy, Three.js, Godot, Blender, and USD. A <visual> element on a component
references a GLB file (with SHA verification) that carries the full rendering data: meshes,
PBR materials, textures, normal maps, and LOD. This avoids duplicating what glTF already does
well. HCDF does not define its own PBR material system, texture pipeline, or shader model.
The <material> element in HCDF serves a different purpose: it defines
physical surface properties (friction coefficients, restitution, contact stiffness)
and a basic color for fallback rendering. These are the properties that physics engines and
simulation exporters need, not what renderers need. When converting HCDF to SDF or USD for
simulation, the material's friction and color transfer to the simulator; the GLB's PBR textures
transfer separately through glTF import.
For components without a GLB model (early design, procedural geometry), HCDF provides
<geometry> primitives (box, cylinder, sphere, capsule, cone, ellipsoid, mesh,
frustum) that can be used for both collision bounds and fallback visualization. Geometry
primitives on <collision> define the physics boundary; on
<visual> they provide a placeholder shape until a proper 3D model is available.
Embodiment Description
Beyond the kinematic tree (joints connecting comps), HCDF provides three mechanisms for describing how a robot is intended to be used. Groups name collections of joints for planning: a "left_arm" kinematic chain, a "left_hand" end-effector, a "locomotion" set. Groups can contain other groups for composition ("left_manipulation" = left_arm + left_hand). States define named joint configurations (home, transport, inspection) that agents can command. Self-collision disable lists pairs of components that cannot collide, with reasons (adjacent, mounted, unreachable), so collision checkers skip unnecessary tests.
<group name="left_manipulation">
<description>Left arm + hand for manipulation tasks</description>
<group ref="left_arm"/>
<group ref="left_hand"/>
</group>
<state name="transport">
<description>Compact transport position — arms folded tight</description>
<joint-position joint="l_shoulder_yaw" value="0"/>
<joint-position joint="l_elbow" value="2.4"/>
<joint-position joint="l_wrist_pitch" value="1.0"/>
</state>
<self-collision-disable>
<pair comp1="torso" comp2="mcn1-l" reason="adjacent"/>
<pair comp1="mcn1-l" comp2="mcn1-r" reason="unreachable"/>
</self-collision-disable>Extensions
HCDF uses a reverse-DNS domain system for extensions: <extension domain="org.ros2" version="1.0">.
The schema allows xs:any with processContents="lax" inside the
extension element, so any well-formed XML is valid. Versioning allows evolution without breaking
existing files. The domain identifier prevents conflicts between vendors.
Registered extensions include org.ros2 (topic mapping), org.gazebosim
(simulation parameters), and org.cognipilot.imu-stability (Allan variance for
tactical IMUs). See the Extensions Guide for details on writing and
registering new extensions.
Comparison
| Capability | HCDF | OpenUSD | URDF | SDF | MJCF |
|---|---|---|---|---|---|
| Physical Structure | |||||
| Kinematic tree | Yes (tree + loops) | Yes | Yes (tree only) | Yes | Yes |
| Joint types | 10 (revolute, cylindrical, ball, free, ...) | Via UsdPhysics | 6 | 9 | Many |
| Collision geometry | 8 primitives + mesh | Full | 5 primitives + mesh | 9 primitives + mesh | Primitives + mesh |
| Visual / materials | GLB/glTF refs + color | Full PBR (native) | Color + texture | PBR | Basic |
| Named states / keyframes | Yes | No | No (SRDF separate) | No | Yes |
| Joint groups | Yes (hierarchical) | No | No (SRDF separate) | No | No |
| Sensors & Actuators | |||||
| Sensor categories | 11 (inertial, optical, RF, tactile, audio, ...) | No | 2 (camera, ray) | 15+ | Several |
| Sensor noise models | Yes (gaussian, bias, per-axis) | No | No | Gaussian only | No |
| Motor specifications | Full (curves, pole-pairs, thermal, control modes) | No | No | No | Partial |
| HMI (displays, buttons, LEDs) | Yes | No | No | No | No |
| Dynamic surfaces (wings, wheels, props, grippers) | Yes | No | No | Via plugins | No |
| Networking & Connectivity | |||||
| Network topology | Yes (link, bus, chain, mesh) | No | No | No | No |
| Bus protocols (CAN, I2C, SPI, EtherCAT) | Yes | No | No | No | No |
| Deterministic networking (TSN) | Yes (gPTP, Qbv, FRER, stream profiles) | No | No | No | No |
| Network security | Yes (MACsec, key management) | No | No | No | No |
| Wireless (WiFi, BLE, Thread mesh) | Yes | No | No | No | No |
| Power & Energy | |||||
| Power distribution | Yes (buses, voltage rails, budgeting) | No | No | No | No |
| Energy sources (battery, fuel cell, tank, solar, supercapacitor) | Yes (chemistry, capacity, charging, flow, MPPT, ESR) | No | No | No | No |
| Cyber Infrastructure | |||||
| Device identity & discovery | Yes (hwid, IP, firmware hash) | No | No | No | No |
| Firmware versioning | Yes (SHA, MCUboot, OTA manifests) | No | No | No | No |
| Agent configuration (YANG) | Yes | No | No | No | No |
| Verified distribution (SHA) | Yes | No | No | No | No |
| Format & Tooling | |||||
| Schema validation | XSD + JSON Schema | USD Schema | XSD | Embedded schema | No |
| Formats | XML + JSON (bidirectional) | USD binary + ASCII | XML | XML | XML |
| Extension mechanism | Reverse-DNS domains + XSD | Vendor schemas | Gazebo tag (lax) | Plugins | No |
| Composition | Include + SHA verification | Layers + Payloads | xacro (preprocessor) | Include | Include |
| Simulation export | Planned (converters) | Native | Native | Native | Native |
HCDF is not anti-simulation; it is a superset that also covers the cyber infrastructure
that URDF, SDF, MJCF, and OpenUSD cannot describe. Converters from HCDF to URDF, SDF, and USD
will enable HCDF-described robots to be simulated in Gazebo, MuJoCo, Isaac Sim, and other tools.
The Gazebo extension (org.gazebosim) carries simulation-specific parameters that
survive the round trip. HCDF is designed to be the single source of truth for both the real
hardware and its simulation counterpart.
For full design rationale, see the design documents in docs/design/.
Relationship with OpenUSD
OpenUSD is gaining traction in robotics simulation (Isaac Sim, Gazebo). USD excels at scene composition, visual fidelity (PBR), physics (UsdPhysics), and multi-tool interoperability. But as the RobotecAI REP acknowledges: "OpenUSD lacks native schemas for domain-specific data (e.g., URDF transmission, MJCF actuator), conversions are inherently lossy."
HCDF and USD are complementary (see the comparison table above). USD handles visual/simulation; HCDF handles everything else (networking, power, firmware, device identity, agent configuration). An HCDF-to-USD converter extracts visual meshes, collision geometry, joints, and physics properties for simulation. The cyber infrastructure stays in HCDF where it belongs.
Simulation Interoperability (Planned)
HCDF files will be convertible to simulation formats:
- HCDF → URDF: Extract kinematic tree, inertial properties, visual/collision geometry, joint limits
- HCDF → SDF: Same plus sensors, plugins, materials, closed loops
- HCDF → USD: Visual meshes, physics joints, collision geometry via UsdPhysics
- URDF → HCDF: Import existing URDF models, add networking and cyber infrastructure
These converters enable using HCDF as the single source of truth while still supporting existing simulation tools (Gazebo, Isaac Sim, MuJoCo, Drake).
Versioning
HCDF uses semantic versioning (MAJOR.MINOR) for the schema. Minor versions add optional elements, attributes, or enumeration values and are always backward compatible. Major versions may remove, rename, or change existing elements.
| Change | Version bump | Backward compatible? |
|---|---|---|
| New optional element or attribute | Minor (1.0 → 1.1) | Yes |
| New enumeration value | Minor | Yes |
| New extension XSD | None | Yes |
| Change optional to required | Major (1.x → 2.0) | No |
| Remove or rename element | Major | No |
| Change element type | Major | No |
Parsers should ignore unknown elements and attributes so that an HCDF 1.0 parser can
read a 1.3 file without rejecting it. The <hcdf version="1.0"> root
attribute declares which schema version the file was authored against.
Each released version is archived in the versions/ directory. Extensions
and stream profiles are versioned independently. For the full policy, see
docs/design/versioning.md.