Concepts

OpenHAL is a universal driver specification. AI agents use OpenHAL to safely discover, integrate and control lab and manufacturing equipment through one standard set of read and write commands.

What the name means

OpenHAL stands for Open Hardware Abstraction Layer.

Hardware. Any device OpenHAL controls. Each device has a Device File with the device's channels and the limits a person confirmed.
Abstraction. Every device gets the same interface, so an agent drives a 3D printer, a bench power supply or an Arduino board with the same few requests.
Layer. The Hub between the agent and the hardware. The Safety Kernel checks every request against the device file before a Driver sends a command.

Hub

The Hub is one process on your computer or a Raspberry Pi that owns every device. Clients connect with JSON-RPC 2.0 over a WebSocket or stdio, or through the MCP server.

Device files

Each Device File lists what can be read and changed, the limits and the safe state.

openhal: "0.1"
device: Klipper 3D printer
id: printer
match:
  mdns: _moonraker._tcp
  moonraker: { hostname: "printer*" }
connect: { moonraker: printer.local, port: 7125, timeout: 5 s }
read:
  state: { type: enum, values: [standby, printing, paused, complete, cancelled, error], every: 1 s }
  extruder_temp: { unit: degC, every: 1 s, range: [0, 320] }
  bed_temp: { unit: degC, every: 1 s, range: [0, 130] }
  progress: { unit: percent, every: 5 s }
write:
  extruder_target: { unit: degC, min: 0, max: 260, max_change_per_s: 50 }
  bed_target: { unit: degC, min: 0, max: 110, max_change_per_s: 20 }
actions:
  pause:
    description: Pause the print. Klipper parks the nozzle and keeps the heaters on.
    require: ["state == printing"]
  resume:
    description: Resume a paused print.
    require: ["state == paused"]
  cancel:
    description: Cancel the print. It can't be resumed afterwards.
    confirm: confirm-each-time
safe_state:
  - { extruder_target: 0, bed_target: 0 }
interlocks:
  - if: "extruder_target > 0 degC"
    require: "state != error"
    message: "Clear the printer error before heating."
watchdog: { heartbeat: 5 s, on_loss: hold }
hazard: medium
notes: "A print keeps running if the hub goes away, so the watchdog holds the printer's state instead of stopping the print. Klipper's own heater checks stay on either way."
provenance: { source: hand-written, by: openhal print babysitter example, at: 2026-10-24 }
confirmed: { by: owner, at: 2026-10-24, sha256: 43396b8f02a70481b9653275f22cc58f96b060ad2e31f4d80214acb26e51af1a }

Every channel and action has a risk level of low, medium or high. A high risk channel or action stays read-only until a person confirms the limits, and the rest take commands within the device's own range. A generated limit stays a suggestion until a person confirms the limit.

Safety kernel

The Safety Kernel checks units, range, step, rate of change, interlocks, token scope and confirmation, in that order, and stops at the first failure. The kernel is plain code with no model, and an unknown value such as a stale reading counts as unsafe.

Drivers and grants

A Driver implements one protocol, such as SCPI or Moonraker. A driver changes hardware only with a Grant, a single-use permission for one exact command.

Errors

A blocked or held command returns a JSON-RPC error with a stable code and name.

Code	Name	Meaning
-32010	LIMIT_EXCEEDED	Outside the confirmed limits
-32011	RATE_LIMITED	Faster than the rate limit
-32012	INTERLOCK_BLOCKED	An interlock doesn't hold
-32013	CONFIRMATION_REQUIRED	Held until a person approves
-32014	STOPPED	The hub is stopped
-32015	UNVERIFIED_LIMITS	The device file isn't confirmed

The specification lists every code.

Principals and hazard classes

A person uses the human token. An agent uses an agent token with a scope of read, control_low or control_medium. A device file's hazard class is low, medium or high, and the hub holds every change to a high hazard device until a person approves.

Conformance levels

Hubs and drivers declare a Conformance Level. Core covers discovery and reads, Control adds changes and stop, and Full adds actions, routines and confirmations.

What OpenHAL doesn't do

Each device's firmware still controls the device. OpenHAL doesn't replace e-stops, enclosures or hardware interlocks.