OpenHAL

OpenHAL

[hardware][abstraction][layer]

An open-source protocol for AI agents to control hardware.

Get started

Agent

Owner

OpenHAL hub

Printer

watch my print

read frame

done

bed_target 70 °C

done

extruder_target 300 °C

LIMIT_EXCEEDED

read frame

done

pause

done

cancel

pending

approve

cancel

done

[hardware]

The hardware is any device OpenHAL controls. Each device has a device file that lists the device's channels and the limits a person confirmed.

[abstraction]

A hardware abstraction layer gives every device the same interface, so an agent reads and changes a 3D printer, a bench power supply or an Arduino board with the same few requests while the device file and the driver handle the differences.

[layer]

The layer is the hub between the agent and the hardware, where the safety kernel checks every request against the device file's limits before a driver sends a command to the device.

• H [hardware]

  The hardware is any device OpenHAL controls. Each device has a device file that lists the device's channels and the limits a person confirmed.

• A [abstraction]

  A hardware abstraction layer gives every device the same interface, so an agent reads and changes a 3D printer, a bench power supply or an Arduino board with the same few requests while the device file and the driver handle the differences.

• L [layer]

  The layer is the hub between the agent and the hardware, where the safety kernel checks every request against the device file's limits before a driver sends a command to the device.

9 steps 1 / 92 / 93 / 94 / 95 / 96 / 97 / 98 / 99 / 9

Skip the demo Smooth scrolling

An agent watches a 3D print through the OpenHAL hub.

You start a long print and ask an agent to watch it.

The agent checks the webcam and sees a corner of the first layer lifting.

The agent raises the bed to 70 °C. Your limit is 110 °C, so the hub lets the request through.

The agent also tries a nozzle temperature of 300 °C to help the print stick. Your limit is 260 °C, so the hub refuses.

Later, the webcam shows the print has come loose.

The agent pauses the print. Pausing is safe, so no one has to approve it.

Cancelling can't be undone, so the hub holds the request until you approve it.

You approve, and the hub sends the cancel to the printer.

The audit log records all 6 requests, including the refusal and your approval.

Agent

Owner

OpenHAL hub

Printer

watch my print watch my print

read frame read frame

done

bed_target 70 °C bed_target 70 °C

done

extruder_target 300 °C extruder_target 300 °C

LIMIT_EXCEEDED

read frame read frame

done

pause pause

done

cancel cancel

pending

approve approve

cancel cancel

done

Webcam, demo frame

Seen: first layer corner liftingSeen: print loose

Nozzle

215 °C155 °C113 °C

Bed target

60 °C70 °C

State

printingpausedcancelled

1. You start a long print and ask an agent to watch it.

   watch my print

2. The agent checks the webcam and sees a corner of the first layer lifting.

   read frame done

3. The agent raises the bed to 70 °C. Your limit is 110 °C, so the hub lets the request through.

   bed_target 70 °C done

4. The agent also tries a nozzle temperature of 300 °C to help the print stick. Your limit is 260 °C, so the hub refuses.

   extruder_target 300 °C LIMIT_EXCEEDED

   extruder_target 300 °C exceeds the limit of 260 °C

5. Later, the webcam shows the print has come loose.

   read frame done

6. The agent pauses the print. Pausing is safe, so no one has to approve it.

   pause done

7. Cancelling can't be undone, so the hub holds the request until you approve it.

   cancel pending

8. You approve, and the hub sends the cancel to the printer.

   approve cancel done

9. The audit log records all 6 requests, including the refusal and your approval.

Safety model

• Limits a person confirmed

  A person sets the limits in the device file, and the kernel checks every command against the limits.

• One STOP

  One command puts every device in its safe state, and the devices stay stopped until a person lifts the stop.

• Everything logged

  Every request, refusal, stop and confirmation goes into an append-only audit log.

What OpenHAL works with

OpenHAL has 34 drivers tested on simulator, in these device families.

• Microcontrollers and maker boards

  openhal-firmwarefirmataesphomeserialrpi-gpiopi-i2c-spible

• 3D printers and CNC

  marlinmoonrakeroctoprintbambugrbl

• Lab instruments and automation

  scpipylabrobotsila2http

• Home and building

  homeassistantmqttmatterzigbee-zwaveknx

• Industrial buses

  modbusopcuacan

• Robotics and astronomy

  ros2lerobotalpacaindi

• Cameras, media and input

  uvcrpi-cameraonvifupnphidmidi

All 34 drivers

Run the demo

The demo uses simulated devices, so you only need uv and git.

$ git clone https://github.com/sohan-bhat/OpenHAL
$ cd OpenHAL
$ uv run openhal demo

The demo plays the same story in your terminal. Send the requests in your browser

Read more

• Read the specification

  The specification defines every message, error and rule, and each version has a number such as v0.1.

• Read the docs

  The docs explain how to run the hub, create device files and add drivers.