hillm — Hardware Interface LLM

AI Cost Tracking

• 🤖 LLM usage: $0.7176 (2 commits)
• 👤 Human dev: ~$228 (2.3h @ $100/h, 30min dedup)

Generated on 2026-06-09 using openrouter/qwen/qwen3-coder-next

---

Control platform hardware through a unified registry and transport layer:

• Displays / HDMI — xrandr, wlr-randr
• Cameras — V4L (/dev/video*)
• Audio — microphones / speakers via PulseAudio
• Input — keyboard / mouse discovery (/dev/input)
• USB — lsusb enumeration
• Serial / RS232 / RS485 — pyserial
• Modbus RTU/TCP — pymodbus
• MQTT / HTTP — network device gateways

Pairs with:

Package	Role
gillm	GUI / IDE keyboard injection
tillm	Shell LLM clients (aider, codex, …)
hillm	Physical devices and field interfaces

Install

cd /home/tom/github/semcod/hillm
make install-dev          # uv sync + control layer (recommended)
cp examples/env.example .env   # HILLM_DRY_RUN=1 for safe local dev
make install-transports   # + serial/modbus/mqtt
make help                 # all targets

Or manually:

uv sync --all-packages --extra dev   # recommended (workspace + dev tools)
# pip fallback:
pip install -e ".[dev]"
bash packages/install-dev.sh         # editable *2hillm adapters
pip install -e ".[serial,modbus,mqtt]"   # optional transports

CLI

hillm devices
hillm scan
hillm read --device camera-usb --dry-run
hillm write --device actuator-relay --value 1 --register coil:0 --dry-run
hillm actuate --device display-primary --action on
hillm status --ecosystem

DSL / integrations

# DSL — hardware verbs dry-run by default
dsl2hillm HEALTH
dsl2hillm 'READ DEVICE sensor-temp'

# URI — dry-run by default; --live for real hardware
uri2hillm HEALTH
uri2hillm 'READ DEVICE sensor-temp'
uri2hillm 'hillm://cmd/READ?device=camera-usb&dry_run=true'

# NLP — --apply is dry-run by default
nlp2hillm "read temperature from serial"
nlp2hillm "read temperature from serial" --apply
nlp2hillm "read temperature from serial" --apply --live

# REST (port 8218)
rest2hillm --port 8218
curl -X POST http://127.0.0.1:8218/v1/dsl -d HEALTH

# nlp2uri: pip install nlp2uri[hillm]
uri2hillm 'hillm://cmd/HEALTH'

Dry-run policy per adapter: docs/control-layer.md.

Architecture

hillm (core)
  registry.py      — device catalog + aliases + suggest_device_ids()
  resolve.py       — NL keywords → device id (shared by nlp2hillm)
  project_env.py   — .env bootstrap + apply_execution_policy()
  controller.py    — read / write / actuate / connect
  transports/      — serial, modbus, mqtt, display, v4l, audio, usb, …
  compat.py        — Koru backend + tool registry exports

packages/
  dsl2hillm        — CQRS bus (single mutation point)
  uri2hillm        — hillm:// URI + DSL shorthand
  nlp2hillm        — NL → DSL (--apply dry-run default)
  cli2hillm        — shell passthrough
  mcp2hillm        — MCP tools
  rest2hillm       — REST API (:8218)

Examples

Runnable smoke scripts in examples/ — full index: examples/README.md.

bash packages/install-dev.sh
cp examples/env.example .env    # optional
bash examples/run-all-dry-run.sh
make test-examples

Category	Scripts
CLI	devices · scan · read dry-run · status ecosystem · status mouse
DSL	smoke · read sensor-temp · devices usb
NLP	temperature · mouse port PL · apply live temp · check serial
URI	dispatch · shorthand read · decode
Devices	display · camera · mouse live · sensor temp · serial resolve

Tests

make test              # core + control layer (70+ tests)
make test-examples     # examples/**/*.sh smoke (40+ scripts)
make examples          # bash examples/run-all-dry-run.sh

Documentation

Doc	Content
docs/README.md	Documentation index
docs/configuration.md	Env vars, install profiles, ports
docs/control-layer.md	*2hillm adapters (DSL, URI, REST, MCP)
packages/README.md	Control layer package matrix
examples/README.md	Runnable smoke scripts
CHANGELOG.md	Release history
TODO.md	Roadmap and open items

Environment

Variable	Purpose
HILLM_DRY_RUN	Force dry-run transport globally
OPENROUTER_API_KEY	Enable LLM mapping in nlp2hillm (via litellm)
LLM_MODEL	OpenRouter model (default: openrouter/qwen/qwen3-coder-next)
HILLM_MODBUS_HOST	Default Modbus TCP host
HILLM_MQTT_URL	Default MQTT broker URL
HILLM_<DEVICE>_ADDRESS	Per-device address override

License

Licensed under Apache-2.0.