iotping

A simple ICMP-based device monitor with Telegram notifications. Pings devices at regular intervals and alerts you when they go offline or come back online.

Features

• ICMP-only monitoring - Uses raw ping, no TCP port scanning. All tested commercial IOT devices(Ewelink, Tuya) and of course all open source (Tasmota etc) work.
• Telegram notifications - Get alerts on your phone when devices go down
• LAN-based monitoring - Works when internet is down (as long as LAN is up). It cannot send telegram messages obviously, but it can check if devices are alive.
• Superior in detecting problems over built-in IoT notifications - Device "cloud" notifications often misfire due to internet connectivity issues; this method monitors locally and is more reliable. Example: For a WIFI plug(Tuya, Ewelink etc) connected to a freezer a network connection issue canot be distinguished from a power failure (using in App notifications), but iotping being a LAN device has no problem with this.
• Repeated notifications - Configurable and can be disabled
• Message queue - Caches notifications during network outages and sends them when connection is restored
• Configurable via JSON - Easy configuration file
• Debug mode - Optional verbose logging
• Log file support - Redirect output to file with ~ and $HOME expansion

Prerequisites

Static IP addresses required: Your LAN router/DHCP must be configured to assign static IPs to your IoT devices. This tool monitors devices by IP address, not hostname.

Use IP addresses in config: Always use IP addresses (e.g., 192.168.1.10) in the configuration file, not hostnames. Even if you have DNS/hostnames configured, use the IP addresses to avoid dependency on DNS resolution.

The device running iotping (presumably your home server) must be alive 24/7 and UPS powered. The UPS must also backup the Internet Appliances (Router, ONT, switch etc). To have Internet when the power is down.

Installation

# Build
go build -ldflags="-s -w" -trimpath

Configuration

Config file location: ~/.config/iotping/config.json

Create the directory and config:

mkdir -p ~/.config/iotping
cat >~/.config/iotping/config.json << 'EOF'{ "devices": { "DEVICE1": "192.168.1.10", // comments are allowed "DEVICE2": "192.168.1.11" /* C, C++ format */ }, "telegram-token": "YOUR_BOT_TOKEN", "telegram-chat-id": "YOUR_CHAT_ID", "interval": "60s", "failure-threshold": 3, "recovery-notify": true, "ping-timeout": "5s", "debug": false, "log-file": "~/logs/iotping.log", "repeat-interval": "1h", "max-repeat-notifications": 3}EOF

Secure your token: config.json contains your Telegram bot token. Make sure only your user can read it:

chmod 600 ~/.config/iotping/config.json

Config Options

Option	Type	Default	Description
devices	object	{}	Device name → IP address mapping (use IPs, not hostnames)
telegram-token	string	""	Telegram bot token (get from @BotFather)
telegram-chat-id	string	""	Your Telegram chat ID
interval	string	"60s"	Check interval (e.g., 30s, 5m, 1h)
failure-threshold	int	3	Failed pings before marking offline
recovery-notify	bool	true	Notify when device comes back online
ping-timeout	string	"5s"	Timeout for each ping
debug	bool	false	Enable verbose debug logging
log-file	string	""	Log file path (supports ~ and $HOME)
repeat-interval	string	"1h"	Interval between repeat notifications while offline
max-repeat-notifications	int	3	Maximum repeated notifications (0 = disabled)

Getting Telegram Credentials

1. Create a bot: Message @BotFather, send /newbot, follow instructions
2. Get token: BotFather will give you a token like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz
3. Get chat ID: Message @userinfobot or @raw_data_bot to get your chat ID

Running

# Just run it
./iotping
# In background with setsid
setsid -f ./iotping &# Autostart# crontab -e
@reboot setsid -f path/to/iotping
# Or use systemd

System Requirements

The program requires unprivileged ICMP to be enabled (most modern Linux distributions):

# Check current setting
cat /proc/sys/net/ipv4/ping_group_range
# If it shows "1 0" or doesn't include your user group, fix it:
sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"# Make permanent:echo'net.ipv4.ping_group_range = 0 2147483647'| sudo tee /etc/sysctl.d/99-ping.conf
sudo sysctl --system

If you can't enable unprivileged ICMP but have root access, you can use capabilities:

sudo setcap cap_net_raw+ep ./iotping

Or run as root (not recommended):

sudo ./iotping

License

MIT