This image is generated by Gemini

TelePiHomeReconBot

A private Telegram bot for monitoring your home LAN.

Hardware

• A Raspberry Pi 2, 4 where this script will be deployed. Tested on RPi2

Features

• Device Discovery: Scan LAN, detect devices
• Telegram Bot: Control via Telegram commands
• Device Tracking: Track devices by MAC address

Setup

1. Install System Dependencies

sudo apt install nmap python3-venv

2. Clone and Setup

git clone https://github.com/yourusername/telepihomereconbot.git
cd telepihomereconbot
python3 -v -m venv .venv
source venv/bin/activate
pip install -r requirements.txt

3. Configure

cp .env.example .env
nano .env

Add your settings:

• TELEGRAM_BOT_TOKEN - Get from @BotFather
• AUTHORIZED_USERS - Your Telegram user ID (get from @userinfobot)

4. Test Bot

python main.py --bot

Commands

Command	Description
/scan	Scan LAN for devices
/list	List tracked devices
/status	network status
/help	Show commands

Running as a Service

1. Create Service File

Create /etc/systemd/system/telepihomereconbot.service:

[Unit]
Description=TelePiHomeReconBot
After=network.target

[Service]
Type=simple
User=<user>
Group=<group>
WorkingDirectory=/home/<user>/telepihomereconbot
ExecStart=/home/<user>/telepihomereconbot/venv/bin/python main.py --bot
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Adjust the path (/home/<user>/telepihomereconbot) if your installation directory is different.

2. Reload systemd

sudo systemctl daemon-reload

3. Enable Service (start on boot)

sudo systemctl enable telepihomereconbot

4. Start Service

sudo systemctl start telepihomereconbot

5. Check Status

sudo systemctl status telepihomereconbot

6. View Logs

sudo journalctl -u telepihomereconbot -f

Service Commands Summary

Action	Command
Start	sudo systemctl start telepihomereconbot
Stop	sudo systemctl stop telepihomereconbot
Restart	sudo systemctl restart telepihomereconbot
Enable (boot)	sudo systemctl enable telepihomereconbot
Disable (boot)	sudo systemctl disable telepihomereconbot
Status	sudo systemctl status telepihomereconbot
View logs	sudo journalctl -u telepihomereconbot -f

Project Structure

telepihomereconbot/
├── .env              # Secrets (see .env.example)
├── config/
│   └── config.json   # Settings
├── src/
│   ├── bot.py        # Telegram handlers
│   ├── scanner/     # Network scanning
│   └── storage/     # SQLite database
├── main.py          # Entry point
└── requirements.txt

License

MIT