A Home Assistant custom integration that exposes selected entities as Belkin WeMo switches on the local network. Alexa discovers and controls them without cloud services or an Alexa skill — everything stays on your LAN, no port 80 required.
Based on the fauxmo project by Nathan Henrie, originally forked from makermusings/fauxmo.
+----------+ SSDP/UDP 1900 +-------------------------+
| | -----------------> | SSDP Responder |
| Alexa | <----------------- | (upnp.py) |
| Echo | one response per | responds with one entry |
| | WeMo device | per entity |
| | +------------+------------+
| | GET /setup.xml | per-device
| | --------------------------------+ TCP ports
| | POST /upnp/control/basicevent1 | (50000+)
| | <-------------------------------+
+----------+ SOAP responses +------------+------------+
| WeMo Device Servers |
| (wemo_api.py) |
| one aiohttp server per |
| exposed entity |
+------------+------------+
|
calls HA services
(turn_on / turn_off)
|
v
+-------------------------+
| Home Assistant |
| entity states |
+-------------------------+
- SSDP discovery — A UDP responder on port 1900 answers Alexa's M-SEARCH broadcasts. Each registered entity gets its own SSDP response advertising its individual HTTP server location.
- Per-entity WeMo servers — Each exposed entity runs its own
aiohttp HTTP server on a dedicated port (base port + deterministic
offset). Alexa fetches
GET /setup.xmland sends SOAP commands toPOST /upnp/control/basicevent1. - Entity control — On/off SOAP commands are translated to
homeassistant.turn_on/homeassistant.turn_offservice calls (scenes usescene.turn_on; scene turn_off is a no-op).
The Philips Hue emulation approach requires the HTTP server to be reachable on port 80, which conflicts with other services (e.g. NGINX, another web server). The Belkin WeMo approach gives each entity its own port in the 50000+ range — no port 80, no reverse proxy needed.
input_boolean, light, scene, script, switch
FauxMo supports up to 255 exposed entities per installation.
- Open HACS → Integrations → ⋮ (three dots) → Custom repositories.
- Add this repository URL and select category Integration.
- Search for FauxMo and click Download.
- Restart Home Assistant.
Copy custom_components/fauxmo/ into your Home Assistant
config/custom_components/ directory. Restart Home Assistant.
After installation, add the integration via the UI:
Settings → Devices & Services → Add Integration → FauxMo
| Option | Default | Description |
|---|---|---|
| Base port | 50000 | Starting TCP port. Each entity is assigned a port in the range [base_port, base_port + 255). |
Open the integration's Options to pick which entities to expose and set custom Alexa-visible names:
- Select entities from the supported domains (max 255).
- Set a custom name for each (or leave blank to use the entity's friendly name).
- Save. Changes apply immediately — no restart required.
If you have an existing Emulated Hue config entry, FauxMo will detect it on first setup and offer to import your entities automatically.
custom_components/fauxmo/
├── __init__.py # Integration lifecycle: setup, unload, options update
├── config_flow.py # Config flow UI (setup + options + migration)
├── const.py # Constants (ports, domain, WeMo protocol values)
├── diagnostics.py # Diagnostic data export
├── manifest.json # HA integration manifest
├── quality_scale.yaml # HA quality scale checklist
├── store.py # Persistent per-entity activity tracking
├── strings.json # Localisation source strings
├── translations/
│ └── en.json # English translations
├── upnp.py # SSDP/UPnP discovery responder
└── wemo_api.py # WeMo device servers (one per entity)
tests/components/fauxmo/
├── conftest.py # Shared fixtures
├── test_config_flow.py
├── test_wemo_api.py
├── test_init.py
├── test_store.py
└── test_upnp.py
- Per-entity ports — Each entity gets a deterministic port
(
base_port + sum(ord(c) for c in entity_id) % 255), with collision resolution. No port 80 dependency. - Deterministic serials — Device serial numbers are derived from entity names (matching the original fauxmo algorithm) so they remain stable across restarts.
- No polling — State is read from HA at SOAP request time; SSDP
uses UDP multicast. Classification:
local_push. - Debounce — A 300 ms debounce window prevents duplicate commands from multiple Alexa devices responding simultaneously.
- Activity tracking —
store.pyrecords per-entityfirst_discoveredandlast_controlledtimestamps, viewable in the diagnostics panel. - Auto-reload on port change — Changing the base port in the options flow triggers a full integration reload.
Because FauxMo emulates Belkin WeMo switches on your network, Home Assistant's built-in WeMo integration will detect them and show a discovery notification asking you to set up "Belkin WeMo". Ignore and dismiss this notification — these are your own emulated devices, not real WeMo hardware. You can click Ignore on the notification to prevent it from appearing again.
If Alexa doesn't find your devices, verify:
- SSDP reachable — Check HA logs for M-SEARCH activity from Alexa's IP.
- Device servers running — In the diagnostics panel, confirm
device_servers_runningmatches your entity count. - setup.xml reachable —
curl http://<HA_IP>:<device_port>/setup.xmlshould return Belkin device XML. - Same subnet — Alexa and HA must be on the same LAN subnet (SSDP multicast doesn't cross routers).
- Firewall — Ensure UDP 1900 and the device ports (default 50000–50254) are not blocked between Alexa and HA.
pytest tests/components/fauxmo/ -v# configuration.yaml
logger:
logs:
custom_components.fauxmo: debugProtocol implementation inspired by fauxmo by Nathan Henrie, originally forked from makermusings/fauxmo.
This project is provided under the same license as Home Assistant Core.