-
Notifications
You must be signed in to change notification settings - Fork 1
Home Assistant
NAMO can appear in Home Assistant through two different local integrations. Choose the one that matches the entities you need.
Important
The NAMO custom integration is currently a development preview. Its host-side contract tests pass, but Home Assistant container, discovery, DHCP, live handover, HACS, and upgrade verification are still release gates. Use it for evaluation and keep critical automations conservative until the integration is release-verified.
| Integration | Best for | Identity |
|---|---|---|
| ESPHome | Physical sensors and controls exposed by each NAMO device | One Home Assistant device per physical NAMO node |
| NAMO custom integration | Stable Site/Space occupancy, motion, target count, fused health, and shared automation areas | One entry per Site and one device per logical Space |
You may use both at the same time. The NAMO integration does not replace the physical ESPHome entities.
During initial NAMO setup, select Also use Home Assistant. NAMO prepares the ESPHome Native API and generates a unique encryption key.
Save that key. If you need it later:
- Open Management/Backup on the real NAMO device.
- Select Show API key.
- Copy it before the dialog hides it automatically.
Treat the key as a password. Do not post it in screenshots, logs, issues, or public configuration files.
[photo: Management/Backup page with the Show API key button and the temporary key dialog]
- In Home Assistant, open Settings > Devices & services.
- Accept the discovered ESPHome device, or select Add integration > ESPHome.
- Enter the NAMO IP address or
.localname. - Enter the Native API encryption key shown by NAMO.
- Wait up to about one minute for the first API connection after initial setup.
Repeat this for each physical NAMO device whose hardware sensors you want to expose.
Use Show API key on the device. If you select Reissue API key, all existing ESPHome Native API clients using the old key are disconnected. Update Home Assistant with the new key afterward.
System reset does not reveal, delete, or replace this key.
The current integration is not yet distributed as a verified HACS release. Install it manually for development preview use:
- Copy the repository directory
custom_components/namoto<Home Assistant config>/custom_components/namo. - Restart Home Assistant.
- Open Settings > Devices & services > Add integration.
- Select NAMO.
- If automatic discovery is unavailable, enter the address of any online NAMO device in the Site.
The entry is keyed by the stable Site identity rather than the IP address. A changed route or coordination device should update the existing entry instead of creating a duplicate.
[photo: Home Assistant Add Integration dialog showing NAMO discovery or manual host entry]
Each logical Space exposes:
- occupancy;
- motion;
- target count;
- health:
healthy,degraded, orunavailable; - detection mode: standalone, single sensor, or multiple sensors;
- fusion status;
- online device count;
- configured device count;
- source data age.
Enabled shared automation areas on the canonical floorplan also become occupancy entities. Their identities remain stable across configuration-owner or group-leader handovers.
Device-local excluded, reduced, disabled, and calibration areas are sensor filters and are not exported as shared Home Assistant area entities.
NAMO does not convert an unreachable or stale source into a false “clear” state.
- A route change or timeout makes the affected entity unavailable.
- A short restart does not immediately create a Home Assistant Repair.
- A non-healthy Site that persists for 30 seconds creates a Repair issue.
- The Repair issue clears automatically after the Site recovers.
This behavior prevents a network outage from being interpreted as an empty room.
Use the Space occupancy entity for automations that must remain stable when the coordinating physical device changes. Use motion when an action should react only to recent movement. Use target count only when the automation can tolerate the radar's normal multi-target uncertainty.
For critical lighting or HVAC shutdowns:
- require occupancy to remain clear for a delay;
- do not treat
unavailableas clear; - check the Space health or fusion status before taking destructive actions;
- keep a manual override.
Add the NAMO custom integration once per Site, not once per physical node. One Site entry discovers its logical Spaces and routes requests to the current calculation devices.
ESPHome integrations remain per physical node. It is normal to see several ESPHome devices and one NAMO Site entry for the same installation.
- Add the device manually by IP address.
- Confirm that Home Assistant and NAMO can reach each other on the local network.
- Wait for the initial Native API preparation to finish.
- Check that multicast discovery is not blocked between VLANs.
Open Management/Backup > Show API key and compare it again. If the key was reissued, remove or reconfigure the old ESPHome connection with the new key.
- Confirm that the entered device is online and belongs to the intended Site.
- Try the device IP address instead of its
.localname. - If the Site is converging after a restart, wait and reload the integration.
- Do not add every physical node as a separate NAMO entry.
A short unavailable period can occur while the route changes. If it persists, check the NAMO dashboard for Site health, online device count, and fusion status before reloading or removing the Home Assistant entry.