hillm — Hardware Interface LLM

AI Cost Tracking

• 🤖 LLM usage: $0.7734 (14 commits)
• 👤 Human dev: ~$1208 (12.1h @ $100/h, 30min dedup)

Generated on 2026-07-07 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

Local complexity gate

Run make quality-regix before publishing source changes. It requires regix with the Lizard backend (verified with Regix 0.1.15); select an isolated executable with make quality-regix REGIX=/path/to/regix when needed.

The gate reads the current working tree, including uncommitted source, under src/ and every packages/*/src/ adapter. It exits nonzero above CC 15 or 100 lines per function. Tests, examples and build output are outside its scope. Coverage, documentation and maintainability have no enforced baseline in this configuration. This opt-in local command does not install hooks or replace the independent OneDev test and Validator publication process.

Local regression watcher

After installing the development workspace, run make watch-tests in the checkout being edited. Wup and TestQL must be available (verified with Wup 0.2.64 and TestQL 1.2.67); override WUP and TESTQL with executable paths when needed. The watcher runs in the foreground; stop it with Ctrl-C.

Changes in core or adapter Python files trigger the pinned quick scenario (103 focused regression cases). A quick failure triggers the full test suite; traces and the generated runtime configuration stay in ignored .wup/. Generated files are excluded, periodic HTTP probes and external reporting are disabled. The test runner forces dry-run by default and imports source from this checkout, even with a shared test Python. Wup 0.2.64 ignores test directories even if listed as watch roots; for test-only edits, run bash scripts/wup-tests.sh quick or detail manually. An incomplete environment fails with setup guidance instead of auto-installing. This development watcher does not replace protected OneDev verification.

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.