Home Network Presence Bot

A lightweight Telegram bot that runs on your local network (e.g., a Raspberry Pi or home server) to track who is at home.

This bot solves the common "deep sleep" issue with modern smartphones (especially Samsung and iOS devices) where standard ping requests fail when the screen is off. It uses arping to force the device's Wi-Fi chip to respond, ensuring accurate presence detection.

Features

• Presence Detection (/whoishome): Scans the local network using aggressive ARP packets to see which predefined static IPs (family members, housemates) are currently connected.
• Whitelist Security: Only Telegram User IDs specified in the config.json can interact with the bot. It completely ignores strangers.
• Natural Language Processing: You don't have to use strict commands. Simply texting "who is at home" will trigger the scan.

Prerequisites

To run this bot, you need the following installed on your home server (e.g., Raspberry Pi):

1. Python 3 & Dependencies:

   sudo apt update
   sudo apt install python3 python3-pip
   pip3 install python-telegram-bot

2. Arping Tool (Crucial for bypassing deep sleep):

   sudo apt install iputils-arping

3. Local Static IPs: You must assign static IP addresses to the devices you want to track via your router's interface (DHCP Binding).

Getting Started

1. Clone this repository to your server using Git:

   git clone https://github.com/ggheroes/HomeNetworkPresenceTelegramBot.git
   cd HomeNetworkPresenceTelegramBot

2. Rename the configuration file using the mv (move) command:

   mv config.example.json config.json

3. Fill in your details inside config.json:

   • TELEGRAM_BOT_TOKEN: Your bot API token from BotFather.
   • ALLOWED_USER_IDS: The Telegram IDs of the people allowed to use the bot.
   • HOUSEMATES: The names and static IP addresses of the devices you want to track.

4. Run the bot:

   python3 bot.py

Running as a Background Service (systemd)

To ensure the bot starts automatically when your Raspberry Pi reboots, you can set it up as a systemd service:

1. Create a service file at /etc/systemd/system/home_bot.service:

[Unit]
Description=Telegram Home Bot
After=network.target

[Service]
ExecStart=/usr/bin/python3 /PATH/TO/YOUR/bot.py
WorkingDirectory=/PATH/TO/YOUR/
StandardOutput=inherit
StandardError=inherit
Restart=always
User=YOUR_USERNAME

[Install]
WantedBy=multi-user.target

2. Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable home_bot.service
sudo systemctl start home_bot.service

---

Built in collaboration with Google Gemini.