https://github.com/semcod/hillm
Hardware Interface LLM — control displays, cameras, audio, USB, serial, Modbus, and more.
https://github.com/semcod/hillm
automation hardware iot llm mcp modbus python semcod serial usb
Last synced: 1 day ago
JSON representation
Hardware Interface LLM — control displays, cameras, audio, USB, serial, Modbus, and more.
- Host: GitHub
- URL: https://github.com/semcod/hillm
- Owner: semcod
- License: apache-2.0
- Created: 2026-06-08T16:52:04.000Z (25 days ago)
- Default Branch: main
- Last Pushed: 2026-06-18T11:24:30.000Z (15 days ago)
- Last Synced: 2026-06-18T12:28:21.734Z (15 days ago)
- Topics: automation, hardware, iot, llm, mcp, modbus, python, semcod, serial, usb
- Language: Python
- Homepage: https://semcod.github.io/hillm/
- Size: 326 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://openrouter.ai/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`](../gillm/) | GUI / IDE keyboard injection |
| [`tillm`](../tillm/) | Shell LLM clients (aider, codex, …) |
| **`hillm`** | Physical devices and field interfaces |
## Install
```bash
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:
```bash
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
```bash
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
```bash
# 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](docs/control-layer.md#dry-run-policy).
## 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/](examples/) — full index: [examples/README.md](examples/README.md).
```bash
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](examples/cli/devices.sh) · [scan](examples/cli/scan.sh) · [read dry-run](examples/cli/read-dry-run.sh) · [status ecosystem](examples/cli/status-ecosystem.sh) · [status mouse](examples/cli/status-mouse-dry-run.sh) |
| **DSL** | [smoke](examples/dsl/run-smoke.sh) · [read sensor-temp](examples/dsl/read-sensor-temp.sh) · [devices usb](examples/dsl/devices-usb.sh) |
| **NLP** | [temperature](examples/nlp2hillm/to-dsl-temperature.sh) · [mouse port PL](examples/nlp2hillm/to-dsl-mouse-port-pl.sh) · [apply live temp](examples/nlp2hillm/apply-temperature-live.sh) · [check serial](examples/nlp2hillm/check-serial-env.sh) |
| **URI** | [dispatch](examples/control-layer/uri-dispatch.sh) · [shorthand read](examples/control-layer/uri-shorthand-read.sh) · [decode](examples/control-layer/uri-decode-sensor.sh) |
| **Devices** | [display](examples/devices/display/status.sh) · [camera](examples/devices/camera/capture-dry-run.sh) · [mouse live](examples/devices/input/mouse-status-live.sh) · [sensor temp](examples/devices/sensor/temp-read-dry-run.sh) · [serial resolve](examples/devices/sensor/temp-resolve-address.sh) |
## Tests
```bash
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](docs/README.md) | Documentation index |
| [docs/configuration.md](docs/configuration.md) | Env vars, install profiles, ports |
| [docs/control-layer.md](docs/control-layer.md) | `*2hillm` adapters (DSL, URI, REST, MCP) |
| [packages/README.md](packages/README.md) | Control layer package matrix |
| [examples/README.md](examples/README.md) | Runnable smoke scripts |
| [CHANGELOG.md](CHANGELOG.md) | Release history |
| [TODO.md](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__ADDRESS` | Per-device address override |
## License
Licensed under Apache-2.0.