A Home Assistant custom integration for the USR-R16 — a 16-channel TCP relay board manufactured by USR IOT.
This is a fork of blindlight86/HA_USR-R16, rewritten as a proper config-entry-based integration compatible with modern Home Assistant versions.
- 16 relay switches exposed as individual
switchentities - Auto-discovery of USR-R16 devices on the local network (UDP broadcast + TCP scan)
- Local push connection over TCP — no cloud dependency
- Automatic reconnection on connection loss
- Keep-alive mechanism to maintain the TCP link
- UI-based configuration via the Home Assistant Config Flow
- HACS-compatible
| Requirement | Version |
|---|---|
| Home Assistant | ≥ 2022.7.5 |
- Open HACS in your Home Assistant instance.
- Go to Integrations → click the three-dot menu → Custom repositories.
- Add
https://github.com/Elwinmage/ha-usr-r16-componentas an Integration. - Search for USR-R16 and click Download.
- Restart Home Assistant.
- Go to Settings → Devices & Services → Add Integration.
- Search for USR r16.
- Choose a setup method:
Select Auto-discover to let the integration scan your local network automatically.
The integration uses two complementary methods:
- UDP broadcast (port 1901) — sends the USR proprietary discovery packet; devices reply with their IP and name. Fast (~3 s) but may be blocked by some managed switches or routers.
- TCP port scan (port 8899) — probes every host on your subnet in parallel as a fallback, in case UDP broadcast is filtered.
Once the scan completes, a list of discovered devices is shown. Devices that are already configured appear in the list but are marked as such and cannot be selected again. Select the device you want to add, confirm the password, and click Submit.
If no new device is found, the flow automatically falls back to manual entry.
Select Manual to enter the connection details directly:
| Field | Description | Default |
|---|---|---|
| Host | IP address of the USR-R16 device | (required) |
| Port | TCP port of the device | 8899 |
| Password | Device password | admin |
Click Submit. Home Assistant will attempt to connect and validate the credentials.
Once added, 16 switch entities are automatically created, named usr_r16_1 through usr_r16_16, corresponding to the 16 relay channels.
The USR-R16 is a 16-channel relay controller communicating over TCP. It is commonly used in home automation setups for controlling lights, pumps, or other equipment.
- Protocol: TCP (Local Push)
- Default port: 8899
- Default password:
admin - Channels: 16 independently controllable relays
Each relay channel is exposed as a switch entity supporting the following actions:
| Action | Description |
|---|---|
turn_on |
Closes the relay (ON) |
turn_off |
Opens the relay (OFF) |
toggle |
Toggles the relay state |
Availability is tracked in real time: entities become unavailable if the TCP connection drops, and recover automatically when reconnected.
- Connection type: Local Push (event-driven, no polling)
- Discovery — UDP broadcast port: 1901
- Discovery — TCP scan port: 8899
- Reconnect interval: 10 seconds
- Keep-alive interval: 3 seconds
- Connection timeout: 10 seconds
- YAML import: Legacy
configuration.yamlentries are automatically migrated to config entries
No device found during auto-discovery
- Make sure the USR-R16 is powered on and connected to the same network as Home Assistant.
- If your network uses VLANs or a managed switch, UDP broadcast may be blocked — use Manual entry instead and enter the IP address directly.
- Try increasing the scan timeout if your network is slow.
Cannot connect
- Verify the IP address and port of your USR-R16 device.
- Make sure the device is reachable from your Home Assistant host (try
pingortelnet <host> 8899). - Check that the password is correct (default:
admin).
Device already configured
- Each host/port combination can only be added once. If the device appears greyed out in the discovery list, it is already configured. Remove the existing entry before adding it again.
Entities unavailable after restart
- The integration reconnects automatically. Wait a few seconds; if the issue persists, check your network connectivity to the device.
- Repository: github.com/Elwinmage/ha-usr-r16-component
- Issue tracker: github.com/Elwinmage/ha-usr-r16-component/issues
- Original fork: github.com/blindlight86/HA_USR-R16
This project is licensed under the MIT License.