mirror of
https://github.com/jokob-sk/NetAlertX.git
synced 2025-12-06 17:15:38 -08:00
92 lines
4.5 KiB
Markdown
Executable File
92 lines
4.5 KiB
Markdown
Executable File
# Home Assistant integration overview
|
|
|
|
NetAlertX comes with MQTT support, allowing you to show all detected devices as devices in Home Assistant. It also supplies a collection of stats, such as number of online devices.
|
|
|
|
> [!TIP]
|
|
> You can install NetAlertX also as a Home Assistant addon [](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons) via the [alexbelgium/hassio-addons](https://github.com/alexbelgium/hassio-addons/) repository. This is only possible if you run a supervised instance of Home Assistant. If not, you can still run NetAlertX in a separate Docker container and follow this guide to configure MQTT.
|
|
|
|
## ⚠ Note
|
|
|
|
- Please note that discovery takes about ~10s per device.
|
|
- Deleting of devices is not handled automatically. Please use [MQTT Explorer](https://mqtt-explorer.com/) to delete devices in the broker (Home Assistant), if needed.
|
|
- For optimization reasons, the devices are not always fully synchronized. You can delete Plugin objects as described in the [MQTT plugin](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/_publisher_mqtt#forcing-an-update) docs to force a full synchronization.
|
|
|
|
|
|
## 🧭 Guide
|
|
|
|
> 💡 This guide was tested only with the Mosquitto MQTT broker
|
|
|
|
1. Enable Mosquitto MQTT in Home Assistant by following the [documentation](https://www.home-assistant.io/integrations/mqtt/)
|
|
|
|
2. Configure a user name and password on your broker.
|
|
|
|
3. Note down the following details that you will need to configure NetAlertX:
|
|
|
|
- MQTT host url (usually your Home Assistant IP)
|
|
- MQTT broker port
|
|
- User
|
|
- Password
|
|
|
|
4. Open the _NetAlertX_ > _Settings_ > _MQTT_ settings group
|
|
|
|
- Enable MQTT
|
|
- Fill in the details from above
|
|
- Fill in remaining settings as per description
|
|
- set MQTT_RUN to schedule or on_notification depending on requirements
|
|
|
|
![Configuration Example][configuration]
|
|
|
|
## 📷 Screenshots
|
|
|
|
| ![Screen 1][sensors] | ![Screen 2][history] |
|
|
|----------------------|----------------------|
|
|
| ![Screen 3][list] | ![Screen 4][overview] |
|
|
|
|
|
|
[configuration]: ./img/HOME_ASISSTANT/HomeAssistant-Configuration.png "configuration"
|
|
[sensors]: ./img/HOME_ASISSTANT/HomeAssistant-Device-as-Sensors.png "sensors"
|
|
[history]: ./img/HOME_ASISSTANT/HomeAssistant-Device-Presence-History.png "history"
|
|
[list]: ./img/HOME_ASISSTANT/HomeAssistant-Devices-List.png "list"
|
|
[overview]: ./img/HOME_ASISSTANT/HomeAssistant-Overview-Card.png "overview"
|
|
|
|
## Troubleshooting
|
|
|
|
If you can't see all devices detected, run `sudo arp-scan --interface=eth0 192.168.1.0/24` (change these based on your setup, read [Subnets](./SUBNETS.md) docs for details). This command has to be executed the NetAlertX container, not in the Home Assistant 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 when accessing the UI of NetAlertX).
|
|
|
|
## Accessing the NetAlertX container via SSH
|
|
|
|
1. Log into your Home Assistant host via SSH
|
|
|
|
```bash
|
|
local@local:~ $ ssh pi@192.168.1.9
|
|
```
|
|
2. Find the NetAlertX container name, in this case `addon_db21ed7f_netalertx`
|
|
|
|
```bash
|
|
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. SSH into the NetAlertX cointainer
|
|
|
|
```bash
|
|
pi@raspberrypi:~ $ sudo docker exec -it addon_db21ed7f_netalertx /bin/sh
|
|
/ #
|
|
```
|
|
|
|
4. Execute a test `asrp-scan` scan
|
|
|
|
```bash
|
|
/ # 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 result doesn't contain results similar to the above, double check your subnet, interface and if you are dealing with an inaccessible network segment, read the [Remote networks documentation](./REMOTE_NETWORKS.md). |