https://github.com/ahana4banerjee/wireless-sensor-network
Wireless Sensor Network (WSN) is an end-to-end Industrial IoT platform for real-time environmental and network health monitoring. The system combines ESP32-based sensor nodes, MQTT messaging, a FastAPI backend, machine learning pipelines & a modern React dashboard to collect, analyze, and visualize distributed telemetry from multiple sensor nodes.
https://github.com/ahana4banerjee/wireless-sensor-network
fastapi gradient-boosting internet-of-things isolation-forest linear-regression mqtt python3 react real-time-monitoring scikitlearn-machine-learning telemetry-data wireless-sensor-networks
Last synced: 20 days ago
JSON representation
Wireless Sensor Network (WSN) is an end-to-end Industrial IoT platform for real-time environmental and network health monitoring. The system combines ESP32-based sensor nodes, MQTT messaging, a FastAPI backend, machine learning pipelines & a modern React dashboard to collect, analyze, and visualize distributed telemetry from multiple sensor nodes.
- Host: GitHub
- URL: https://github.com/ahana4banerjee/wireless-sensor-network
- Owner: ahana4banerjee
- License: mit
- Created: 2026-03-10T15:21:17.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-07-04T20:37:37.000Z (about 1 month ago)
- Last Synced: 2026-07-04T21:12:09.848Z (about 1 month ago)
- Topics: fastapi, gradient-boosting, internet-of-things, isolation-forest, linear-regression, mqtt, python3, react, real-time-monitoring, scikitlearn-machine-learning, telemetry-data, wireless-sensor-networks
- Language: Python
- Homepage: https://wireless-sensor-network.vercel.app
- Size: 10.1 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Intelligent Wireless Sensor Network (WSN) Platform & Simulation
[](https://www.python.org/)
[](https://fastapi.tiangolo.com/)
[](https://react.dev/)
[](https://www.postgresql.org/)
[](https://mqtt.org/)
[](https://wokwi.com/)
[](https://wokwi.com/)
[](docs/CONTEXT.md)
[](firmware/esp32_wsn_node/platformio.ini)
[](LICENSE)
An enterprise-grade, simulation-first IoT and MLOps platform for distributed Wireless Sensor Networks (WSNs). The system coordinates simulated C++ edge nodes, high-throughput MQTT brokers, persistent PostgreSQL database storage, real-time FastAPI REST services, in-memory machine learning estimators, and an interactive React web dashboard.
---
## 🏗️ Implementation Philosophy
The platform is designed around a **Simulation-First & Hardware-Decoupled Architecture** to solve traditional hardware development constraints:
1. **Generic Firmware Strategy**: Microcontrollers are flashed with identical, location-agnostic firmware. They identify themselves at runtime by querying their default hardware eFuse MAC address, dynamically binding coordinator coordinates, location details, and settings via a backend Node Registry.
2. **Simulation-to-Physical Path**: Telemetry sources connect via standard MQTT, enabling a seamless transition from software models (Phase 1) and simulated ESP32 boards (Phase 2) to real physical microchips (Phase 3) with zero modifications to the databases, APIs, retraining engines, or dashboards.
3. **Operational Explainability**: Avoids black-box predictions for core network diagnostics, using a trace-based Network Health Index (NHI) calculation to yield clear, explainable maintenance directives.
---
## 📅 Development Journey
The platform development is organized into progressive development phases:
### 🟢 Phase 1 — Software Simulation (Completed)
* **Purpose**: Model the physical and environmental behaviors of WSN grids entirely in software before working with hardware interfaces.
* **Implementation**: Five virtual node scripts representing regional hubs (Delhi, Hyderabad, Mumbai, Bangalore, Secunderabad). Each node queries the **OpenWeather API** to seed telemetry with real weather conditions.
* **Synthetic Metrics**: Implemented math-based models for Gaussian RSSI noise, linear battery discharge per transmission, and latency spikes.
### 🔵 Phase 2 — Hardware Simulation (Completed)
* **Purpose**: Replace the Python generator scripts with C++ firmware executing inside simulated microcontrollers.
* **Implementation**: Generic firmware written in C++ running on simulated **ESP32** microchips inside the **Wokwi** browser sandbox.
* **Identity Decoupling**: Decoupled locations from firmware. The board queries its unique hardware **eFuse MAC address** on boot (`node_id = "mac"`). The backend Node Registry dynamically binds the MAC address to city coordinates, locations, and settings.
* **Continuous Learning & MLOps**: Enabled a background retraining daemon monitoring dataset growth and elapsed time to trigger automatic model updates.
### 🟣 Phase 2.5 — Productionization & Persistence Layer (Completed)
* **Purpose**: Transition the simulated platform into an industry-grade, production-style software architecture with robust database storage, full containerization, and automated quality gates.
* **Implementation**: Migrated storage from flat CSV/JSON files to a robust relational **PostgreSQL 17** database.
* **Alembic & SQLModel**: Designed fully typed database models utilizing SQLModel and managed schema migrations via Alembic.
* **REST API & ML Overhaul**: Ported all FastAPI gateways and the ML continuous retraining daemon to execute queries and write prediction histories, validation runs, and twin states straight to PostgreSQL.
* **Full Containerization**: Containerized the entire multi-service stack (PostgreSQL, Mosquitto, FastAPI API gateway, MQTT ingestion daemon, ML retraining scheduler, Nginx React dashboard host) using Docker Compose.
* **CI Pipeline Integration**: Configured GitHub Actions to validate Python code, database migrations, React builds, and Docker compilations on push/PR.
* **Cloud Deployment**: Deployed production frontend assets to **Vercel** and the REST API and PostgreSQL database to **Render**.
### 🟡 Phase 3 — Real Hardware Deployment (Planned)
* **Purpose**: Flash the validated Phase 2 C++ firmware directly onto real physical microchips and wire them to environmental sensors.
* **Implementation**: Flash the identical C++ code using **PlatformIO** onto physical **ESP32 DevKitC** boards.
* **Zero Downstream Changes**: Real boards publish matching JSON packages over Wi-Fi. The REST API and React dashboard serve physical node measurements with zero changes to code.
---
## 📸 Dashboard Showcase
### 1. Mission Control NOC View
Visualizes connection links and gateway statuses, routing dynamic communication paths from the MQTT broker down to geographical points.
### 2. SVG WSN Topology NOC View
Nodes color-code dynamically: Green (Healthy), Yellow (Warning), Red (Watchdog Timeout Offline), and Grey (Disabled) with animated flowlines representing real-time MQTT message streams.
### 3. Machine Learning Operations (MLOps)
Visualizes model versions, validation benchmarks ($R^2$, MAE, RMSE), training histories, and live trigger accumulation progress.
### 4. Environmental Prediction Engine
Linear Regression models are used to forecast environmental telemetry and compare predicted values against actual observations.
### 5. Network Parameter Prediction Engine
Gradient Boosting models forecast battery behavior, latency, and packet loss to support predictive maintenance and fault prevention.
---
## 🛠️ Technology Stack
* **Embedded & Firmware**: C++, ESP32 Core, Wokwi Web Simulator, PlatformIO, PubSubClient, ArduinoJson, WiFiClientSecure
* **Backend REST Gateway**: Python 3.11+, FastAPI, Uvicorn, SQLModel, SQLAlchemy
* **Database Migration**: Alembic, PostgreSQL 17, asyncpg, psycopg2
* **Message Broker**: MQTT (HiveMQ Cloud broker / local Mosquitto broker)
* **Machine Learning**: Scikit-Learn, Joblib, NumPy, Pandas, Matplotlib
* **Frontend Client**: React 18, Vite, Tailwind CSS, Recharts, Lucide React
* **Continuous Integration**: GitHub Actions
---
## 📁 Folder Structure
```text
Wireless-Sensor-Network/
├── .github/workflows/ # GitHub Actions CI pipeline configuration
├── alembic/ # Database migrations history and env configurations
├── configs/ # System configurations (settings.json, nodes_registry.json)
├── dashboard/ # React frontend application (Vite SPA)
├── docs/ # Project documentation reference manuals
│ ├── screenshots/ # Visual dashboard PNG assets
│ ├── ARCHITECTURE.md # Architectural blueprints and database schemas
│ ├── CONTEXT.md # Onboarding reference and engineering decisions
│ ├── API.md # REST API routes and payloads contract
│ ├── LOCAL_SETUP_GUIDE.md # Pre-requisites & local installation steps
│ ├── DOCKER_IMPLEMENTATION.md # Docker setup and architecture overview
│ ├── PRODUCTION_CONTEXT.md # Production Render/Vercel cloud configurations
│ ├── HARDWARE.md # Physical wiring and PlatformIO configurations
│ └── ML_PIPELINE.md # MLOps retraining gates and health scores
├── models/ # Pickled ML models (.pkl) and registry.json
├── predictions/ # Legacy prediction cache outputs
├── src/ # Python backend source code
│ ├── api/ # FastAPI REST API implementation
│ │ ├── routes/ # Analytics, Predictions, Twins, Nodes endpoints
│ │ ├── database.py # Database engines and session context managers
│ │ └── models.py # SQLModel table schema declarations
│ ├── db/ # Telemetry CSV importer and seed engines
│ │ ├── migrate_csv.py # CSV backfill script
│ │ └── seed.py # Unified database seeding script
│ ├── ml/ # ML forecasting models and training managers
│ └── backend.py # MQTT subscriber daemon & watchdog
├── tests/ # Unit testing suite
├── Dockerfile # Backend docker configuration
├── requirements.txt # Python dependencies
└── LICENSE # Project license file (MIT)
```
---
## 💻 Installation & Quick Start
For detailed step-by-step guidance, check the comprehensive **[docs/LOCAL_SETUP_GUIDE.md](docs/LOCAL_SETUP_GUIDE.md)**.
### Option A: Containerized Quick Start (Docker - Recommended)
If you have Docker Desktop installed, you can start the entire multi-container network with three simple commands:
```bash
# 1. Start the stack in background
docker compose up -d --build
# 2. Run database migrations
docker compose exec api-fastapi python -m alembic upgrade head
# 3. Seed historical data & bootstrap ML models
docker compose exec api-fastapi python src/db/seed.py
```
Open **`http://localhost`** to view the live React NOC Dashboard, or **`http://localhost:8000/docs`** for interactive API documentation.
---
### Option B: Manual Bare-Metal Setup
To run services as local processes:
1. **Clone & Setup Virtual Environment**:
```bash
git clone https://github.com/YOUR_USERNAME/Wireless-Sensor-Network.git
cd Wireless-Sensor-Network
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
pip install -r requirements.txt
```
2. **Configure `.env`**:
Create a `.env` file in the root directory:
```env
DATABASE_URL="postgresql://postgres:password@localhost:5432/wsn"
ASYNC_DATABASE_URL="postgresql+asyncpg://postgres:password@localhost:5432/wsn"
```
3. **Run Migrations & Seeding**:
```bash
python -m alembic upgrade head
python src/db/seed.py
```
4. **Launch Backend Processes** (Run in three separate terminals/tabs with active `.venv`):
```bash
# Terminal 1: Ingestion Subscriber
python src/backend.py
# Terminal 2: Background Retraining Daemon
python src/ml/training_manager.py
# Terminal 3: FastAPI REST Server
python -m uvicorn src.api.main:app --host 127.0.0.1 --port 8000 --reload
```
5. **Run Client Dashboard** (In Terminal 4):
```bash
echo "VITE_API_URL=http://localhost:8000" > dashboard/.env.local
cd dashboard
npm install
npm run dev
```
Open **`http://localhost:5173`** to access the dashboard.
---
## 🌐 Production Cloud Deployment
* **Frontend (Vercel)**: Deployed at Vercel edge networks, connected to the backend REST API via dynamic configurations. It operates in **Demo Mode** to remain free-tier compliant.
* **Backend & DB (Render)**: FastAPI backend and PostgreSQL 17 database instances hosted on Render. Render configurations limit connection pools to 9 active sockets to remain free-tier compliant.
---
## 🛠️ Continuous Integration (CI)
The project includes a robust **GitHub Actions** CI pipeline that validates code quality on every push or Pull Request to `main`.
* **Jobs Executed**:
1. **Backend Verification**: Boots an ephemeral PostgreSQL 17 container, runs Alembic schema migrations (`alembic upgrade head`), and executes unittest suites.
2. **Frontend Verification**: Installs npm dependencies and validates build assets bundling (`npm run build`).
3. **Docker Build Verification**: Runs test builds on the Dockerfiles to ensure container health.
---
## 📚 Technical Documentation Reference
To explore the architecture, APIs, or database choices, check out the detailed manuals:
* **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**: Network/Ingestion blueprints and PostgreSQL schemas.
* **[docs/LOCAL_SETUP_GUIDE.md](docs/LOCAL_SETUP_GUIDE.md)**: Core local tools installation steps.
* **[docs/DOCKER_IMPLEMENTATION.md](docs/DOCKER_IMPLEMENTATION.md)**: Docker container boundaries and volume mounts.
* **[docs/PRODUCTION_CONTEXT.md](docs/PRODUCTION_CONTEXT.md)**: Cloud deployment configurations (Vercel & Render).
* **[docs/API.md](docs/API.md)**: REST endpoints contract.
* **[docs/ML_PIPELINE.md](docs/ML_PIPELINE.md)**: ML regression formulas and health calculation rules.
* **[docs/HARDWARE.md](docs/HARDWARE.md)**: Physical wiring and PlatformIO configurations.
---
## 👤 Author
**Ahana Banerjee**
*JNTUH, ECE, 4th Year*