Design
HCDF describes a cyber-physical system as one coordinated model. Its structural layer covers rigid components, kinematic joints, geometry, sensors, actuators, and planning metadata. Its connectivity layer describes what each component can exchange, how that capability appears in physical hardware, and which system-level networks use it. The same vocabulary covers data, electrical power, guided and radiated signals, liquids, and gases.
These layers are related by explicit references rather than collapsed into one overloaded connector or network object. That separation lets an early design state that two controllers communicate without inventing a harness, while a manufacturing description can identify every pin, conductor, mating connector, and visible model part.
One model, four views
| View | Primary elements | Question answered |
|---|---|---|
| Structural | comp, joint, frame, group, state |
What are the rigid bodies, coordinate frames, and degrees of freedom? |
| Functional | port, channel, component functions |
What can a component send, receive, supply, or consume? |
| Physical | connectors, positions, assemblies, paths, junctions, terminations, antennas | What physical hardware carries the exchange? |
| Connectivity | binding, mate, topologies, configurations, stream profiles |
How do the functional and physical views form a connected system? |
A reference may point through included component instances, so reusable modules keep their own internal names while a larger system connects specific instances. Names remain local to the objects that own them, and typed references make the relationship explicit.
Structure and embodiment
A <comp> is a rigid body or hardware assembly. It can carry inertial
properties, visual and collision shapes, frames, ports, connectors, antennas, sensors, motors,
software identity, and other component-local details. A <joint> connects a
parent component to a child component and supplies the kinematic origin, axes, limits, dynamics,
mimic behavior, and optional loop-closure semantics.
The ten joint types are revolute, continuous,
prismatic, fixed, ball, universal,
planar, screw, cylindrical, and free.
Loop-closing joints represent parallel mechanisms without pretending that every joint is a tree
edge. Joint groups, named states, and self-collision exclusions provide planning and control
metadata in the same document.
<joint name="j_crank" type="revolute">
<description>Driven crank pivot on the ground link (the input; drive this to move the mechanism).</description>
<parent comp="ground"/>
<child comp="crank"/>
<origin xyz="0 0 0"/>
<axis xyz="0 0 1"/>
<limit lower="-1.0472" upper="1.0472" effort="20" velocity="3"/>
</joint>Functional ports and channels
A port is the functional boundary of a component. Its capabilities state the purposes, carriers, profiles, and engineering ranges that the component supports. A channel subdivides a port into named signal or flow roles, such as CAN high and CAN low, supply and return, UART receive and transmit, or the individual phases of a power connection.
Purpose answers why an exchange exists. Carrier answers what physically conveys it. Capabilities
may advertise alternatives; a network's required selected element chooses one
purpose and one carrier for that network instance.
| Dimension | Schema values | Examples |
|---|---|---|
| Purpose | communication, power-delivery, material-transfer |
CAN data, a DC supply, hydraulic fluid, cooling gas, or fuel |
| Carrier | electrical, guided-optical, conducted-rf, radiated-rf, liquid, gas |
Copper, fiber, coax, free-space RF, liquid lines, and gas lines |
Capability ranges can describe rate, voltage, current, power, impedance, frequency, bandwidth, pressure, flow, and temperature. Profile identifiers remain extensible, so CAN, UART, PWM, RS-485, Ethernet variants, BDSHOT, servo buses, and organization-specific protocols can share the same core grammar without becoming hard-coded schema types.
<port name="can">
<capabilities>
<purpose value="communication"/>
<carrier value="electrical"/>
<profile id="hcdf:can"/>
<rate min="1000000" max="1000000" nominal="1000000" unit="bit/s"/>
</capabilities>
<channel name="can_h" role="hcdf:can-high"/>
<channel name="can_l" role="hcdf:can-low"/>
</port>Connectors and physical positions
A connector names a physical interface and may identify its family. Its positions use vocabulary that matches the thing being represented. Each position can carry a role, a local grouping label, and an optional visible representation.
| Position | Use |
|---|---|
pin | A projecting electrical or signal contact. |
socket | A receiving electrical or signal contact. |
contact | A conductive contact that is not usefully classified as a pin or socket. |
fiber | An optical fiber position or optical termination. |
passage | A liquid or gas opening. |
feed | A conducted feed into an antenna or RF structure. |
waveguide-opening | The physical aperture of a waveguide connection. |
Connector shells and their positions can point at complete models or named model parts. This makes a connector and its pins selectable in a viewer while preserving the existing visual asset as the source of geometry.
<connector name="can_connector" family="hcdf:jst-gh-2">
<pin name="1" role="hcdf:can-high">
<representation>
<model-part node-path="dm8009p/jst_gh_2/jst_gh_2_p1" submesh-fallback="jst_gh_2_p1">
<model-root><component-visual component="base_j1_stator" visual="motor_case_connectors"/></model-root>
</model-part>
</representation>
</pin>
<pin name="2" role="hcdf:can-low">
<representation>
<model-part node-path="dm8009p/jst_gh_2/jst_gh_2_p2" submesh-fallback="jst_gh_2_p2">
<model-root><component-visual component="base_j1_stator" visual="motor_case_connectors"/></model-root>
</model-part>
</representation>
</pin>
<representation>
<model-part node-path="dm8009p/jst_gh_2/jst_gh_2_shell" submesh-fallback="jst_gh_2_shell">
<model-root><component-visual component="base_j1_stator" visual="motor_case_connectors"/></model-root>
</model-part>
</representation>
</connector>Assemblies, paths, junctions, terminations, and mates
Root-level harness, cable, plumbing, and
umbilical elements group physical connectivity into manufactured or routed
assemblies. An assembly can own connectors, paths, junctions, terminations, and one
representation. The same physical primitives can also appear inside a component when they are
integral to that component.
| Construct | Schema elements | Meaning |
|---|---|---|
| Two-ended paths | wire, conductor, cable-member, fiber, coax, waveguide, feed, hose, pipe, passage |
A physical carrier between exactly two physical endpoints. |
| Junctions | splice, tee, manifold, busbar, optical-splitter |
A physical joining point with one or more attachments. |
| Terminations | termination |
A typed endpoint, inline device, branch, or closure with optional engineering quantities and a profile. |
| Mates | mate |
A connection between two connector references, with optional position-to-position mappings. |
Termination mounting is one of endpoint, inline,
branch, or closure. A CAN termination resistor, an optical
termination, a hydraulic valve, and a sealed cap can therefore be described by the same
structural pattern without pretending they are the same kind of hardware.
Bindings and fidelity
A binding connects one functional endpoint, a port or channel, to one physical endpoint, a connector, position, or junction. It answers questions such as which connector pin carries CAN high without forcing that pin assignment into the functional port definition.
| Fidelity | Meaning |
|---|---|
functional | The relationship is known at the functional level; physical presentation may be absent. |
presented | The physical boundary is shown, but exact internal positions or routing may not be known. |
exact | The declared endpoint, position, route, or mapping is exact for the described design. |
quantified | The physical statement includes the engineering detail needed for analysis. |
The same fidelity values are used by bindings, paths, junctions, terminations, and mates. This lets a document mix high-level declarations with manufacturing detail while stating the precision of each claim.
<binding name="can_h_to_jst_gh_2_pin_1" fidelity="exact">
<functional><channel-ref component="base_j1_stator" port="can" channel="can_h"/></functional>
<physical><position-ref connector="can_connector" position="1"><component-ref component="base_j1_stator"/></position-ref></physical>
</binding>Physical representations and antennas
Connectivity objects use a focused representation vocabulary:
box, cylinder, sphere, model,
model-part, and derived-route. A model part selects a node path in an
existing component visual or assembly model. A derived route uses at least two waypoints and
may define a round or rectangular section, which allows a viewer to draw wires, hoses, pipes,
and waveguides without a separate mesh.
RF keeps conducted and radiated interfaces distinct. A port with
conducted-rf describes a feed, coax, waveguide, or PCB launch. A port with
radiated-rf describes the free-space boundary. An antenna requires a
radiated port, may reference a conducted port, and may carry a representation of the radiator.
Radiated ports can participate in links, buses, stars, meshes, or other topology objects just
like ports using a wired carrier. This also covers short-gap millimeter-wave links across a
moving joint.
<port name="wifi0-feed">
<capabilities>
<purpose value="communication"/>
<carrier value="conducted-rf"/>
<frequency min="5150000000" max="5850000000" nominal="5500000000" unit="Hz"/>
</capabilities>
</port><antenna name="wifi0">
<conducted-port component="compute" port="wifi0-feed"/>
<radiated-port component="compute" port="wifi0"/>
</antenna>Network topologies
HCDF has seven root-level topology objects. Every topology owns its participants and selection, and topology-specific objects add coordinators, hops, legs, or roots. They are direct children of the HCDF document, not members of a separate container.
| Topology | Required shape | Typical use |
|---|---|---|
link | Exactly 2 participants | Point-to-point wired, optical, RF, power, or fluid connection |
bus | At least 2 participants | CAN, RS-485, multidrop serial, shared power, or a shared material line |
chain | At least 2 participants, 2 hops, and 1 leg | Daisy chains and switched paths |
star | A coordinator reference and at least 2 participants | Hub, switch, manifold, or coordinator-centered network |
ring | At least 3 participants, 3 hops, and 3 legs | Closed paths and redundant rings |
mesh | At least 2 participants | Wireless or logical mesh membership |
tree | A root hop, at least 2 participants, 2 hops, and 1 leg | Branched switched, power, optical, or fluid distribution |
A participant names a functional endpoint. A hop identifies a component or component function that processes or forwards the carrier. A leg joins hop and participant references, so route shape is explicit when the chosen topology needs it.
Selection, configuration, and stream profiles
| Construct | Scope | Contents |
|---|---|---|
selected |
Required on every topology | The active purpose and carrier, plus optional profile, rate, electrical, RF, pressure, flow, or temperature selections. |
configuration |
Optional and owned by one topology | gPTP domains, traffic classes, gate schedules, schedule assignments, PLCA, MACsec, and Energy Efficient Ethernet settings. |
stream-profile |
A separate root-level resource reference | A URI, optional SHA, optional required flag, and optional selection role for a stream-profile document containing streams, talkers, listeners, paths, traffic and schedule references, and optional FRER policy. |
Selection describes what the physical network is operating as. Configuration describes how that topology is controlled. A stream profile describes traffic demand and routing separately, so multiple traffic plans can target the same network description.
<chain name="test-chain">
<description>Two-hop switched communication chain with timing, scheduling, MACsec, and EEE configuration.</description>
<selected purpose="communication" carrier="electrical"><rate><nominal value="100000000" unit="bit/s"/></rate></selected>
<configuration>
<gptp-domain name="time" number="0">
<clock name="parent-clock" kind="ordinary" gm-capable="true" priority1="128" priority2="128"><participant-ref network="test-chain" participant="parent-body"/></clock>
<clock name="board-clock" kind="ordinary" gm-capable="false" priority1="255" priority2="255"><participant-ref network="test-chain" participant="test-board"/></clock>
<port-defaults log-sync-interval="-3" neighbor-prop-delay-threshold-ns="800"/>
</gptp-domain>
<traffic-class name="ptp" number="7" preemption="express"><pcp value="7"/></traffic-class>
<traffic-class name="safety" number="6" preemption="express"><pcp value="6"/></traffic-class>
<traffic-class name="motion" number="5" preemption="express"><pcp value="5"/></traffic-class>
<traffic-class name="bulk" number="0" preemption="preemptable"><pcp value="0"/></traffic-class>
<gate-schedule name="1ms-control" cycle-time-ns="1000000">
<gate duration-ns="50000"><open><traffic-class-ref network="test-chain" traffic-class="ptp"/></open></gate>
<gate duration-ns="200000"><open><traffic-class-ref network="test-chain" traffic-class="safety"/><traffic-class-ref network="test-chain" traffic-class="motion"/></open></gate>
<gate duration-ns="750000"><open><traffic-class-ref network="test-chain" traffic-class="bulk"/></open></gate>
</gate-schedule>
<schedule-assignment name="chain-participants"><schedule-ref network="test-chain" schedule="1ms-control"/><target><participant-ref network="test-chain" participant="parent-body"/></target><target><participant-ref network="test-chain" participant="test-board"/></target></schedule-assignment>
<macsec><policy name="secure" enforcement="must-secure" cipher="ieee:gcm-aes-128" key-agreement="vendor:psk" credential-store-ref="se051"/><default-policy><macsec-policy-ref network="test-chain" policy="secure"/></default-policy></macsec>
<eee default-mode="disabled"/>
</configuration>
<participant name="parent-body"><endpoint><port-ref component="parent-body" port="eth0"/></endpoint></participant>
<participant name="test-board"><endpoint><port-ref component="test-board" port="eth0"/></endpoint></participant>
<hop name="parent-body" role="root"><owner><component-ref component="parent-body"/></owner></hop>
<hop name="test-board" role="tail"><owner><function-ref component="test-board" function="test-switch"/></owner></hop>
<leg name="parent-to-board"><from><hop-ref network="test-chain" hop="parent-body"/><participant-ref network="test-chain" participant="parent-body"/></from><to><hop-ref network="test-chain" hop="test-board"/><participant-ref network="test-chain" participant="test-board"/></to></leg>
</chain><stream-profile uri="profiles/operational.streams.xml" selection-role="default"/>Visuals, color, collision, and contact
A visual has one of two appearance sources. A high-fidelity visual uses a GLB or glTF
model, with an optional SHA and optional submesh or
exclude-submesh selectors. It may include a primitive geometry fallback for load
failure. A primitive visual instead uses one of box, cylinder,
sphere, capsule, cone, or ellipsoid, with
an optional inline or named color.
Collision geometry supports the same six primitives plus a lean external mesh. Contact physics
belongs directly under the collision's surface, which can hold friction,
restitution, and contact stiffness and damping. A frustum is general sensor field-of-view
geometry, not a visual or collision solid. There is no general material element: rich appearance
stays in GLB or glTF, flat appearance uses color, and contact behavior stays on collision.
<visual name="board">
<pose xyz="0 0 0" rpy="0 0 0"/>
<model uri="models/test-board.glb" sha="abc123def456"/>
</visual>
<collision name="board_col">
<pose xyz="0 0 -0.005" rpy="0 0 0"/>
<geometry>
<box><size>0.048 0.044 0.012</size></box>
</geometry>
<surface>
<friction static="0.6" dynamic="0.4"/>
<restitution>0.2</restitution>
</surface>
</collision>Sensors
A sensor is a named component-local container that can hold measurement blocks from twelve categories. The categories describe measurement domains rather than product names.
| Category | Examples |
|---|---|
inertial | Accelerometers, gyroscopes, and combined IMUs |
em | Magnetometers, Hall-effect sensors, fluxgates, and other near-field electromagnetic sensing |
optical | Cameras, thermal imagers, lidar, time-of-flight, and optical flow |
rf | GNSS, UWB, radar, and radio altimeters |
chemical | Gas, pH, humidity, and related chemical measurements |
force | Pressure, strain, torque, and load cells |
encoder | Incremental, absolute, and linear position encoders |
temperature | Thermistors, RTDs, thermocouples, and infrared temperature sensing |
radiation | Geiger, scintillation, neutron, and dosimetry sensors |
audio | Microphones, ultrasonic sensors, sonar, and hydrophones |
tactile | Capacitive, resistive, piezoelectric, barometric, and optical-gel touch sensors |
fluid | Barometers, airspeed, depth, flow, level, and pressure-reference sensors |
Sensor-specific blocks carry the parameters relevant to their domain, including poses, drivers, ranges, resolution, noise, bandwidth, sampling, field of view, and output characteristics where the corresponding type defines them.
<sensor name="imu0" update-rate="1000">
<inertial type="accel_gyro">
<pose xyz="0.016 -0.001 -0.008" rpy="0 0 0"/>
<driver name="icm45686">
<axis-align x="Y" y="-X" z="Z"/>
</driver>
<accel>
<range unit="g">16</range>
<resolution unit="mg">0.488</resolution>
<noise type="gaussian">
<mean>0</mean>
<stddev>0.003</stddev>
<bias-mean>0.01</bias-mean>
</noise>
</accel>
<gyro>
<range unit="dps">2000</range>
<noise type="gaussian">
<stddev>0.01</stddev>
</noise>
</gyro>
</inertial>
</sensor>Extensions
Extensions use a reverse-DNS domain and may declare their own version. Extension payloads are deliberately open to domain schemas while the HCDF core remains typed. The repository ships schemas for these four extension domains:
| Domain | Purpose |
|---|---|
org.ros2 | ROS 2 sensor and motor topic mappings with message types and QoS presets |
org.ros2.control | ROS 2 control hardware, joint, sensor, and command/state interface mapping |
org.gazebosim | Gazebo-specific simulation settings and plugins |
org.ieee.1722 | IEEE 1722 stream and transport details |
Other domains may be used without changing the core schema. The IMU Stability page is an illustrative extension design, not one of the shipped typed extension schemas.
Conversion and interoperability
The current Rust implementation imports and exports both URDF and SDF. It reports losses where a target format cannot represent HCDF content, and its URDF profile distinguishes clean round-trip cases from transformed or lossy projections. Xacro input is expanded by the pure-Rust xacro engine and then imported through the URDF path. These paths are available to native and WebAssembly consumers; Python access is provided through the Rust bindings.
| Path | Status |
|---|---|
| URDF → HCDF | Implemented |
| HCDF → URDF | Implemented, with profile classification and a loss manifest |
| SDF → HCDF | Implemented for the mapped mechanical and simulation overlap |
| HCDF → SDF | Implemented, with a loss manifest for unsupported HCDF content |
| Xacro → HCDF | Implemented through pure-Rust expansion and URDF import |
| HCDF and OpenUSD | Planned, not currently implemented |
HCDF is the richer source model in these conversions. A successful export does not imply that networking, power, firmware, or every simulation-specific field exists in the destination format; the reported losses are part of the conversion result.
Versioning and content integrity
The current core schema is HCDF 1.0. The root name is required. The
version value follows a MAJOR.MINOR pattern and defaults to
1.0 when omitted. The version string identifies the document grammar; it is not a
cryptographic identity for the schema bytes.
Strict XSD validation rejects unknown elements and attributes in the typed core. Extension payloads are the intentional open area and use lax processing. Tooling can bind the canonical XSD by its SHA-256 content hash, independently of the document's version string.
Hash attributes on referenced resources, including models, includes, connectivity models, and stream profiles, are optional. When present they provide integrity for that reference. They do not imply that every external resource in an HCDF document is hashed or that the entire document has been verified.