🐀 Houserat

A daemon that monitors network traffic for DHCP and ARP packets from known devices and sends a notification using Telegram when these devices connect or disconnect.

🚀 Usage

1. Create a Telegram bot and save its token.
2. Install using a package manager:
   • Arch Linux: AUR, e.g. yay -S houserat
   • Cargo: cargo install houserat (note that you'll have to manually install the service and config files)
3. Edit configuration at /etc/houserat/config.toml with bot token, device and user information (example).
4. Enable and start service: systemctl enable --now houserat.

🤖 Bot Configuration

Once you have your bot token you'll need to get chat IDs for every user that subscribes to notifications. The easiest way to do that is:

1. Have the user start a conversation with the bot or send any message to it.
2. Open https://api.telegram.org/bot<token>/getUpdates in a browser (replacing <token> with your bot token) and look for the chat ID, it should be in message.chat.id in the result array.
3. Put the chat ID you found in the chat_id field for that user in config.toml.
4. Optionally clearing the updates list by going back to the Telegram getUpdates API method and adding ?offset=<update_id+1>, where the update_id is found in the result. This would make it easier to find other chat IDs when repeating this process.

💫 How It Works

Houserat detects devices connecting to the network when they send a DHCP request packet. It will then notify that device's subscriber and start polling this device to detect when it goes away. Since phones don't always respond to PING packets houserat uses ARP requests which all devices must respond to.

When several ARP requests go unanswered the device is considered disconnected and a notification is sent to the subscriber.

💤 Anti-Spam

Houserat has several features designed to reduce notification spam:

• Configurable cooldown during which no new notifications are sent, for example if a device reconnects soon after its initial connection only 1 notification is sent.
• Configurable quiet period during which messages are sent without sound notifications. This can be used to avoid having noisy Telegram notifications at night.