Pi.Alert: Device Monitoring/ IP address inventory tool

alfwro13 · June 20, 2023, 10:31am

I would like to share a little gem I have recently discovered on GitHub. As soon as I started developing my own ESPHome devices, I realized that my IPv4 home range was getting messy, and keeping up with the changes was becoming challenging. Sadly, Home Assistant doesn’t have a built-in way of managing this. However, I have found a solution: Pi.Alert. It has been my best new friend lately.

You can find Pi.Alert on GitHub at the following link:

Pi.Alert

Pi.Alert scans the devices connected to your WiFi/LAN and alerts you to the connection of unknown devices. It also provides warnings when an “always connected” device disconnects. Additionally, Pi.Alert offers the ability to check the availability of web services.

The setup process is well explained on the website, so I won’t repeat it here.

Pi.Alert provides a very basic API, and the author explains how to integrate it with Home Assistant. You can find instructions on how to do this in the following link:

Pi.Alert API Usage with Home Assistant

I hope someone will find this little piece of software as useful as I did.

nickrout · June 20, 2023, 11:35am

Looks to be very handy.

paddy0174 · June 20, 2023, 11:42am

Nice one! Thanks for sharing!

nicola_s · February 5, 2024, 10:37am

Hello,
due the changes on 2023.6,

the way to define a command_lines sensor changed

This is the update sensor definition for PiAlert properties

command_line: 
  - sensor:
      name: "PiAlert - Last Scan"
      command: curl -k -X POST -F 'api-key=--todo-api-key-here--' -F 'get=system-status' http://[mypialerthost]/pialert/api/
      scan_interval: 200
      unique_id: pialert.status.lastscan
      value_template: '{{ value_json.Last_Scan }}'

  - sensor:
      name: "PiAlert - All Devices"
      command: curl -k -X POST -F 'api-key=--todo-api-key-here--' -F 'get=system-status' http://[mypialerthost]/pialert/api/
      scan_interval: 200
      unique_id: pialert.status.alldevices
      unit_of_measurement: ""
      value_template: '{{ value_json.All_Devices }}'

  - sensor:
      name: "PiAlert - Online Devices"
      command: curl -k -X POST -F 'api-key=--todo-api-key-here--' -F 'get=system-status' http://[mypialerthost]/pialert/api/
      scan_interval: 200
      unique_id: pialert.status.onlinedevices
      unit_of_measurement: ""
      value_template: '{{ value_json.Online_Devices }}'

  - sensor:
      name: "PiAlert - Offline Devices"
      command: curl -k -X POST -F 'api-key=--todo-api-key-here--' -F 'get=system-status' http://[mypialerthost]/pialert/api/
      scan_interval: 200
      unique_id: pialert.status.offlinedevices
      unit_of_measurement: ""
      value_template: '{{ value_json.Offline_Devices }}'

  - sensor:
      name: "PiAlert - Archived Devices"
      command: curl -k -X POST -F 'api-key=--todo-api-key-here--' -F 'get=system-status' http://[mypialerthost]/pialert/api/
      scan_interval: 200
      unique_id: pialert.status.archiveddevices
      unit_of_measurement: ""
      value_template: '{{ value_json.Archived_Devices }}'

  - sensor:
      name: "PiAlert - New Devices"
      command: curl -k -X POST -F 'api-key=--todo-api-key-here--' -F 'get=system-status' http://[mypialerthost]/pialert/api/
      scan_interval: 200
      unique_id: pialert.status.newdevices
      unit_of_measurement: ""
      value_template: '{{ value_json.New_Devices }}'

  - sensor:
      name: "PiAlert - Scanning"
      command: curl -k -X POST -F 'api-key=--todo-api-key-here--' -F 'get=system-status' http://[mypialerthost]/pialert/api/
      scan_interval: 120
      unique_id: pialert.status.scanning
      value_template: '{{ value_json.Scanning }}'

Also mind that in my case, I had to add an “/pialert/” to the url as the api are not served from the root but from this secondary path

valsergi · February 19, 2024, 9:42am

Hello, implement what is described here in my system and it works correctly, but I have a question, would it be possible to have more detailed information on the new devices, directly on HA, or failing that, at least be able to have some information for when detects a new device make an automation, for a notice… THANK YOU!

alfwro13 · February 27, 2024, 9:00am

You will need to go to github (link in the first post) and raise that as a feature request.

jokob-sk · June 12, 2024, 11:51am

Hey

I had a few people coming to my fork from this thread so just FYI there are 2 apps, leiweibau’s (linked in the first post) and mine, which I renamed to NetAlertX to avoid confusion. If interested my fork comes with more detailed device sync into home assistant via MQTT:

github.com

jokob-sk/NetAlertX/blob/50a175bd566ca57c82863a3ef34c9ee13aff8f5c/docs/HOME_ASSISTANT.md

# 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.

## ⚠ 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. 


## 🧭 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)

This file has been truncated. show original

vmsman · June 24, 2024, 6:11pm

I like the GUI. I set up my subnets and I configured the ARP settings. On my network it quickly located the router and itself. Nothing else was found. I discovered that I needed to enable the ARP scan and then save the settings and it scanned. Still no other systems were found. Great GUI on the program, but I already know about my router and the Pi.Alert. Seems like a work in progress.

Update: I updated to NetAlertX and it seems about the same. I carefully configured my interface and the ARP. Looks like the issue is it doesn’t like running in a container despite being on the main LAN.

mterry63 · June 24, 2024, 9:20pm

FWIW I ran both in a Proxmox container without issue. Decided to keep pialert. I’m not running any firewalls on Proxmox, however. ARP scan picks up everything in my single subnet.

jokob-sk · June 26, 2024, 6:22am

Hey,

make sure you have the correct network interface specified and the container is running in --network=host. More info here:

nightfever · February 19, 2025, 11:03am

I freshly installed Pi.Alert from this scipt: https://github.com/community-scripts/ProxmoxVE/raw/main/ct/pialert.sh.
It recognizes WAN and itself, but nothing else.
Scan Status indicates that no scan is running, the 5 minutes counts down and resets.
When I do an arp-scan in the shell all my devices are listed.

Is there anything else to set up?

# General Settings
# ----------------------
PIALERT_PATH               = '/opt/pialert'
DB_PATH                    = PIALERT_PATH + '/db/pialert.db'
LOG_PATH                   = PIALERT_PATH + '/log'
PRINT_LOG                  = False
VENDORS_DB                 = '/usr/share/arp-scan/ieee-oui.txt'
PIALERT_APIKEY             = ''
PIALERT_WEB_PROTECTION     = False
PIALERT_WEB_PASSWORD       = '8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92'
NETWORK_DNS_SERVER         = '10.0.0.112'
AUTO_UPDATE_CHECK          = True
AUTO_DB_BACKUP             = False
AUTO_DB_BACKUP_KEEP        = 5
REPORT_NEW_CONTINUOUS      = False
NEW_DEVICE_PRESET_EVENTS   = True
NEW_DEVICE_PRESET_DOWN     = False
SYSTEM_TIMEZONE            = 'Europe/Berlin'
OFFLINE_MODE               = False

# Other Modules
# ----------------------
SCAN_WEBSERVICES           = True
ICMPSCAN_ACTIVE            = True
SATELLITES_ACTIVE = True

# Special Protocol Scanning
# ----------------------
SCAN_ROGUE_DHCP            = False
DHCP_SERVER_ADDRESS        = '0.0.0.0'

# Custom Cronjobs
# ----------------------
# The shortest interval is 3 minutes. All larger intervals must be integer multiples of 3 minutes.
AUTO_UPDATE_CHECK_CRON     = '0 3,9,15,21 * * *'
AUTO_DB_BACKUP_CRON        = '0 3 */2 * *'
REPORT_NEW_CONTINUOUS_CRON = '0 * * * *'
SPEEDTEST_TASK_CRON        = '00 7,22 * * *'

# Mail-Account Settings
# ----------------------
SMTP_SERVER                = 'smtp.gmail.com'
SMTP_PORT                  = 587
SMTP_USER                  = '[email protected]'
SMTP_PASS                  = 'password'
SMTP_SKIP_TLS	           = False
SMTP_SKIP_LOGIN	           = False

# WebGUI Reporting
# ----------------------
REPORT_WEBGUI              = True
REPORT_WEBGUI_WEBMON       = True
REPORT_TO_ARCHIVE          = 0
# Number of hours after which a report is moved to the archive. The value 0 disables the feature

# Mail Reporting
# ----------------------
REPORT_MAIL                = False
REPORT_MAIL_WEBMON         = False
REPORT_FROM                = 'Pi.Alert <' + SMTP_USER + '>'
REPORT_TO                  = '[email protected]'
REPORT_DEVICE_URL          = 'http://pi.alert/deviceDetails.php?mac='
REPORT_DASHBOARD_URL       = 'http://pi.alert/'

# Pushsafer
# ----------------------
REPORT_PUSHSAFER           = False
REPORT_PUSHSAFER_WEBMON    = False
PUSHSAFER_TOKEN            = 'ApiKey'
PUSHSAFER_DEVICE           = 'a'
PUSHSAFER_PRIO             = 0
PUSHSAFER_SOUND            = 22

# Pushover
# ----------------------
REPORT_PUSHOVER            = False
REPORT_PUSHOVER_WEBMON     = False
PUSHOVER_TOKEN             = '<Token>'
PUSHOVER_USER              = '<User>'
PUSHOVER_PRIO              = 0
PUSHOVER_SOUND             = 'siren'

# NTFY
#---------------------------
REPORT_NTFY                = False
REPORT_NTFY_WEBMON         = False
NTFY_HOST                  = 'https://ntfy.sh'
NTFY_TOPIC                 = 'replace_my_secure_topicname_91h889f28'
NTFY_USER                  = 'user'
NTFY_PASSWORD	           = 'password'
NTFY_PRIORITY 	           = 'default'
NTFY_CLICKABLE 	           = True

# Shoutrrr
# ----------------------
SHOUTRRR_BINARY            = 'armhf'
# SHOUTRRR_BINARY            = 'armhf'
# SHOUTRRR_BINARY            = 'arm64'
# SHOUTRRR_BINARY            = 'x86'

# Telegram via Shoutrrr
# ----------------------
REPORT_TELEGRAM            = False
REPORT_TELEGRAM_WEBMON     = False
TELEGRAM_BOT_TOKEN_URL     = '<Your generated servive URL for telegram - use $HOME/pialert/back/shoutrrr/<your Systemtyp>/shoutrrr generate telegram>'

# DynDNS and IP
# ----------------------
QUERY_MYIP_SERVER          = 'https://myipv4.p1.opendns.com/get_my_ip'
DDNS_ACTIVE                = False
DDNS_DOMAIN                = 'your_domain.freeddns.org'
DDNS_USER                  = 'dynu_user'
DDNS_PASSWORD              = 'A0000000B0000000C0000000D0000000'
DDNS_UPDATE_URL            = 'https://api.dynu.com/nic/update?'

# Automatic Speedtest
# ----------------------
SPEEDTEST_TASK_ACTIVE      = False

# Arp-scan Options & Samples
# ----------------------
ARPSCAN_ACTIVE             = True
MAC_IGNORE_LIST            = []
IP_IGNORE_LIST             = []
SCAN_SUBNETS               = '--localnet'
# SCAN_SUBNETS               = '--localnet --interface=eth0'
# SCAN_SUBNETS               = ['192.168.1.0/24 --interface=eth0','192.168.2.0/24 --interface=eth1']

# ICMP Monitoring Options
# ----------------------
ICMP_ONLINE_TEST           = 1
ICMP_GET_AVG_RTT           = 2

# Pi-hole Configuration
# ----------------------
PIHOLE_ACTIVE              = False
PIHOLE_VERSION             = 5
PIHOLE_DB                  = '/etc/pihole/pihole-FTL.db'
PIHOLE6_URL                = ''
PIHOLE6_PASSWORD           = ''
PIHOLE6_API_MAXCLIENTS     = 100
DHCP_ACTIVE                = False
DHCP_LEASES                = '/etc/pihole/dhcp.leases'
DHCP_INCL_SELF_TO_LEASES   = False

# Fritzbox Configuration
# ----------------------
FRITZBOX_ACTIVE            = False
FRITZBOX_IP                = '192.168.17.1'
FRITZBOX_USER              = 'user'
FRITZBOX_PASS              = 'password'

# Mikrotik Configuration
# ----------------------
MIKROTIK_ACTIVE            = False
MIKROTIK_IP                = '10.0.0.1'
MIKROTIK_USER              = 'user'
MIKROTIK_PASS              = 'password'

# UniFi Configuration
# -------------------
UNIFI_ACTIVE               = False
UNIFI_IP                   = '10.0.0.2'
UNIFI_API                  = 'v5'
UNIFI_USER                 = 'user'
UNIFI_PASS                 = 'password'
# Possible UNIFI APIs are v4, v5, unifiOS, UDMP-unifiOS, default

# OpenWRT Configuration
# ----------------------
OPENWRT_ACTIVE            = False
OPENWRT_IP                = '192.168.1.1'
OPENWRT_USER              = 'root'
OPENWRT_PASS              = ''

# Satellite Configuration
# -----------------------
SATELLITE_PROXY_MODE       = False
SATELLITE_PROXY_URL        = ''

# Maintenance Tasks Cron
# ----------------------
DAYS_TO_KEEP_ONLINEHISTORY = 60
DAYS_TO_KEEP_EVENTS        = 180

_Xander · May 5, 2025, 4:57pm

For who’s interested:

Instead of the curl command_line sensor which didn’t work for me in docker, I get the pialert.status in HA using the following configuration under sensor:

- platform: rest
  name: "PiAlert - Status"
  resource: "http://192.168.x.y/pialert/api/"
  method: POST
  headers:
    Content-Type: "application/x-www-form-urlencoded"
  payload: "api-key=[API-key]&get=system-status"
  json_attributes:
    - Last_Scan
    - All_Devices
    - Online_Devices
    - Offline_Devices
    - New_Devices
    - Down_Devices
    - Scanning
    - Offline_Devices_ICMP
    - Online_Devices_ICMP
  value_template: "{{ value_json.Last_Scan }}"
  scan_interval: 200
  unique_id: pialert.status