NEEO Remote for Home Assistant

A local-only Home Assistant integration that exposes selected Home Assistant entities to a NEEO Brain and its physical remote. Home Assistant acts as the NEEO SDK adapter: the Brain pulls device definitions over HTTP, and the remote's buttons, sliders, and screen updates flow through the integration in both directions.

Status: pre-release (0.1.0). The Brain API and SDK routes are verified against neeo-sdk 0.53.8 and a live Brain (firmware 0.53.9). The full live register/notify/PGP round-trip is still owner-gated and pending; all automated tests run against a mock Brain. See docs/protocol.md for the protocol notes and known open items.

Features

• Discovery and static setup — mDNS (_neeo._tcp.local) with a manual host/port fallback and a read-only validation ping.
• Full MVP domain coverage — media_player, light, switch, climate, sensor, scene, and script.
• Physical remote mapping — D-Pad/transport/volume/mute/power buttons, brightness and volume sliders, climate target temperature and HVAC modes, source buttons, and cover art.
• Live state push — Home Assistant state changes become debounced, de-duplicated Brain notifications.
• Encrypted callbacks — the Brain can PGP-encrypt button/set callbacks to an ephemeral key served by Home Assistant.
• Resilient lifecycle — 30 s heartbeat, exponential backoff, and automatic adapter re-registration after a Brain reboot.
• Area-aware options UI — pick entities by Home Assistant area and choose per-area volume/power targets.

Requirements

• Home Assistant 2026.10.0 or newer.
• A NEEO Brain and NEEO Remote on the same network (or routable to each other).
• The Brain must be able to reach the Home Assistant HTTP(S) URL. The integration registers a token-scoped callback URL automatically.
• Port 3000 (Brain API) reachable from Home Assistant.

Installation

HACS (recommended)

1. In HACS, open Integrations, then the three-dot menu, then Custom repositories.
2. Add https://github.com/anomalyco/ha-neeo-remote with category Integration.
3. Install NEEO Remote, then restart Home Assistant.

Manual

Copy custom_components/neeo into your Home Assistant config/custom_components directory and restart Home Assistant.

Setup

1. Go to Settings → Devices & services → Add integration and choose NEEO Remote.
2. Accept a discovered Brain, or enter its host/IP and port (3000 by default). The integration validates with GET /v1/systeminfo (read-only).
3. Open the integration's Configure dialog:
   • Select the entities to expose, grouped by area.
   • Choose whether to send cover art.
   • Tune the notification debounce (default 0.25 s).
   • Optionally set a Home Assistant base URL override for multi-homed or reverse-proxied installs.
   • Optionally rename the adapter (the SDK-recognised src- prefix is added automatically).
4. On the second options step, optionally map a room's physical volume and power buttons to different entities.

The adapter is registered on setup and unregistered when the entry is unloaded or removed. See docs/setup.md for network and reverse-proxy details.

Supported entities

Domain	Remote controls
media_player	Playing switch, volume slider, mute switch, transport buttons, volume up/down, mute toggle, power on/off, source buttons, title/description/cover-art labels, D-Pad buttons
light	Power switch, brightness slider (0–100% ↔ 0–255)
switch	Power switch
climate	Current temperature label, target temperature slider, HVAC mode label, one button per HVAC mode
sensor	State label with unit
scene	Activate button
script	Run button

D-Pad presses have no generic Home Assistant navigation service; they fire neeo_action events for automations instead. See docs/entities.md for the full capability and service mapping.

How it works

NEEO Remote <--2.4 GHz--> NEEO Brain (:3000)
                               |
                               | HTTP (Brain API + callbacks)
                               v
                     Home Assistant custom component (neeo)
                       - registers adapter + token-scoped base URL
                       - serves /db, /device, /secure views
                       - maps HA entities <-> NEEO capabilities
                       - pushes debounced state notifications

The Brain pulls /db/search and /db/adapterdefinition/<apt-...> to discover the exposed devices, calls /device/<apt-...>/... for gets/sets/buttons, and receives POST /v1/notifications updates from Home Assistant. Callback bodies may be PGP-encrypted; the integration serves its ephemeral public key at /secure/pubkey.

Security

• Callback views are unauthenticated at the HTTP layer (the Brain has no Home Assistant credentials), but every request must carry a 256-bit per-entry secret token in the URL path. Wrong tokens get an indistinguishable 404.
• Callback POSTs can be PGP-encrypted; decryption failures return 401.
• No cloud service is involved. The Brain and Home Assistant talk directly.
• The token is embedded in the registered callback URL, so treat Brain configuration and debug logs as sensitive. Rotate by removing and re-adding the integration.

See docs/security.md for the threat model and hardening recommendations.

Troubleshooting

Start with docs/troubleshooting.md. For Brain reboots and recovery behavior, see docs/reboot-recovery.md.

Enable debug logging:

logger:
  default: warning
  logs:
    custom_components.neeo: debug

Development

python3.14 -m venv .venv
.venv/bin/pip install -r requirements_test.txt
.venv/bin/pytest tests/ --cov=custom_components/neeo --cov-report=term-missing
.venv/bin/ruff check custom_components tests
.venv/bin/ruff format --check custom_components tests

The test suite is offline by default: all Brain HTTP goes to the NeeoBrainMock fixture in tests/fixtures/. Never point tests or CI at a real Brain. A dev container is provided in .devcontainer/ for a sandboxed Home Assistant instance.

License

MIT — see LICENSE.