NetAlertX/docs/HOME_ASSISTANT.md

Home Assistant integration

NetAlertX includes MQTT support, allowing detected devices to appear as devices in Home Assistant. It also publishes various statistics, such as the number of online devices.

Tip

You can also install NetAlertX as a Home Assistant Add-on via the from the alexbelgium/hassio-addons repository. This is only available for supervised Home Assistant installations. If you're running Home Assistant Container or Home Assistant Core, you can instead run NetAlertX in a separate Docker container.

Warning

• Device discovery in Home Assistant takes approximately 10 seconds per device.
• Devices removed from NetAlertX are not automatically removed from Home Assistant. Use MQTT Explorer to delete them from the MQTT broker if required.
• For performance reasons, device definitions are not always fully synchronized. To force a complete synchronization, delete the MQTT Plugin Objects as described in the MQTT plugin documentation.

Mosquitto MQTT setup

1. Enable the Mosquitto MQTT integration in Home Assistant by following the official documentation.

2. Create an MQTT username and password on your broker.

3. Record the following information for configuring NetAlertX:

   • MQTT host URL (usually your Home Assistant IP address)
   • MQTT broker port
   • Username
   • Password

4. Open NetAlertX → Settings → MQTT.

   • Enable MQTT.
   • Enter the broker details from the previous step.
   • Configure the remaining settings as needed.
   • Set MQTT_RUN to either schedule or on_notification, depending on your requirements.

Screenshots

Troubleshooting

Missing devices

If some devices do not appear in Home Assistant, first verify that NetAlertX can detect them by running:

sudo arp-scan --interface=eth0 192.168.1.0/24

Replace the interface and subnet with values appropriate for your environment (see the Subnets documentation).

Run this command inside the NetAlertX container, not inside the Home Assistant container.

Accessing the NetAlertX container

You can access the NetAlertX container via Portainer on your host or via SSH. The container name will be something like addon_db21ed7f_netalertx (you can copy the db21ed7f_netalertx part from the browser URL when accessing the NetAlertX web interface).

1. Log into your Home Assistant host via SSH.

local@local:~ $ ssh pi@192.168.1.9

2. Find the NetAlertX container name.

pi@raspberrypi:~ $ sudo docker container ls | grep netalertx
06c540d97f67   ghcr.io/alexbelgium/netalertx-armv7:25.3.1                   "/init"               6 days ago      Up 6 days (healthy)    addon_db21ed7f_netalertx

3. Open a shell inside the NetAlertX container.

pi@raspberrypi:~ $ sudo docker exec -it addon_db21ed7f_netalertx /bin/sh
/ #

4. Run a test arp-scan.

/ # sudo arp-scan --ignoredups --retry=6 192.168.1.0/24 --interface=eth0
Interface: eth0, type: EN10MB, MAC: dc:a6:32:73:8a:b1, IPv4: 192.168.1.9
Starting arp-scan 1.10.0 with 256 hosts (https://github.com/royhills/arp-scan)
192.168.1.1     74:ac:b9:54:09:fb       Ubiquiti Networks Inc.
192.168.1.21    74:ac:b9:ad:c3:30       Ubiquiti Networks Inc.
192.168.1.58    1c:69:7a:a2:34:7b       EliteGroup Computer Systems Co., LTD
192.168.1.57    f4:92:bf:a3:f3:56       Ubiquiti Networks Inc.
...

If your output does not contain devices similar to those shown above, verify that your subnet configuration is correct (see the Subnets documentation), that you are scanning the correct network interface, and that the network segment is reachable. If the devices are located on a different or remote network, refer to the Remote Networks documentation.