Telegram Device Telemetry & Anti-Theft Bot

A lightweight, zero-dependency background bot for Linux devices (laptops, desktops, servers, Raspberry Pis). It runs silently waiting for Telegram commands to deliver live device telemetry, exact street-level location, anti-theft tools, and proactive smart alerts.

---

Features

• Street-Level Geolocation: Uses nearby Wi-Fi BSSID triangulation (via Apple Location DB & OpenStreetMap reverse geocoding) to determine physical coordinates down to ~50m with street names, even through Starlink / VPN / CGNAT.
• Battery & Power Telemetry: Real-time battery percentage, charging/discharging state, and AC adapter detection.
• Network Monitoring: Active Wi-Fi SSID, signal percentage, interface name, local LAN IP, public IP, and ISP/Organization name.
• System Health: Hostname, OS/Kernel, uptime, RAM consumption, and disk storage usage.
• Webcam Snap: Silently capture a photo from the laptop webcam and send it to Telegram.
• Remote Screen Lock: Lock the Linux desktop remotely.
• Loud Alarm: Play a siren sound at max volume to find a device or deter tampering.
• Smart Alerts: Automatic low battery, power disconnect, and Wi-Fi change alerts.
• Multi-Device Fleet: Name each device and query specific machines or all at once.
• Remote Power Controls: Put devices to sleep or reboot them remotely.
• Chat ID Whitelisting: Restrict bot access to authorized Telegram accounts only.
• Zero External Python Dependencies: Built entirely using Python 3 standard libraries.

---

Quick Installation (On any Linux machine)

1. Clone or Copy the Repository

git clone <YOUR_REPO_URL> device-beacon
cd device-beacon

2. Run the 1-Step Automated Installer

You can pass your Bot Token directly:

./install.sh "YOUR_TELEGRAM_BOT_TOKEN"

Or simply run ./install.sh and it will prompt you to enter the token.

The installer will:

1. Validate Python 3.
2. Save your configuration.
3. Create and start a persistent systemd user service (telegram-device-bot.service).

---

Telegram Commands

Telemetry

Command	Description
/status	Full device report + interactive map pin
/loc	High-accuracy map pin, street address & Google Maps link
/battery	Battery level (%) and power source (AC/Battery)
/network	Connected Wi-Fi SSID, signal %, local IP, public IP, and ISP
/ping	Health check to verify the device listener is online
/help	Displays command reference

Anti-Theft

Command	Description
/snap	Capture webcam photo and send it to Telegram
/lock	Remotely lock the Linux screen (loginctl)
/alarm	Play a loud alarm sound at max volume

Power Controls

Command	Description
/sleep	Put the device into suspend/sleep mode
/reboot	Remotely reboot the machine

Multi-Device Fleet

Command	Description
/status all	Request status from all fleet devices
/status <name>	Query a specific named device

---

Configuration (config.json)

{
  "bot_token": "YOUR_TELEGRAM_BOT_TOKEN",
  "chat_id": "",
  "allowed_chat_ids": ["6711092933"],
  "device_name": "Work Laptop",
  "hourly_broadcast_enabled": false,
  "hourly_broadcast_interval_seconds": 3600,
  "smart_alerts_enabled": false,
  "low_battery_threshold": 15,
  "alert_on_power_disconnect": true,
  "alert_on_network_change": true
}

Config Fields

Field	Type	Description
bot_token	string	Telegram bot token from @BotFather
chat_id	string	Auto-detected on first message
allowed_chat_ids	array	Whitelist of Telegram user IDs. Empty = allow all
device_name	string	Friendly name for this machine (e.g. "Work Laptop")
hourly_broadcast_enabled	bool	Send automatic telemetry every hour
hourly_broadcast_interval_seconds	int	Broadcast interval in seconds (default: 3600)
smart_alerts_enabled	bool	Enable proactive smart alerts
low_battery_threshold	int	Battery % threshold for low battery alert (default: 15)
alert_on_power_disconnect	bool	Alert when charger is unplugged
alert_on_network_change	bool	Alert when connected to a different Wi-Fi network

After editing, restart the service:

systemctl --user restart telegram-device-bot.service

---

Service Management

# Check service status
systemctl --user status telegram-device-bot.service

# View real-time logs
journalctl --user -u telegram-device-bot.service -f

# Restart service
systemctl --user restart telegram-device-bot.service

# Stop service
systemctl --user stop telegram-device-bot.service

---

Uninstalling

To remove the service and configuration:

./uninstall.sh