OpenMHS family: tag-bridge

Tag, register and PV devices through TagDriver (Modbus, EPICS Channel Access, ASCOM Alpaca)

Generated by MHS/registry/build_registry.py on 2026-10-20T00:00:00Z from 27 registry records and their task cards. A plan, not a conformance claim.

• bridge_status: available
• helper: TagDriver
• exemplar: MHS/drivers/labs/josuablejeru__labmastro

Launch

Every driver package starts the same way; per-repo configuration (environment id, model path, port, baud rate, VISA resource) lives in the package's driver.py, never in launch flags:

mhs serve <driver-dir>

A package is done when python3 -m mhs.driver check <driver-dir> --backend fake exits 0 (evidence contract_checked; a fake never yields an MHS-Device level).

Registry coverage

• Repos: 27
• Decisions: bridge-runtime 20, family-config 5, reference 1, skip 1
• Waves: 2: 2, 3: 2, 5: 1, 9: 22
• Dispatchable now: 0
• Modes: hardware 16, simulated 12

Applicability

Devices a server exposes by register number, PV name or Alpaca member: triage rule 9, family:tag-bridge. The implemented TagDriver is a configuration-only helper with three profiles, modbus, epics-ca and alpaca: a finite tag_config.points table where every address carries source_ref: path/in/clone:LINE (or a bounded range) that shows it at the pinned commit, plus parameters, reads, writes, commands, actions and safety_bindings. native names the upstream class that shows the map; it is parsed, never imported. Gate G7 accepts a register only as the address argument of a Modbus call or as a register constant on the cited lines, with the call's table and direction matching the point. Read the tag-bridge helper guide for the grammar, the codecs and the transport interface, and copy the structure of the labmastro exemplar (a Modbus RTU bench supply: state reads, write-only setpoints with operator-required limits, confirmed output commands and a confirmed stop), never its registers, facts or limits.

Check the card's shape first. Triage files a repository here when it imports a tag library anywhere; when the device itself speaks serial, SCPI or a Python SDK and the tag protocol is only a service layer or an example (an OPC UA mailbox, a Tango or Lima plugin, a Modbus demo for another device), write that device's shape and record DEVIATION FROM THE CARD, or stop with blocked HELPER_MISSING. A repository whose PV names come from a deployment file absent from the clone cannot cite its addresses: stop.

Capability mapping

Class ids come from python3 -m mhs.driver catalog search <words>. The deprecated classes cap.device.describe.v1, cap.world.state.v1, cap.world.snapshot.v1 and cap.world.restore.v1 are replaced by the protocol methods mhs.devices.get, mhs.resource.read, mhs.snapshot and mhs.restore.

Safety

The risk floor of a device is the highest catalogue risk_class of its classes (CAP-017); a driver may declare a higher risk, never a lower one. Hardware at R1 or above needs a declared native stop and a non-empty safe state. Any write or effectful command requires safety_bindings["estop"]: fixed writes or Alpaca methods followed by at least one confirmation read; R2+ hardware also needs an input-free Action(safe_state=True) with fixed steps and confirmation. Without a real, source-backed stop route a tag device may only observe (R0 reads). An acknowledgement alone never proves a stop, and a confirmation proves what the device reports, not physical quiescence: say in safe_state what stays energized or running.

Every TagDriver hardware backend, at every risk class and for every author, requires a schema-valid lock with a human reviewed_by entry of scope hardware before any factory or connection runs; models keep reviewed_by null. A lost, unacknowledged or unconfirmed write is an unknown outcome: the point leaves the state and ordinary effects are refused until a confirmed stop; a write-only setpoint whose write was lost then keeps commands refused until it is written again. Values a register cannot represent exactly are refused, never rounded. Industrial servers can front dangerous equipment; never write an undeclared tag.

Fidelity

A RecordingTagTransport fake is a deterministic point store: it establishes only contract_checked evidence. Mark its seeded values as placeholders, model only the device behaviour the cited source shows (a written output read back), and say in RESULT.json notes what the fake does not model (regulation, timing, Modbus exceptions, server errors).

Pitfalls

Address maps, unit ids and PV prefixes are deployment-specific; keep them in the backend options. Upstream helpers often scale, split or combine registers in ways the source must show (decimals, word order, two separate single-register writes are not one atomic value). Upstream code may swallow protocol errors; the package's transport must not. Multi-word writes, arrays, subscriptions and long-running commands are outside this helper version.

First task cards

• gh.josuablejeru/labmastro: family-config, wave 2, rank 26, MHS/registry/tasks/labs/josuablejeru__labmastro.json
• gh.holtzmanjon/apoalpyca: family-config, wave 2, rank 76, MHS/registry/tasks/labs/holtzmanjon__apoalpyca.json
• gh.danielballan/caproto-rpi: family-config, wave 3, rank 320, MHS/registry/tasks/labs/danielballan__caproto-rpi.json
• gh.nsls-ii-sst/caproto_cryostat: family-config, wave 3, rank 350, MHS/registry/tasks/labs/nsls-ii-sst__caproto_cryostat.json
• gh.festo-se/festo-pgva: family-config, wave 5, rank 19, MHS/registry/tasks/labs/festo-se__festo-pgva.json

Sources

• Task cards: MHS/registry/tasks/<track>/<owner>__<repo>.json (schema/taskcard.schema.json).
• Triage rules and the helper table: MHS/registry/triage.py; curated decisions: MHS/registry/overrides/.
• Driver API and gate: MHS/sdk/docs/driver-authoring.md; exemplars: MHS/drivers/.
• TagDriver grammar, transport and runtime rules.
• Driver authoring, model/human review, and safety specification.
• labmastro fake, tests, source facts, and hardware factory.