The Host Contract
The rules governing what a Neuro N6 board does when a host is and is not attached, and the five traffic classes between board and host.
The core is built to one rule regarding the host: detaching Neuro Studio changes what a human can see, and nothing else. A shipped board has no host, so no decision the device makes may depend on one, and anything the device needs in order to decide must live on the device. The rule and the wire formats that implement it are defined in cores/NeuroN6/n6_host_contract.h, which must stay in sync with Neuro Studio.
Traffic classes
| Class | Direction | Description | Delivery |
|---|---|---|---|
| Capability | Device to host | What this build can do | Latest-wins, about 1 Hz, safe to miss |
| Result | Device to host | What the device decided this frame | Small, per frame, never dropped |
| Evidence | Device to host | Why it decided that: thumbnails, histograms, masks | Large, per frame, for a human only, droppable and host-gated |
| Parameter | Host to device | A live knob | Applied immediately, bounded, not persisted |
| Asset | Host to device | Data that must survive a power cycle: calibration, tables, weights | Written by the bootloader |
Uplink travels on the vendor bulk-in endpoint as tag-length-value (TLV) records. Downlink travels on the vendor bulk-out endpoint as magic-prefixed binary. Evidence tags occupy a reserved range so that a transport can drop evidence without parsing it.
Consequences
Results always travel. Detections, decoded payloads and sensor readings are computed for the device's own purposes; the host overhears them.
Evidence is produced only on request. Crop thumbnails and diagnostic images exist so that a person can look at them, and the board does not build them unless a host has subscribed recently. A sketch that passes a frame to vnd_meta_vision_add() incurs no cost when no host is subscribed.
Parameters do not persist. Live tuning values are lost at reboot. A value that must outlive the session is an asset. See Live Tuning and Assets.
Clips do not go to USB. The event recorder writes clips to its sink and sends only the event to the host, because a watching host already has the live video and producing a clip on the possibility of a watcher would violate the rule. See Events and SD Logging.
The boot log is replayed. Output published during setup() is stored and delivered when a host attaches, so a late connection loses no information. See The Serial Console.
Metadata slots
Results are published into slots. Four are reserved for models, VND_META_SLOT_MODEL_0 to _3, and others for sensors, QR, AprilTag, blob, event and audio results. The background capture task composes the current contents of every slot into each frame's metadata. Slot 0 carries the frame-wide box list. See Running Several Models.
Publishing functions
| Function | Class | Use |
|---|---|---|
vnd_meta_publish_debug_text(s) | Result | A line of text, also recorded in the boot log |
vnd_meta_vision_begin/add/finish | Result and evidence | A box, a label, extra bytes, and a crop thumbnail that is sent only if subscribed |
vnd_meta_publish_tlv(slot, tag, data, len) | Any | Arbitrary bytes under a tag |
NeuroN6_MetaAnnounce | Capability or result | Periodic announcement without video |
vnd_meta_invalidate_slot(slot) | Clears a slot so stale results are not sent |
vnd_meta_publish_tlv has a weak stub in the core, so a library can publish a result without a hard dependency on the PostProcess library.
Adding a capability
The contract header contains a five-question procedure for deciding which class a new piece of traffic belongs to. New evidence tags are allocated in the evidence range. Tags outside the range are classified explicitly by value.
Compile-time checks
The header asserts that the tag values used by libraries match the contract, so a mismatch fails the build rather than appearing as a parsing error on the host.