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

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.