HomeDeck

HomeDeck is a battery-powered handheld smart home controller built around the M5Stack Tab5 Kit. It's designed to replace a Logitech Harmony Hub remote, then grow into a general-purpose handheld controller for media systems, smart home devices, home monitoring, and personal dashboards.

Harmony is the first supported integration — not the identity of the project. See ADR-0001 for the full project vision.

Goals

• A polished, consumer-quality handheld smart home control device — not a hobby project with a screen.
• A complete, reliable replacement for a Harmony Hub remote as the first milestone that actually matters to a user.
• A modular architecture that lets new integrations (Kodi, Uptime Kuma, Home Assistant, and beyond) be added without compromising the reliability of what's already there.
• Local-first control: LAN and direct device communication preferred over cloud dependencies wherever possible.

Supported hardware

• M5Stack Tab5 Kit — the primary and currently only supported target. Application processor is an ESP32-P4, which has no radio; Wi-Fi/BT run through an onboard ESP32-C6-MINI-1U wireless co-processor — see docs/architecture/hardware.md for the full hardware reference. Capacitive touchscreen, display, IMU, RTC, battery monitoring, speaker, microphones, USB-C, and microSD are all expected to be used by the firmware.

No other hardware is supported today. The architecture avoids unnecessary coupling to Tab5-specific quirks so that future hardware variants remain possible, but none is planned or committed to.

Current status

M3 (Harmony) is complete — HomeDeck can fully replace a Harmony Hub remote's day-to-day usage. M4 (Media) is the current milestone, delivered in two parts: M4a (Kodi connection, playback/transport, and the Now Playing / remote Touch UI) and M4b (Kodi library browsing) are both complete, including an on-hardware verification pass on a Tab5. See docs/roadmap.md for what's built, what's in progress, and the architectural decisions index.

Architecture

HomeDeck is organized into four layers:

UI
  ↓
HomeDeck Core
  ↓
Apps / Modules
  ↓
External Services / Devices

• UI — a Touch UI (on-device, LVGL) for everyday use, and a Web Management UI (browser-based) for administration.
• HomeDeck Core — shared services: lifecycle, navigation, dashboard, widgets, notifications, event bus, configuration, storage, networking, logging, diagnostics, OTA, power management, time/date, and weather.
• Apps / Modules — isolated integrations (Harmony, Kodi, Uptime Kuma, Home Assistant, ...) that use Core services and appear to the user as Apps.
• External Services / Devices — the actual hardware/services a module talks to (a Harmony Hub, a Kodi instance, etc.).

The full architecture is documented in docs/architecture/, starting with overview.md. Significant architectural decisions are recorded as ADRs in docs/decisions/.

Repository structure

HomeDeck/
├── docs/            architecture, ADRs, roadmap
├── src/             portable Core/UI source, shared by firmware/ and simulator/
├── firmware/        ESP-IDF firmware (Tab5 target)
├── simulator/       desktop simulator build
├── webui/           Web Management UI frontend
├── hardware/        physical accessory/enclosure design work
├── tools/           supporting developer tooling
└── tests/           test suites

firmware/ and simulator/ share the portable Core/UI source in src/; they differ only in which hardware-facing implementation they're built against. See docs/architecture/simulator.md.

License

MIT — see LICENSE and ADR-0001.

Getting involved

HomeDeck is early-stage — see docs/roadmap.md for the current milestone. For development setup, see DEVELOPMENT.md; for how to submit a change, see CONTRIBUTING.md.