OpenWrt (for Homeassistant)

A secure, production-ready Home Assistant integration for OpenWrt devices. Monitor system resources, track connected devices, manage WiFi radios, execute commands, and natively update firmware directly from Home Assistant.

🧭 Quick Links


✨ Features	📦 Installation	⚙️ Configuration	🛡️ Security
🛠️ Options	🧱 Services	📖 Automations	❓ FAQ
🧑‍💻 Development	💖 Credits	📄 License

Why use this integration?

While you can monitor routers via SNMP or ping trackers, this integration uses native OpenWrt APIs (Ubus/RPC) to provide deep, reliable integration without the overhead of polling generic network protocols. This means instant device tracking via modern ARP/NDP tables, full control over firewall rules and radios, and even the ability to compile firmware directly from your dashboard.

Supports OpenWrt 25.12 and newer (older versions may also work, but are not directly tested and supported within this integration; update to the latest release if possible).

✨ Features

VPN Monitoring:
- Tracks status (Up/Down) for WireGuard and OpenVPN tunnels.
- Monitors throughput (RX/TX) and WireGuard peer counts with handshake details.
Network & Connectivity:
- Latency/Ping: Monitor network latency to a target (e.g. 8.8.8.8) with packet loss tracking.
- DHCP Monitoring: Track the number of active DHCP leases.
- Public IP: Track your external WAN IP address with change detection.
- Advanced Interface Diagnostics: Individual sensors/attributes for IPv6 addresses, link speed (Mbps), duplex mode, and interface uptime.
4G/5G QModem Support (ModemManager integration):
- Comprehensive signal diagnostics: RSRP, RSRQ, RSSI, SINR for LTE and 5G.
- Device health: Modem temperature, voltage, and ISP detection.
- SIM status: Tracking SIM slots and connectivity state.
Configurable Control:
- WiFi TX Power: Native slider to control transmission power of WiFi radios.
- SQM (Smart Queue Management):
  - Control enabled state of SQM instances.
  - Set download and upload limits (Mbps) via native number sliders.
  - Diagnostic sensors for configured interface, qdisc, and setup script.
- Service Management: Monitor, start, stop, and restart system services (e.g., AdGuard Home, OpenVPN, Samba).
- Backup & Commands: Trigger configuration backups or execute arbitrary shell commands directly from HA.
Parental Control & Device Management:
- Internet Access Control: Per-device "Internet Access" switches to block/allow traffic (Fritz!Box style).
- Wireless Management: WPS control switches and buttons to kick (disconnect) specific wireless clients.
Smart Tracking & Events:
- Multi-source Device Tracking: Combines DHCP leases with ARP/NDP tables (ip neigh) for instant and reliable presence detection.
- Persistent History: Tracks initially_seen and last_seen timestamps for every device, persisting across Home Assistant restarts.
- Connection Type Detection: Automatically identifies if a device is connected via wired or a specific WiFi band (2.4GHz, 5GHz, 6GHz).
- Topology Mapping: Wireless clients are automatically linked to their respective Access Point via the via_device attribute.
- Infrastructure Filtering: Automatically identifies and filters out the router's own network interfaces to prevent circular self-tracking.
- New Device Event: Fires openwrt_new_device when previously unknown MAC addresses are discovered.
Advanced Diagnostics:
- Refined Naming: Routers are primarily identified by their product model (e.g. "Xiaomi AX3600") for a premium dashboard look.
- LLDP Neighbors: Discover and monitor physical port connections via the LLDP protocol (if available on the router).
Optimized for Large Environments:
- Parallel API calls and background platform loading prevent Home Assistant blocking warnings and ensure smooth startup even with 100+ devices.
Native Experience:
- Full Localization: English and German translations included.
- HA Repairs: Integrated check for auth failures, missing packages, and permission issues.

❤️ Support This Project

I maintain this integration in my free time alongside my regular job — bug hunting, new features, testing on real devices. Test hardware costs money, and every donation helps me stay independent and dedicate more time to open-source work.

This project is and will always remain 100% free. There are no "Premium Upgrades", paid features, or subscriptions. Every feature is available to everyone.

Donations are completely voluntary — but the more support I receive, the less I depend on other income sources and the more time I can realistically invest into these projects. 💪

📦 Installation

HACS (Recommended)

This integration is fully compatible with HACS.

Note

This integration is currently a custom repository. A Pull Request to include it in the HACS default repositories is already pending.

Open HACS in Home Assistant.
Click on the three dots in the top right corner and select Custom repositories.
Add FaserF/ha-openwrt with category Integration.
Search for "OpenWrt".
Install and restart Home Assistant.

Manual Installation

Download the latest release from the Releases page.
Extract the custom_components/openwrt folder into your Home Assistant's custom_components directory.
Restart Home Assistant.

⚙️ Configuration

🛡️ Security Note: Before configuring the integration, please read our Security Best Practices regarding dedicated accounts, restricting permissions, and connection methods. Using root is supported but not recommended.

Adding your OpenWrt router is entirely done via the UI. No YAML configuration is required.

Navigate to Settings > Devices & Services in Home Assistant.
Click Add Integration and search for OpenWrt.
Follow the guided setup:
- Select your connection method: Ubus (HTTP/HTTPS) is highly recommended.
- Enter your router's IP/Hostname, Username (usually root), and Password.
- For Ubus, ensure the rpcd package is installed on your router.

Supported Connection Methods

Feature	Ubus (Recommended)	LuCI RPC	SSH
Performance	🚀 Very Fast	🚄 Fast	🐌 Slow
Ease of Setup	✅ Easy	✅ Easy	⚠️ Complex
Permissions	🛡️ Strict (ACLs)	🔓 Permissive	👑 Full (Root)
Reliability	✅ High	✅ High	⚠️ Moderate
Device Tracking	✅ Instant	✅ Instant	✅ Fast
Backups/Update	✅ Full	✅ Full	❌ Limited

🔑 Which method should I choose?

Ubus (HTTP/HTTPS): The gold standard. If your router supports it and permissions are set up correctly, use this. It's the most stable and efficient.
LuCI RPC: The perfect fallback. If Ubus is giving you "Access Denied" errors (common on newer OpenWrt SNAPSHOTs or restricted firmware), switch to LuCI RPC. It often has more permissive default access to system sensors like temperature and client lists.
SSH: Use only if HTTP/HTTPS is not possible or if you need to bypass all RPC restictions entirely. Note that SSH causes higher CPU load on the router during polling.

Required Permissions

If you are using a non-root user (e.g. for security reasons), you need to grant specific OpenWrt permissions (via rpcd ACLs or LuCI) to utilize all features of this integration:

Subsystem	Description	Write Permission Required for
System	Read router info, stats (Hostname, Load, Memory, Temp, Storage)	Rebooting router, sysupgrade, backups
Network	Read interfaces, bytes/packets counters, speeds	Toggling & reconnecting interfaces
Wireless	Read WiFi radios, SSIDs, signal levels, client lists	Toggling radios/SSIDs, WPS control
Firewall	Read firewall rules & port forwards	Toggling rules/forwards, Parental Control (Device Blocking)
Devices	Read DHCP Leases, ARP/Neighbor table (Connected devices)	Wake on LAN, Kicking wireless clients
VPN	Read WireGuard & OpenVPN status	-
SQM	Read SQM instance status	Toggling SQM, Changing bandwidth limits
Services	Read active system services (OpenVPN, AdGuard, etc.)	Toggling & restarting services
LEDs	Read current state of router LEDs	Toggling LEDs, changing brightness
MWAN3	Read Multi-WAN load balancing status	-

During setup, the integration will check your user's permissions and display a summary of available features.

Required Packages

Some features require additional OpenWrt packages to be installed on your router. During setup, the integration will check if these are installed.

Package	Missing Features
sqm-scripts	SQM QoS Settings (Limits, Toggles)
mwan3	MWAN3 Sensors (Load balancing status)
iwinfo	Enhanced WiFi Info (Bitrate, detailed signal diagnostics)
etherwake	Wake on LAN functionality
wireguard-tools	WireGuard VPN Sensors
openvpn	OpenVPN Sensors

🛠️ Options Flow

After configuration, click Configure on the integration page to adjust:

Update Interval: How frequently to poll data (default 30s). Adjust based on your router's performance.
Device Tracking: Enable/disable device tracking.
Track Wired Devices: If enabled, Home Assistant will also track devices found in the ARP/Neighbor table, even if they aren't on WiFi.
Consider Home: Set the grace period (in seconds) for device presence detection (prevents devices from switching to "Away" during brief sleep cycles).
DHCP Software:
- Auto-detect: Best for most users.
- dnsmasq: Uses /tmp/dhcp.leases.
- odhcpd: Uses ubus call dhcp ipv4leases.
- none: Disables dynamic IP/hostname resolution to save resources.
Custom Firmware Repo: Provide a GitHub repo (e.g., owner/repo) if you use custom OpenWrt community builds to check for updates.
Attended Sysupgrade Server: Configure the URL for the ASU server (default: https://sysupgrade.openwrt.org).

🧱 Services

The integration provides several powerful services for advanced control.

`openwrt.reboot`

Reboots the OpenWrt router.

entry_id: (Optional) The config entry ID of the router to reboot.

`openwrt.manage_service`

Manage system services (init.d) on the router.

service_name: The name of the service (e.g., dnsmasq).
action: One of start, stop, restart, enable, disable.

`openwrt.execute_command`

Execute arbitrary shell commands on your router.

command: The command to run (e.g., /etc/init.d/uhttpd restart).

`openwrt.uci_get`

Read a value from the UCI configuration. Returns the value as a service response.

config, section, option: The UCI path components.

`openwrt.uci_set`

Modify any UCI setting and commit the change immediately.

config, section, option, value: The target setting.

`openwrt.wake_on_lan`

Send a Magic Packet through the router to wake up a device.

mac: Target MAC address.
interface: (Optional) The interface to use (e.g., br-lan).

`openwrt.create_backup`

Triggers a configuration backup and returns the path to the backup file.

📖 Automation Examples

🔄 Reboot Router Weekly

alias: "Router: Weekly Reboot"
trigger:
  - platform: time
    at: "03:00:00"
condition:
  - condition: time
    weekday:
      - sun
action:
  - device_id: <YOUR_OPENWRT_DEVICE_ID>
    domain: button
    entity_id: button.openwrt_reboot_router
    type: press

🚨 Notification on WAN Disconnect

alias: "Router: WAN Disconnect Notification"
trigger:
  - platform: state
    entity_id: binary_sensor.openwrt_wan_connected
    to: "off"
    for:
      minutes: 1
action:
  - service: notify.notify
    data:
      title: "🚨 Internet Connection Lost"
      message: "The main WAN interface on the OpenWrt router went down."

🔄 Firmware Update Notification

alias: "Router: Firmware Update Available"
trigger:
  - platform: state
    entity_id: update.openwrt_firmware
    attribute: latest_version
action:
  - service: notify.notify
    data:
      title: "🔄 OpenWrt Update Available"
      message: >-
        A new firmware update ({{ state_attr('update.openwrt_firmware', 'latest_version') }})
        is available for your router!

📡 Toggle Guest WiFi via Dashboard

alias: "Router: Toggle Guest WiFi"
trigger:
  - platform: state
    entity_id: input_boolean.guest_wifi_toggle
action:
  - service: switch.turn_{{ trigger.to_state.state }}
    target:
      entity_id: switch.openwrt_wireless_guest

🖥️ Execute Custom Command on Router

alias: "Router: Clear DNS Cache"
trigger:
  - platform: state
    entity_id: input_button.clear_router_dns
action:
  - service: openwrt.execute_command
    data:
      command: "/etc/init.d/dnsmasq restart"
    target:
      device_id: <YOUR_OPENWRT_DEVICE_ID>

💡 LED Night Mode - Turn off LEDs at Night

Turn off all router LEDs after midnight and turn them back on in the morning.

alias: "Router: LED Night Mode Off"
trigger:
  - platform: time
    at: "00:00:00"
action:
  - service: light.turn_off
    target:
      entity_id:
        - light.openwrt_led_power
        - light.openwrt_led_wan
        - light.openwrt_led_wireless

---

alias: "Router: LED Morning Mode On"
trigger:
  - platform: time
    at: "07:00:00"
action:
  - service: light.turn_on
    target:
      entity_id:
        - light.openwrt_led_power
        - light.openwrt_led_wan
        - light.openwrt_led_wireless

🌐 Port Forwarding Security: Disable at Night

Automatically disable sensitive port forwarding rules during night hours to reduce your attack surface.

alias: "Security: Disable Port Forwards (Night)"
trigger:
  - platform: time
    at: "23:00:00"
action:
  - service: switch.turn_off
    target:
      entity_id:
        - switch.openwrt_port_forward_ssh_external
        - switch.openwrt_port_forward_vpn_server

👶 Parental Control: Internet Schedule

Automatically disable internet access for specific devices during homework or bed time. Uses the Fritz-style "Internet Access" switches.

alias: "Guard: Child Internet Off (Bedtime)"
trigger:
  - platform: time
    at: "20:30:00"
action:
  - service: switch.turn_off
    target:
      entity_id:
        - switch.openwrt_internet_access_ipad_kids
        - switch.openwrt_internet_access_gaming_pc

🏎️ Dynamic Bandwidth Alert (Mbps)

Get notified if a specific interface exceeds a throughput threshold (e.g. 100 Mbps) for longer than 10 minutes.

alias: "Network: High Sustained Throughput"
trigger:
  - platform: numeric_state
    entity_id: sensor.openwrt_wan_rx_rate
    above: 100
    for:
      minutes: 10
action:
  - service: notify.mobile_app_faserf
    data:
      title: "🏎️ Sustained High Download Rate"
      message: "WAN interface has been saturating over 100Mbps for 10 minutes."

🔁 Auto-Reconnect on High Packet Errors

If the WAN interface accumulates more than 500 errors (monitored via the consolidated attributes), trigger an interface reconnect.

alias: "Network: Reconnect on Errors"
trigger:
  - platform: template
    value_template: "{{ state_attr('sensor.openwrt_wan_rx', 'errors') | int > 500 }}"
action:
  - service: button.press
    target:
      entity_id: button.openwrt_reconnect_wan

🚨 Notification on Public IP Change

Useful for home lab users without DDNS. Get notified as soon as your router gets a new external IP address.

alias: "Network: Public IP Changed"
trigger:
  - platform: state
    entity_id: sensor.openwrt_public_ip
action:
  - service: notify.notify
    data:
      title: "🌐 Router IP Updated"
      message: "The new public IP address is {{ trigger.to_state.state }}"

🚨 Notification on Network Errors (WAN)

alias: "Router: Network Error Alert"
trigger:
  - platform: template
    value_template: "{{ state_attr('sensor.openwrt_wan_rx', 'errors') | int > 100 }}"
action:
  - service: notify.notify
    data:
      title: "⚠️ Network Errors Detected"
      message: >-
        More than 100 RX errors detected on WAN.
        This may indicate cable or hardware issues.

🖥️ Wake on LAN: Wake PC via OpenWrt

Wakes up your PC when you arrive home or via an input button.

alias: "Automation: Wake Gaming PC"
trigger:
  - platform: state
    entity_id: input_button.wake_pc
action:
  - service: openwrt.wake_on_lan
    data:
      target: <YOUR_OPENWRT_ENTRY_ID>
      mac: "AA:BB:CC:DD:EE:FF"
      interface: "br-lan"

🧠 High Resource Usage Alert (CPU/Memory)

Get notified early if your router is struggling with high load, potentially preventing network outages or indicating a runaway background process.

alias: "Router: High Resource Usage Alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.openwrt_cpu_load_1m
    above: 4.0
    for:
      minutes: 5
  - platform: numeric_state
    entity_id: sensor.openwrt_memory_usage
    above: 90
    for:
      minutes: 5
action:
  - service: notify.notify
    data:
      title: "⚠️ Router Overload Warning"
      message: >-
        The OpenWrt router is experiencing sustained high resource usage!
        Trigger: {{ trigger.entity_id }} is currently at {{ trigger.to_state.state }}.

🙋‍♂️ Guest WiFi Automation Based on Presence

Automatically enable the Guest WiFi when a specific "Guest Mode" input boolean is turned on, or disable it when everyone leaves the house to improve security and reduce airtime congestion.

alias: "WiFi: Auto-Disable Guest Network"
trigger:
  - platform: state
    entity_id: zone.home
    to: "0"  # Everyone left home
    for:
      minutes: 10
action:
  - service: switch.turn_off
    target:
      entity_id: switch.openwrt_wireless_guest

🔁 Daily Router Reboot (Scheduled Maintenance)

Some specific setups or failing modems require a daily reboot. You can easily schedule this via Home Assistant natively rather than relying on OpenWrt cronjobs.

alias: "Router: Daily Maintenance Reboot"
trigger:
  - platform: time
    at: "04:00:00"
action:
  - service: button.press
    target:
      entity_id: button.openwrt_reboot_router

🔐 VPN Failure Alert

Get notified immediately if a specific VPN tunnel (WireGuard or OpenVPN) goes down.

alias: "Security: VPN Tunnel Down"
trigger:
  - platform: state
    entity_id: binary_sensor.openwrt_vpn_wg0_up
    to: "off"
    for:
      seconds: 30
action:
  - service: notify.notify
    data:
      title: "🔐 VPN Outage"
      message: "VPN Interface wg0 has disconnected!"

📡 New Device Connection Alert

Use the openwrt_new_device event to get notified whenever a new, previously unknown device connects to your network for the first time.

alias: "Security: New Device Detected"
trigger:
  - platform: event
    event_type: openwrt_new_device
action:
  - service: notify.notify
    data:
      title: "📡 New Device Found"
      message: "A new device with MAC {{ trigger.event.data.mac }} connected to {{ trigger.event.data.host }}."

📦 Automatic Backup Before Update

Automatically trigger a configuration backup right before a firmware update to ensure you can always restore your settings even if a flash goes wrong.

alias: "System: Auto-Backup on Update"
trigger:
  - platform: state
    entity_id: update.openwrt_firmware
    to: "installing"
action:
  - service: openwrt.create_backup
    data:
      entry_id: <YOUR_OPENWRT_ENTRY_ID>

📉 High Latency Notification

Monitor your internet connection quality and get notified if latency increases significantly, which might indicate ISP issues or network congestion.

alias: "Health: High WAN Latency"
trigger:
  - platform: numeric_state
    entity_id: sensor.openwrt_wan_latency
    above: 50
    for:
      minutes: 5
action:
  - service: notify.notify
    data:
      title: "📉 Network Latency Spike"
      message: "Current WAN latency is {{ states('sensor.openwrt_wan_latency') }}ms."

🏎️ SQM Night Mode (Speed Boost)

Automatically increase SQM bandwidth limits during night hours when network contention is lower.

alias: "Network: SQM Night Speed Boost"
trigger:
  - platform: time
    at: "01:00:00"
action:
  - service: number.set_value
    target:
      entity_id: number.openwrt_sqm_eth1_download
    data:
      value: 200
  - service: number.set_value
    target:
      entity_id: number.openwrt_sqm_eth1_upload
    data:
      value: 100

---

alias: "Network: SQM Day Speed Limit"
trigger:
  - platform: time
    at: "08:00:00"
action:
  - service: number.set_value
    target:
      entity_id: number.openwrt_sqm_eth1_download
    data:
      value: 100
  - service: number.set_value
    target:
      entity_id: number.openwrt_sqm_eth1_upload
    data:
      value: 50

⚡ WiFi Optimizer (Channel Scan)

Trigger a wireless optimization scan via custom command if high latency or packet loss is detected on a wireless interface.

alias: "WiFi: Optimize on High Latency"
trigger:
  - platform: numeric_state
    entity_id: sensor.openwrt_wan_latency
    above: 100
    for:
      minutes: 2
action:
  - service: openwrt.execute_command
    data:
      command: "wifi down && wifi up"
      entry_id: <YOUR_OPENWRT_ENTRY_ID>

📶 Modem: SMS Notification on ISP Change

If you have a dual-SIM or roaming modem, get notified when the carrier changes.

alias: "Modem: ISP Notfier"
trigger:
  - platform: state
    entity_id: sensor.openwrt_qmodem_isp
action:
  - service: notify.notify
    data:
      title: "🌍 Modem Switched Network"
      message: "The router is now connected via {{ states('sensor.openwrt_qmodem_isp') }}."

❓ Troubleshooting & FAQ

"Access Denied" or Permission Errors

OpenWrt's rpcd has very strict ACLs. Even root is sometimes restricted via the Ubus API.

Solution 1: Switch the connection method to LuCI RPC in the integration settings. It uses the same session as the web UI and often has more permissive defaults.
Solution 2: Check /etc/config/rpcd on your router and ensure your user has the required scopes.

Sensors show "Unavailable"

Check Settings > System > Repairs in Home Assistant. The integration will create a repair issue if there's a specific API or package error.
Ensure the required packages (like iwinfo or uhttpd-mod-ubus) are installed.

How do I use the "Internet Access" switches?

The "Internet Access" switches in Home Assistant act as a toggle for the firewall. When turned off, the router creates a temporary firewall rule to drop all traffic from that specific device's MAC address. This provides simple, reliable parental control without complex VLANs.

Why are some Signal sensors hidden?

The integration automatically hides "STA-style" sensors (Signal, Quality, Bitrate) if the WiFi interface is in Master/AP mode. These values only make sense when the router itself is acting as a client (Station) or Mesh node.

🧑‍💻 Development

This project uses modern Python development tools:

ruff for linting and formatting
mypy for static typing
pytest for unit testing

Setup

python3 -m venv venv
source venv/bin/activate
make install

Pre-commit

Before committing, run tests and linters:

make check

💖 Credits & Acknowledgements

This integration was built from the ground up to replace and modernize the deprecated community project, ensuring long-term maintainability and eliminating persistent edge-case bugs.

A special thanks to:

kvj/hass_openwrt: The original repository which served as the inspiration and reference for OpenWrt integration concepts.
Home Assistant fritz Integration: The official Fritz!Box integration, which served as the gold standard for feature parity, particularly regarding the robust device_tracker scanner implementation and multi-platform architecture.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github		.github
custom_components/openwrt		custom_components/openwrt
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
hacs.json		hacs.json
pyproject.toml		pyproject.toml
renovate.json		renovate.json

Folders and files

Latest commit

History

Repository files navigation

OpenWrt (for Homeassistant)

🧭 Quick Links

Why use this integration?

✨ Features

❤️ Support This Project

📦 Installation

HACS (Recommended)

Manual Installation

⚙️ Configuration

Supported Connection Methods

🔑 Which method should I choose?

Required Permissions

Required Packages

🛠️ Options Flow

🧱 Services

openwrt.reboot

openwrt.manage_service

openwrt.execute_command

openwrt.uci_get

openwrt.uci_set

openwrt.wake_on_lan

openwrt.create_backup

📖 Automation Examples

❓ Troubleshooting & FAQ

"Access Denied" or Permission Errors

Sensors show "Unavailable"

How do I use the "Internet Access" switches?

Why are some Signal sensors hidden?

🧑‍💻 Development

Setup

Pre-commit

💖 Credits & Acknowledgements

📄 License

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 5

Contributors