# HomeAgent
**Minimal open-source smart-home hub BSP.**
Buildroot · SG2000 (arm64 dev lane / RISC-V C906 product ISA) · Zig state machine · C906L FreeRTOS coprocessor · EFR32 radio · Zigbee · Matter · matter.js · Go · Yocto origin lane
**왜 이 작업을 하고 왜 공개하는가 → [#7](https://github.com/junghan0611/homeagent-config/issues/7)** (한글)
[](LICENSE)
---
## Thesis
HomeAgent is being re-centered from a high-spec RPi5/Yocto/Hailo demo into a **minimal hub BSP** project — a reproducible **verification and prototyping ground** across several boards and dev environments. **No business logic lives here**; product logic stays in its own repos.
The work is not to invent a new Matter or Zigbee stack. Buildroot, Linux, Silicon Labs EFR32, Zigbee2MQTT, matter.js, Go, and Flutter already exist. The work here is the wiring:
> boot a small hub-class board with an open image, own the onboard radio, and document a reproducible path from BSP to Matter/Zigbee services.
**One principle, two executions (2026-10-21).** Reproducibility comes from packaging, not from the stack. On the boards we own end to end — Milk-V Duo S, and the RPi5/Yocto origin lane — that packaging starts from our own image, and this repo keeps what it learned building with Yocto and Buildroot. On the **SMHUB Nano** we do not build an image: the vendor's Buildroot is not public. The vendor's OS, RTOS coprocessor firmware, radio firmware and package feed are the base. The work there is packaging the product on top of that base: service combination, configuration, deployment, observation, backup and recovery, and update verification. That a vendor ships a component is not evidence of how far it was validated; our verification is what records that ([`docs/SMHUB.md`](docs/SMHUB.md) §9).
**The board picks the ISA, not the other way round.** On SG2000-class hardware the big core boots either ISA by a physical slide switch — a switch, not a fuse, so it is reversible — and which one we run follows whichever board the work is standing on.
Right now that board is the **SMHUB Nano**, because it arrives already equipped and costs far less hand-work than bringing Milk-V up ourselves. It is **riscv64**, so that is where the current work is.
**Milk-V Duo S on arm64 is a road we have driven, and the reason was Node.js.** `BR2_aarch64` is a first-class architecture for Buildroot's `nodejs` package while riscv64 is not, so arm64 was how the Node/Zigbee2MQTT stack could stand up without a downstream toolchain fork. That lane produced a real result — as of **v2026.7.24** the arm64 image is *flash-and-go*: flash → switch → dongle brings Z2M up with no config edits, proven on a second board. **When building Node for riscv64 is fully worked out, Duo S moves to riscv64 too and the two boards converge.** The product ISA and runtime target were always `riscv64-linux-musl`; arm64 was the detour that kept the stack moving, not a change of destination.
The runtime design — a **Zig 100ms hub state machine** on Linux plus a **C906L FreeRTOS coprocessor base** owning real-time pins over the SoC mailbox — is the public reconstruction of a hub state machine previously shipped as proprietary work: the architecture is open even though the production code is not. See [`runtime/README.md`](runtime/README.md), and [`NEXT.md`](NEXT.md) for the lane in flight.
RPi5 + Yocto + Hailo remains the **high-spec origin lane**: it proved matter.js, OTBR, Go controller, Flutter/Lit UI, Hailo/sLLM experiments, and recovery patterns. The current product-size hypothesis is smaller: **SG2000-class, 512MB, onboard EFR32**.
---
## Hub, Edge and Core — connection first
The shared direction is **a small authenticated connection structure, not a full IoT cloud**. A person can run the server for a home or SOHO; a small business can operate the same minimal contract. Features can grow above it without making automation, AI, a consumer app or a device catalogue prerequisites.
| Repository | Intended responsibility |
|---|---|
| [`coreagent-config`](https://github.com/junghan0611/coreagent-config) | Server-side authentication, registration, ownership and authorization, connection lifecycle, and reproducible server packaging |
| **`homeagent-config`** | Hub BSP/vendor base, radio and protocol services, and packaging our connection client and services across boot, network/time readiness, provisioning, update and recovery; not a separate authority for server accounts or ownership |
| [`edgeagent-config`](https://github.com/junghan0611/edgeagent-config) | Small-node state, self-description and message contracts, governed by that repository's own documents |
```text
Edge ── Hub ── Core server
└─────────── Core server (direct connection remains an option)
```
This is a possible topology, not a mandated routing design. **A NodeCard is self-description, not proof of identity.** An authenticated Hub does not by itself prove the independent identity of every Edge behind it. The server's promised identity scope, initial credential issuer, registration/claim authority, ownership transfer and revocation scope remain decisions to make together. Transport, broker and certificate tooling are not selected yet.
**First joint verification proposal — not implemented:** use one host-side fake Hub to observe authentication → registration/authorization → message exchange → disconnect/reconnect → credential revocation, including rejection of continued use of the revoked session and subsequent reconnects. Unregistered principals and principals without permission to the target must also be denied access. Define the credential and authorization rules before running it. This proves only the Hub–server boundary, not downstream Edge authentication.
The Home/Core coordinators aligned this documentation boundary on 2026-10-21; it does not constitute Edge maintainer approval, a completed implementation, or permission to modify a board. The hub-side resume point is [#8](https://github.com/junghan0611/homeagent-config/issues/8) and `NEXT.md`. ROS integration remains an independent verification axis in [#12](https://github.com/junghan0611/homeagent-config/issues/12).
---
## Current Target
| Axis | Direction |
|------|-----------|
| Main lane | minimal hub BSP + runtime stratification |
| Host | SOPHGO SG2000 (SMHUB Nano / Milk-V Duo S) |
| **Board in hand now** | **SMHUB Nano MG24** — arrives equipped, least hand-work, **riscv64**. Vendor OS, worked as a system-application developer |
| Full-stack board | **Milk-V Duo S** (SG2000, dual-ISA by slide switch, we own every layer) |
| Big-core boot | **riscv64 is the destination and the product ISA** (`riscv64-linux-musl`). **arm64 on Duo S is a driven detour** taken for one reason — Buildroot's `nodejs` supports `BR2_aarch64` and not riscv64 — and it reached flash-and-go in v2026.7.24. Converges back to riscv64 once Node builds there |
| Runtime | **Zig 100ms state machine on Linux + C906L FreeRTOS mailbox coprocessor base** |
| BSP | Buildroot SDK lineage, **both ISA lanes** built in-repo (`bsp/`) — arm64 kept working, riscv64 is where it lands |
| RAM target | 512MB-class for Z2M + MQTT + matter.js/Go evidence |
| Radio | Duo S = **USB ZBDongle-E** (EmberZNet 7.4.2); SMHub = onboard EFR32MG24 → **MG26 / Series 3** trajectory ([`docs/MULTIPROTOCOL.md`](docs/MULTIPROTOCOL.md)) |
| Protocol | Zigbee NCP **or** Thread RCP by firmware switching (single-chip concurrent = chip-timing question) |
| Parked evidence | Tuya THP23-ZB-X / SSD202D / 128MB lower-bound (not active) |
On the Duo S lane a USB coordinator (ZBDongle-E, version-aligned to the board) is the
working radio; onboard EFR32 stays the product shape (SMHub). Firmware:
[`firmware/zbdonglee/`](firmware/zbdonglee/). The runtime architecture lives in
[`runtime/README.md`](runtime/README.md).
---
## Product Direction — Certified Hubs & Radio Timing
**Thesis in one line:** hub certification and radio concurrency are tracked as **landscape research**,
not a product commitment. Single-chip **concurrent** Zigbee+Thread is not viable today (industry, Open
Home Foundation, and the vendor all use 2-radio or firmware mode-switch) — it is a **chip-timing
question** on the **MG21 → MG24 → MG26 → Series 3** line. So the current work is **separate-stack
control** (one radio, one protocol), not concurrency. *(The IKEA DIRIGERA "reproduce 1:1" lane is
**parked** as of 2026-07-14 — `docs/HUBS.md` stays landscape research, not our direction; the active
lanes are Duo S (arm64 dev / RISC-V product ISA) + SMHub reference.)*
**Where to look (recurring product-direction questions):**
| If you're asking… | Read |
|---|---|
| Which certified Zigbee/Matter hub? IKEA vs Zemismart vs SMHub | [`docs/HUBS.md`](docs/HUBS.md) |
| SoC comparison (SG2000 vs STM32MP157), MG21/24/26, PoE | [`docs/HUBS.md`](docs/HUBS.md) §2 |
| Thread TBR vs z2m, Matter over IP vs over Thread | [`docs/HUBS.md`](docs/HUBS.md) §3–4 |
| What devices/product line can the hub support? | [`docs/HUBS.md`](docs/HUBS.md) §7 |
| Single radio doing Zigbee + Thread at once — how / **when**? | [`docs/MULTIPROTOCOL.md`](docs/MULTIPROTOCOL.md) |
| Chip trajectory & when to flip to single-chip concurrent | [`docs/MULTIPROTOCOL.md`](docs/MULTIPROTOCOL.md) §3.7 |
| **Should a stack run on the hub, or should the hub only talk to it?** | [`docs/ECOSYSTEM-PORTFOLIO.md`](docs/ECOSYSTEM-PORTFOLIO.md) |
| Which home-automation host actually fits 512MB? (Buildroot survey) | [`docs/ECOSYSTEM-PORTFOLIO.md`](docs/ECOSYSTEM-PORTFOLIO.md) §3 |
| What does the Zigbee host cost — Z2M vs zigpy vs our own vs none? | [`docs/ECOSYSTEM-PORTFOLIO.md`](docs/ECOSYSTEM-PORTFOLIO.md) §4 · §6.2 |
| What does it cost to speak to Home Assistant / openHAB / Node-RED / …? | [`docs/INTEGRATION-SURFACE.md`](docs/INTEGRATION-SURFACE.md) |
---
## Living Document Set
| File | Role |
|------|------|
| [`AGENTS.md`](AGENTS.md) | week-stable agent rules |
| [`NEXT.md`](NEXT.md) | current handoff |
| [`CHANGELOG.md`](CHANGELOG.md) | closed work / CalVer notes |
| [`ROADMAP.md`](ROADMAP.md) | phase direction |
| [`VERSION.md`](VERSION.md) | stack, version, and physical device matrix |
| [`smhub/RUNBOOK.md`](smhub/RUNBOOK.md) | **새 SMHub Nano 한 대를 받아 Zigbee 데이터가 나가기까지의 순서** — 함정과 판정 포함. 보드는 Z2M + mosquitto만 쥐고, domoticz는 마스터에 둔다 (2026-09-10) |
| [`runtime/README.md`](runtime/README.md) | SG2000 runtime architecture + Zig/C906L code home |
| [`docs/TARGET_DEVICE.md`](docs/TARGET_DEVICE.md) | board/radio strategy details |
| [`docs/HUBS.md`](docs/HUBS.md) | certified Zigbee/Matter hub landscape research (DIRIGERA lane parked — not our direction), SoC/radio comparison, product line |
| [`docs/MULTIPROTOCOL.md`](docs/MULTIPROTOCOL.md) | single-radio Zigbee+Thread concurrency — strategy & timing (MG21/24/26 → Series 3) |
| [`docs/ECOSYSTEM-PORTFOLIO.md`](docs/ECOSYSTEM-PORTFOLIO.md) | home-automation stack landscape — what a 512MB hub can host, and what it should only talk to. The software half of `docs/HUBS.md` |
| [`docs/INTEGRATION-SURFACE.md`](docs/INTEGRATION-SURFACE.md) | the survey under it — all 36 SLZB integrations, transport axis and on-box cost (draft) |
| [`docs/README.md`](docs/README.md) | docs map |
Start with `NEXT.md` when continuing work — **except** when the task is an SMHub device itself
(new unit, build, packaging, install): then start with [`smhub/RUNBOOK.md`](smhub/RUNBOOK.md),
which is the procedure, and treat `NEXT.md` as the current worker's handoff rather than the runbook.
**Topic notes live as issues, not files** (`documentation` label) — the repo keeps few documents on purpose:
| Issue | Topic |
|---|---|
| [#7](https://github.com/junghan0611/homeagent-config/issues/7) | 왜 이 작업을 하고 왜 공개하는가 — 메모리 세 겹, SBC 스펙 근거, 상태머신 축 |
| [#8](https://github.com/junghan0611/homeagent-config/issues/8) | 제품화 구성 — 이미지가 소유해야 하는 것, 남은 축 5개 |
| [#9](https://github.com/junghan0611/homeagent-config/issues/9) | RPi5 + Yocto **origin lane** 세팅 가이드 (재현 절차, 2026-04 기준) |
---
## Architecture Shape
```text
Minimal hub board (SG2000 / 512MB)
├─ Open Linux image (Buildroot lineage)
├─ MQTT / local service bus
├─ Zigbee2MQTT or matter.js service
├─ Go HomeAgent surface / bridge
└─ onboard EFR32 radio
├─ Zigbee NCP firmware path
└─ Thread RCP firmware path
```
High-spec origin lane:
```text
RPi5 / Yocto / Hailo
├─ matterjs-server + OTBR
├─ Go REST/SSE/A2A/A2UI surface
├─ Flutter / Lit UI experiments
└─ Hailo/sLLM integration evidence
```
---
## Bring-up Checklist
For each minimal hub target:
- [ ] UART console and boot log
- [ ] U-Boot interruption or recovery path
- [ ] Open image build/flash path
- [ ] Rootfs and network access
- [ ] Onboard EFR32 device path
- [ ] Zigbee NCP proof with one paired device
- [ ] Thread RCP / matter.js proof when firmware/resources allow
- [ ] RSS/process evidence for MQTT, Z2M, matter.js, Go
- [ ] Power-cycle recovery notes
Hardware is in hand — an SMHUB Nano is the board this work currently stands on, so nothing here is hardware-blocked.
---
## Existing Commands
These still target the existing codebase and high-spec/origin tooling:
```bash
./run.sh go-build
./run.sh flutter-server
./run.sh flutter-run
./run.sh bundle
./run.sh diff
```
Treat RPi5 deploy and Yocto commands as origin-lane tools unless the task says otherwise.
---
## Project Layout
```text
homeagent-config/
├── runtime/ # SG2000 runtime stratification (Linux + Zig state machine + C906L)
├── bsp/ # Duo S board configs (arm64 dev + RISC-V lanes) + build/flash scripts
├── firmware/ # radio coordinator firmware (ZBDongle-E, version-aligned)
├── go/ # Go controller / hub surface (origin lane)
├── flutter/ # Flutter client experiments (origin lane)
├── ui/ # Lit frontend (origin lane)
├── scripts/ # build/deploy helpers
├── yocto/ # high-spec origin lane
├── deprecated/android-docker/ # archived compatibility path
├── docs/ # strategy and implementation notes
├── AGENTS.md
├── README.md
├── NEXT.md
├── ROADMAP.md
├── CHANGELOG.md
└── VERSION.md
```
---
## Philosophy
- Privacy by default.
- Reproducible over impressive.
- Commodity parts named honestly.
- Own the boot path, rootfs, radio, and service lifecycle where we build the image; where the vendor owns the base (SMHub), keep every layer inspectable and own what sits on top.
- Keep platform divergence explicit.
- **No display in the hub.** If a screen is needed, send a message to the web and let it draw (A2UI). Connectivity is the spec — not 4K, not a GPU.
- **Heavy inference is an API call.** The device declares "I am a hub" and turns a state machine, turn by turn.
- **A banner is not evidence.** Verify by filesystem UUID, not by "100% complete".
- **Nothing gets pushed in over ssh to make a product.** If it is not in the image — or, on a vendor base, in the declared package set and configuration — it is not in the product.
Full statement (한글): [#7](https://github.com/junghan0611/homeagent-config/issues/7) — *경계가 투명하지 않으면 재현성이 사라지고, 재현성이 사라지면 인간의 하루가 훌러덩 사라진다.*
---
## License
MIT