How amatikhasan/iotbridgesystem works
1. Overall shape
- This repo is a small IoT control-and-monitoring system built around three runtime pieces: a local MQTT broker (Mosquitto), a Python bridge service, and a Python device simulator.
- The architecture is a hub-and-spoke setup: MQTT is the internal message bus, and Telegram is the human interface.
2. bridge.py is the integration layer
- The bridge is the central orchestrator.
- It connects outward to the Telegram Bot API and inward to the MQTT broker.
- Its job is to translate Telegram commands into MQTT control messages, and translate MQTT sensor/status messages into Telegram alerts and updates.
3. simulator.py is the device-side producer/consumer
- The simulator represents smart-home devices and sensors.
- It publishes synthetic sensor telemetry into MQTT and listens for control commands from the bridge.
- This lets the system demonstrate both telemetry ingestion and remote actuation without real hardware.
4. MQTT is the internal boundary
- MQTT is the main decoupling point between the bridge and devices.
- The bridge does not directly talk to the simulator; both communicate through the broker.
- This makes the system extensible to additional devices or sensors without changing the Telegram-facing logic.
5. Alerting is event-driven with thresholds
- The bridge watches incoming sensor topics and emits Telegram alerts when readings cross configured conditions:
- temperature > 30°C
- humidity > 70%
- CO2 > 1000 ppm
- motion detection
- This is a one-way notification path from MQTT events to Telegram messages.
6. Command/control path is bidirectional
- Telegram buttons drive control actions such as Lights ON/OFF and Status Check.
- Those actions are converted into MQTT commands so the simulator/device side can react.
- Status updates then flow back the other way through MQTT into Telegram, closing the loop.
7. Debouncing prevents alert spam
- The bridge includes time-based suppression logic so the same topic won’t trigger repeated Telegram alerts too frequently.
- This is important architecture-wise because it protects the human notification channel from noisy sensor streams.
8. Mosquitto is run as a local infrastructure service
- docker-compose.yml provisions an Eclipse Mosquitto broker.
- The mosquitto/ directory holds broker configuration, data, and logs, which makes the MQTT layer a managed local dependency rather than an external cloud service.
- The README indicates anonymous access on port 1883, so the broker is intended for local development/demo use.
9. Configuration and secrets are environment-driven
- Telegram credentials are provided via .env variables: bot token and chat ID.
- That keeps the Telegram integration separate from code and allows the bridge to be deployed or tested in different accounts without code changes.
10. Runtime boundaries
- Python application boundary: bridge.py and simulator.py
- Messaging boundary: MQTT broker
- External SaaS boundary: Telegram
- Infrastructure boundary: Docker Compose-managed Mosquitto
- These are the main boxes and arrows to capture in an architecture diagram.
11. Operational flow
- Start Mosquitto with Docker Compose.
- Run the bridge so it can subscribe/publish on MQTT and maintain the Telegram bot session.
- Run the simulator to generate telemetry and respond to control messages.
- The resulting system behaves like a small closed-loop IoT demo with human-in-the-loop control.
12. What is not present
- There is no evidence of a database-backed application layer, web frontend, or cloud-hosted backend.
- Persistence is limited to broker state/logs inside the Mosquitto directory, while the core application state appears to live in memory inside the Python processes.
Main entry points: docker-compose.yml MQTT Broker · bridge.py Bridge · simulator.py Simulator · mosquitto.conf Broker Config
Components 11
Application
Python runtime components that implement the IoT demo logic
Messaging
Internal broker boundary and topic exchange
- MQTT Broker · Local message bus that decouples the bridge from devices
docker-compose.yml - Telemetry · Sensor readings and device status published by the simulator
- Commands · Control messages and status checks sent from the bridge to devices
External
Human-facing SaaS integration
- Alerts · Threshold-based notifications raised by the bridge from incoming MQTT events
- Telegram Bot · Human control and notification channel for the system
Infrastructure
Local broker deployment and persisted broker artifacts
- Compose Stack · Runs the local Mosquitto broker as a managed development service
docker-compose.yml - Broker Config · Mosquitto runtime configuration used by the local broker
mosquitto/config/mosquitto.conf - Broker State · Persisted broker database/state used by the local Mosquitto service
mosquitto/data/mosquitto.db - Broker Logs · Operational log output from the local broker
mosquitto/log/mosquitto.log
Connections 13
- Telegram Bot → Bridge: commands · User actions and bot interactions reach the bridge
- Bridge → Telegram Bot: alerts · Threshold breaches and status updates are sent back to Telegram
- Bridge → MQTT Broker: publish/subscribe · Bridge exchanges MQTT messages through the broker
- Simulator → MQTT Broker: telemetry · Simulator publishes sensor data into MQTT
- MQTT Broker → Simulator: control · Simulator receives commands routed through MQTT
- MQTT Broker → Bridge: events · Bridge consumes sensor and status events from MQTT
- Bridge → Commands: emit · Control actions are translated into MQTT commands
- Telemetry → Bridge: input · Incoming sensor readings are evaluated for alerting
- Bridge → Alerts: raise · Alert conditions create Telegram notifications
- Compose Stack → MQTT Broker: run · Docker Compose provisions the Mosquitto broker service
- Broker Config → MQTT Broker: configure · Broker behavior is defined by Mosquitto configuration
- MQTT Broker → Broker State: persist · Broker state is stored locally for the development stack
- MQTT Broker → Broker Logs: log · Broker activity is written to local log files