Eddiegah/IOT-Sensor-Network: 📡 IoT Sensor Network Simulator

🎬 What's happening under the hood

  Every 3–5 seconds, each node wakes up, generates a reading, and shouts it
  into the network. The hub is always listening. The dashboard is always watching.

  ╔══════════════════════════════════════════════════════════════════════════╗
  ║                     LIVE SENSOR NETWORK (simulated)                     ║
  ╠══════════════════════════════════════════════════════════════════════════╣
  ║                                                                          ║
  ║   🌡  node_1  temp=22.4°C  ──┐                                          ║
  ║   🌡  node_2  temp=19.8°C  ──┤                                          ║
  ║   💧  node_3  humi=58.3%   ──┼──►  [ Mosquitto Broker :1883 ]           ║
  ║   💧  node_4  humi=61.1%   ──┤          │                               ║
  ║   👁  node_5  motion=0     ──┘          │ subscribe sensors/+/+         ║
  ║                                         ▼                               ║
  ║                                  [ hub.py ]                             ║
  ║                                  ├─ logs readings to SQLite             ║
  ║                                  ├─ tracks heartbeats per node          ║
  ║                                  └─ 15s silence = ❌ OFFLINE            ║
  ║                                         │                               ║
  ║                                         ▼                               ║
  ║                              [ Streamlit Dashboard ]                    ║
  ║                              ├─ 🟢 node_1  22.4°C   2s ago             ║
  ║                              ├─ 🟢 node_2  19.8°C   4s ago             ║
  ║                              ├─ 🔴 node_3  OFFLINE  23s ago  ← ALERT   ║
  ║                              ├─ 🟢 node_4  61.1%    1s ago             ║
  ║                              └─ 🟢 node_5  motion=0  3s ago            ║
  ╚══════════════════════════════════════════════════════════════════════════╝

Kill any node with one command. The hub detects the silence. The dashboard goes red. Revive it. It comes back online. The whole thing is live.

🎥 Demo

✨ Why this project exists

Most IoT tutorials fake it — one script, fake pub/sub, no real network, no real protocol.

This project uses real MQTT over a real broker with real distributed processes. The same architecture pattern behind:

🧩 Core concepts demonstrated

node_1 publishes ──► sensors/node_1/temperature  ──► broker ──► hub receives
node_1 publishes ──► sensors/node_1/heartbeat    ──► broker ──► hub receives
hub subscribes   ──► sensors/+/+                 (+ matches any single level)

PID 21564  sensor_node.py  node_1  temperature
PID 11088  sensor_node.py  node_2  temperature
PID  7896  sensor_node.py  node_3  humidity
PID  4208  sensor_node.py  node_4  humidity
PID  3892  sensor_node.py  node_5  motion
PID  9100  hub.py          ← subscribes to all of them

Every 5 seconds:
  node → publishes heartbeat to sensors/{node_id}/heartbeat

Every 5 seconds (hub fault-detection thread):
  for each known node:
    if (now - last_heartbeat) > 15 seconds:
      mark node OFFLINE
      log alert

When heartbeat resumes:
  if node was OFFLINE:
    mark node ONLINE
    log recovery alert

🗂 Project structure

iot-sensor-network/
│
├── src/
│   ├── sensor_node.py      # 🌡  Independent sensor device — MQTT publisher
│   │                       #     Generates realistic temperature / humidity / motion
│   │                       #     Publishes readings + heartbeats
│   │
│   ├── hub.py              # 🖥  Central hub — MQTT subscriber
│   │                       #     Logs all readings to SQLite
│   │                       #     Fault-detection thread watches heartbeats
│   │
│   ├── launch_nodes.py     # 🚀  Spawns all 5 nodes as separate OS processes
│   │                       #     Writes PID records so fault_injector can find them
│   │
│   └── fault_injector.py   # 💀  Kill / revive individual nodes on demand
│                           #     Demonstrates fault detection live
│
├── app.py                  # 📊  Streamlit dashboard — live monitoring UI
├── mqtt_test.py            # ✅  Connectivity verification script
├── requirements.txt        # 📦  Pinned dependencies
├── .gitignore
└── README.md

⚙️ Tech stack

🚀 Getting started

Prerequisites

• Python 3.9 – 3.12
• Mosquitto MQTT broker — this is a system service, not a pip package

Step 1 — Install Mosquitto

⚠️ This step is required. The hub and nodes will fail with ConnectionRefusedError if Mosquitto isn't running.

Windows:

1. Download the installer from https://mosquitto.org/download/ (64-bit .exe)
2. Run it — installs as a Windows service automatically
3. Start the service (PowerShell as Administrator):

net start mosquitto

4. Verify it's listening:

netstat -an | findstr 1883
# Should show: 0.0.0.0:1883   LISTENING

macOS:

brew install mosquitto
brew services start mosquitto

Linux:

sudo apt install mosquitto mosquitto-clients
sudo systemctl start mosquitto

Step 2 — Python environment

# Windows
py -3.11 -m venv venv
venv\Scripts\python.exe -m pip install -r requirements.txt

# macOS / Linux
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Step 3 — Verify connectivity

Run this before anything else. It connects to Mosquitto, publishes a test message, and confirms it arrives back.

# Windows
venv\Scripts\python.exe mqtt_test.py

# macOS / Linux
python mqtt_test.py

Expected output:

✅ All Python imports OK
✅ Connected to Mosquitto at localhost:1883
✅ Received message: {"test": true, ...}
══════════════════════════════════════════════════
��� MQTT CONNECTIVITY TEST PASSED
   You can now start the full simulation.
══════════════════════════════════════════════════

Step 4 — Run the simulation

Open three terminal windows in the project root.

Terminal 1 — Start the hub first:

venv\Scripts\python.exe src/hub.py

[hub] Connected to broker at localhost:1883
[hub] Subscribed to sensors/+/+
[hub] 📡 node_1/temperature: 22.4°C       ← data starts flowing
[hub] 📡 node_3/humidity: 58.1%

Terminal 2 — Launch all sensor nodes:

venv\Scripts\python.exe src/launch_nodes.py

✅ node_1   (temperature) — PID 21564
✅ node_2   (temperature) — PID 11088
✅ node_3   (humidity   ) — PID 7896
✅ node_4   (humidity   ) — PID 4208
✅ node_5   (motion     ) — PID 3892

Terminal 3 — Open the dashboard:

venv\Scripts\streamlit.exe run app.py

Opens at http://localhost:8501 — auto-refreshes every 3 seconds.

Step 5 — Demo fault detection 🔥

This is the interesting part. Open a fourth terminal:

# Kill node_3 — simulates a dead battery or lost connection
venv\Scripts\python.exe src/fault_injector.py --kill node_3

Watch what happens:

# After ~15 seconds silence, the hub fires:
[hub] ❌ Node node_3 OFFLINE (no heartbeat for 15s)
[hub] 🔔 ALERT [offline] node_3: Node node_3 went offline

The dashboard card for node_3 turns 🔴 RED.

# Bring it back
venv\Scripts\python.exe src/fault_injector.py --revive node_3

# Hub immediately detects the returning heartbeat:
[hub] ✅ Node node_3 came back ONLINE
[hub] 🔔 ALERT [online] node_3: Node node_3 reconnected

Card goes 🟢 GREEN. The full cycle is logged in the alerts panel.

🌡 Sensor simulation details

The hub flags anomalies automatically:

• Temperature > 30°C or < 15°C → alert logged
• Humidity > 80% → alert logged
• Motion triggered → alert logged

🔧 Troubleshooting

🗺 Future work

This is a v1 local simulation. The path to production:

• 🔒 TLS + Auth — production MQTT uses port 8883 with client certificates or username/password. Noted in code comments throughout.
• ☁️ Cloud broker — swap localhost:1883 for AWS IoT Core, HiveMQ Cloud, or EMQX. The node/hub code is broker-agnostic.
• 🍓 Real hardware — sensor_node.py runs unmodified on a Raspberry Pi. Point BROKER_HOST at a real broker and connect actual sensors.
• 📈 Time-series DB — replace SQLite with InfluxDB or TimescaleDB for production-scale workloads and Grafana dashboards.
• 😴 Sleep mode — already partially implemented. Nodes publish their sleep schedule; the hub suppresses false-alarm timeouts during intentional dormant periods.

📖 Why MQTT?

MQTT was designed in 1999 for monitoring oil pipelines over satellite links — high latency, low bandwidth, unreliable connections, constrained devices. Those exact constraints describe IoT hardware.

Compared to HTTP:

Today MQTT is the default protocol for AWS IoT Core, Azure IoT Hub, Google Cloud IoT, and most commercial smart home platforms.