Reading an Interface Control Document
Every product in this documentation set that exposes an interface to something outside itself - a REST API, a WebSocket, a named pipe, a config file another process reads - has an Interface Control Document (ICD). It is the page to hand to someone integrating against the product without reading its source.
Document identifiers
An ICD’s own identifier appears in its Identification section and its revision history:
ICD-<PRODUCT>-<NNN> rev <N><PRODUCT> is the product’s documentation slug in upper case: CAPTUREAPP, CMTOBII,
HCPMACE. <NNN> is 001 unless a product publishes more than one physically separate
interface set. rev <N> increments each time a documented interface changes; the revision
history table at the end of the page records what changed and in which product version.
Interface numbers
Within a document, each interface has its own number, stable for the life of the product:
IF-<PRODUCT>-<NN> e.g. IF-HCPMACE-01 Session control (REST)You can cite IF-HCPMACE-01 from your own integration notes and it will point at the same
interface until that interface is formally withdrawn - which the ICD marks explicitly, along
with the product version that removed it. A number is never reused for a different interface.
What every ICD covers
ICDs in this set follow the same section order, so you can jump straight to the part you need across products:
- Identification - document id, revision, which product versions it covers, and who owns it.
- Scope - what the interface covers, and what it deliberately does not.
- Interface inventory - every
IF-*in the document, its direction and transport, in one table. - Per interface - transport and addressing, connection lifecycle, authentication, the message or endpoint set, a field-level data table, timing, and error behaviour.
- Data model reference - the HEAT ProtoLib messages the interface carries, pinned to a schema version.
- Units, frames and conventions - the units, coordinate frame and time base used across the whole document, stated once.
- Configuration affecting the interface - which of the product’s own settings change what you see on the wire.
- Compatibility and versioning - which peer or host versions are supported, and what a peer must tolerate when the schema evolves.
- Security considerations - network exposure and what the deployment is expected to provide.
- Conformance - how to prove your side of the integration works.
- Revision history - one row per change, with the product version that introduced it.
A section that does not apply to a given product still appears, with a one-line reason, rather than being left out - so a missing section always means “not written yet,” never “not applicable.”
Finding a product’s ICD
Every product page links its own ICD from the product’s index page and from its sidebar entry. There is no separate index of ICDs in this set: start from the module catalogue, the plugin catalogue, or HEAT Capture, and follow the Interface Control Document link on the product you need.
Not every product has one. A product that only consumes standard, already-documented data - for example a module that publishes a HEAT ProtoLib component through a third-party SDK, with no interface of its own - says so on its own page instead of pointing at an empty document.