How alexwbaule/telegramopenwrt works
Project type and purpose
• This is an open-source, plugin-based toolkit written in Bash for managing and retrieving information from OpenWrt routers over Telegram. It provides both:
• An event-driven “watcher” service (e.g., lanports, hosts_scan) that monitors router state and proactively notifies via Telegram.
• A polling-based “command processor” service (telegram_bot) that receives user commands from Telegram, dispatches them to plugins, and returns results.
File structure
• Top-level directories:
• etc/config/telegramopenwrt – UCI-style config (bot token, chat ID, settings)
• etc/init.d – SysV init scripts to launch services at boot (lanports, telegram_bot, hosts_scan)
• etc/telegramopenwrt/macaddr.ignore – ignore-list data file
• sbin/ – executable scripts installed into /sbin on the router (lanports, telegram_bot, telebot/telegram_sender, hosts_scan, etc.)
• usr/lib/telegramopenwrt/plugins/ – plugin API:
– actions/ – scripts that perform work in response to a user or context choice
– ctx/ – context scripts that gather user input and invoke actions
– help/ – static help text per command
– top-level plugin scripts (get_ip, fw_add, wifi_list, etc.)
Architecture insights from README
• Two principal services:
• lanports (and other init.d watchers) → monitors logread, DHCP events → invokes telebot/telegram_sender to send alerts
• telegram_bot → loops getUpdates → matches incoming commands → locates plugin in usr/lib/... → executes plugin → sends response via Telegram API
• Plugin design: each command has an optional ctx (for multi-step interaction) and action script, plus a help file for documentation.
a. Main components
• Configuration Store (etc/config/telegramopenwrt + macaddr.ignore)
• Init system (OpenWrt init.d)
• Event Watcher Services (lanports, hosts_scan)
• Command Poller Service (telegram_bot)
• Plugin Dispatcher & Plugins (usr/lib/telegramopenwrt/plugins/{ctx,actions,help,commands})
• Telegram API (external HTTPS endpoint)
• Router Subsystems (network interface, firewall/iptables, UCI, cameras, TV, file system)
b. Relationships and data flows
1. At boot, init.d registers & starts watchers and poller
2. Event Watchers → read logs (logread -f), DHCP leases → format alert → call telebot/telegram_sender → HTTP POST → Telegram API
3. Command Poller (telegram_bot) → HTTPS GET /getUpdates → receives update → invokes Plugin Dispatcher → plugin script interacts with Router Subsystems (uci, iptables, netstat, camera CLI, etc.) → returns output → HTTP POST /sendMessage → Telegram API → user
c. Architectural patterns
• Plugin architecture (loose coupling via filesystem)
• Producer/consumer: watchers produce alerts, poller consumes commands
• Context‐action pattern: ctx scripts for multi‐step UI, actions for atomic operations
d. Key technologies & libraries
• Bash scripting, OpenWrt UCI, logread, iptables, curl (HTTPS), coreutils
• Telegram Bot API (getUpdates, sendMessage endpoints)