{"id":51764511,"url":"https://github.com/ahana4banerjee/wireless-sensor-network","last_synced_at":"2026-07-19T18:00:30.870Z","repository":{"id":357191969,"uuid":"1177991232","full_name":"ahana4banerjee/Wireless-Sensor-Network","owner":"ahana4banerjee","description":"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 \u0026 a modern React dashboard to collect, analyze, and visualize distributed telemetry from multiple sensor nodes.","archived":false,"fork":false,"pushed_at":"2026-07-04T20:37:37.000Z","size":10609,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-04T21:12:09.848Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://wireless-sensor-network.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ahana4banerjee.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-10T15:21:17.000Z","updated_at":"2026-07-04T20:37:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"ad0cd79a-368c-4c03-8bb8-765e163f7696","html_url":"https://github.com/ahana4banerjee/Wireless-Sensor-Network","commit_stats":null,"previous_names":["ahana4banerjee/wireless-sensor-network"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/ahana4banerjee/Wireless-Sensor-Network","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahana4banerjee%2FWireless-Sensor-Network","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahana4banerjee%2FWireless-Sensor-Network/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahana4banerjee%2FWireless-Sensor-Network/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahana4banerjee%2FWireless-Sensor-Network/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ahana4banerjee","download_url":"https://codeload.github.com/ahana4banerjee/Wireless-Sensor-Network/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahana4banerjee%2FWireless-Sensor-Network/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35661228,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-19T02:00:06.923Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","gradient-boosting","internet-of-things","isolation-forest","linear-regression","mqtt","python3","react","real-time-monitoring","scikitlearn-machine-learning","telemetry-data","wireless-sensor-networks"],"created_at":"2026-07-19T18:00:19.241Z","updated_at":"2026-07-19T18:00:30.859Z","avatar_url":"https://github.com/ahana4banerjee.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Intelligent Wireless Sensor Network (WSN) Platform \u0026 Simulation\n\n[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square\u0026logo=python\u0026logoColor=white)](https://www.python.org/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=flat-square\u0026logo=fastapi\u0026logoColor=white)](https://fastapi.tiangolo.com/)\n[![React](https://img.shields.io/badge/React-18-20232A?style=flat-square\u0026logo=react\u0026logoColor=61DAFB)](https://react.dev/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-17-4169E1?style=flat-square\u0026logo=postgresql\u0026logoColor=white)](https://www.postgresql.org/)\n[![MQTT](https://img.shields.io/badge/MQTT-3.1.1-3C3F41?style=flat-square\u0026logo=mqtt\u0026logoColor=white)](https://mqtt.org/)\n[![ESP32](https://img.shields.io/badge/ESP32-Hardware%20Sim-E7352C?style=flat-square\u0026logo=espressif\u0026logoColor=white)](https://wokwi.com/)\n[![Wokwi Sim](https://img.shields.io/badge/Wokwi-ESP32%20Sim-00979D?style=flat-square\u0026logo=arduino\u0026logoColor=white)](https://wokwi.com/)\n[![Digital Twin](https://img.shields.io/badge/Digital%20Twin-Sync-blueviolet?style=flat-square\u0026logo=hcl\u0026logoColor=white)](docs/CONTEXT.md)\n[![PlatformIO](https://img.shields.io/badge/PlatformIO-Target-F58220?style=flat-square\u0026logo=platformio\u0026logoColor=white)](firmware/esp32_wsn_node/platformio.ini)\n[![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)\n\nAn 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.\n\n---\n\n## 🏗️ Implementation Philosophy\n\nThe platform is designed around a **Simulation-First \u0026 Hardware-Decoupled Architecture** to solve traditional hardware development constraints:\n1. **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.\n2. **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.\n3. **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.\n\n---\n\n## 📅 Development Journey\n\nThe platform development is organized into progressive development phases:\n\n### 🟢 Phase 1 — Software Simulation (Completed)\n*   **Purpose**: Model the physical and environmental behaviors of WSN grids entirely in software before working with hardware interfaces.\n*   **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.\n*   **Synthetic Metrics**: Implemented math-based models for Gaussian RSSI noise, linear battery discharge per transmission, and latency spikes.\n\n### 🔵 Phase 2 — Hardware Simulation (Completed)\n*   **Purpose**: Replace the Python generator scripts with C++ firmware executing inside simulated microcontrollers.\n*   **Implementation**: Generic firmware written in C++ running on simulated **ESP32** microchips inside the **Wokwi** browser sandbox. \n*   **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.\n*   **Continuous Learning \u0026 MLOps**: Enabled a background retraining daemon monitoring dataset growth and elapsed time to trigger automatic model updates.\n\n### 🟣 Phase 2.5 — Productionization \u0026 Persistence Layer (Completed)\n*   **Purpose**: Transition the simulated platform into an industry-grade, production-style software architecture with robust database storage, full containerization, and automated quality gates.\n*   **Implementation**: Migrated storage from flat CSV/JSON files to a robust relational **PostgreSQL 17** database.\n*   **Alembic \u0026 SQLModel**: Designed fully typed database models utilizing SQLModel and managed schema migrations via Alembic.\n*   **REST API \u0026 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.\n*   **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.\n*   **CI Pipeline Integration**: Configured GitHub Actions to validate Python code, database migrations, React builds, and Docker compilations on push/PR.\n*   **Cloud Deployment**: Deployed production frontend assets to **Vercel** and the REST API and PostgreSQL database to **Render**.\n\n### 🟡 Phase 3 — Real Hardware Deployment (Planned)\n*   **Purpose**: Flash the validated Phase 2 C++ firmware directly onto real physical microchips and wire them to environmental sensors.\n*   **Implementation**: Flash the identical C++ code using **PlatformIO** onto physical **ESP32 DevKitC** boards.\n*   **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.\n\n---\n\n## 📸 Dashboard Showcase\n\n### 1. Mission Control NOC View\nVisualizes connection links and gateway statuses, routing dynamic communication paths from the MQTT broker down to geographical points.\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/mission-control.png\" alt=\"Mission Control Dashboard\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### 2. SVG WSN Topology NOC View\nNodes color-code dynamically: Green (Healthy), Yellow (Warning), Red (Watchdog Timeout Offline), and Grey (Disabled) with animated flowlines representing real-time MQTT message streams.\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/topology.png\" alt=\"WSN Topology Map\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### 3. Machine Learning Operations (MLOps)\nVisualizes model versions, validation benchmarks ($R^2$, MAE, RMSE), training histories, and live trigger accumulation progress.\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/MLOps-page.png\" alt=\"MLOps Panel\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### 4. Environmental Prediction Engine\nLinear Regression models are used to forecast environmental telemetry and compare predicted values against actual observations.\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/environment-prediction.png\" alt=\"Temperature Prediction\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n### 5. Network Parameter Prediction Engine\nGradient Boosting models forecast battery behavior, latency, and packet loss to support predictive maintenance and fault prevention.\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/network-prediction.png\" alt=\"Battery Prediction\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n---\n\n## 🛠️ Technology Stack\n\n*   **Embedded \u0026 Firmware**: C++, ESP32 Core, Wokwi Web Simulator, PlatformIO, PubSubClient, ArduinoJson, WiFiClientSecure\n*   **Backend REST Gateway**: Python 3.11+, FastAPI, Uvicorn, SQLModel, SQLAlchemy\n*   **Database Migration**: Alembic, PostgreSQL 17, asyncpg, psycopg2\n*   **Message Broker**: MQTT (HiveMQ Cloud broker / local Mosquitto broker)\n*   **Machine Learning**: Scikit-Learn, Joblib, NumPy, Pandas, Matplotlib\n*   **Frontend Client**: React 18, Vite, Tailwind CSS, Recharts, Lucide React\n*   **Continuous Integration**: GitHub Actions\n\n---\n\n## 📁 Folder Structure\n\n```text\nWireless-Sensor-Network/\n├── .github/workflows/           # GitHub Actions CI pipeline configuration\n├── alembic/                     # Database migrations history and env configurations\n├── configs/                     # System configurations (settings.json, nodes_registry.json)\n├── dashboard/                   # React frontend application (Vite SPA)\n├── docs/                        # Project documentation reference manuals\n│   ├── screenshots/             # Visual dashboard PNG assets\n│   ├── ARCHITECTURE.md          # Architectural blueprints and database schemas\n│   ├── CONTEXT.md               # Onboarding reference and engineering decisions\n│   ├── API.md                   # REST API routes and payloads contract\n│   ├── LOCAL_SETUP_GUIDE.md     # Pre-requisites \u0026 local installation steps\n│   ├── DOCKER_IMPLEMENTATION.md # Docker setup and architecture overview\n│   ├── PRODUCTION_CONTEXT.md    # Production Render/Vercel cloud configurations\n│   ├── HARDWARE.md              # Physical wiring and PlatformIO configurations\n│   └── ML_PIPELINE.md           # MLOps retraining gates and health scores\n├── models/                      # Pickled ML models (.pkl) and registry.json\n├── predictions/                 # Legacy prediction cache outputs\n├── src/                         # Python backend source code\n│   ├── api/                     # FastAPI REST API implementation\n│   │   ├── routes/              # Analytics, Predictions, Twins, Nodes endpoints\n│   │   ├── database.py          # Database engines and session context managers\n│   │   └── models.py            # SQLModel table schema declarations\n│   ├── db/                      # Telemetry CSV importer and seed engines\n│   │   ├── migrate_csv.py       # CSV backfill script\n│   │   └── seed.py              # Unified database seeding script\n│   ├── ml/                      # ML forecasting models and training managers\n│   └── backend.py               # MQTT subscriber daemon \u0026 watchdog\n├── tests/                       # Unit testing suite\n├── Dockerfile                   # Backend docker configuration\n├── requirements.txt             # Python dependencies\n└── LICENSE                      # Project license file (MIT)\n```\n\n---\n\n## 💻 Installation \u0026 Quick Start\n\nFor detailed step-by-step guidance, check the comprehensive **[docs/LOCAL_SETUP_GUIDE.md](docs/LOCAL_SETUP_GUIDE.md)**.\n\n### Option A: Containerized Quick Start (Docker - Recommended)\nIf you have Docker Desktop installed, you can start the entire multi-container network with three simple commands:\n```bash\n# 1. Start the stack in background\ndocker compose up -d --build\n\n# 2. Run database migrations\ndocker compose exec api-fastapi python -m alembic upgrade head\n\n# 3. Seed historical data \u0026 bootstrap ML models\ndocker compose exec api-fastapi python src/db/seed.py\n```\nOpen **`http://localhost`** to view the live React NOC Dashboard, or **`http://localhost:8000/docs`** for interactive API documentation.\n\n---\n\n### Option B: Manual Bare-Metal Setup\nTo run services as local processes:\n\n1. **Clone \u0026 Setup Virtual Environment**:\n   ```bash\n   git clone https://github.com/YOUR_USERNAME/Wireless-Sensor-Network.git\n   cd Wireless-Sensor-Network\n   python -m venv .venv\n   # Windows:\n   .venv\\Scripts\\activate\n   # macOS/Linux:\n   source .venv/bin/activate\n   pip install -r requirements.txt\n   ```\n\n2. **Configure `.env`**:\n   Create a `.env` file in the root directory:\n   ```env\n   DATABASE_URL=\"postgresql://postgres:password@localhost:5432/wsn\"\n   ASYNC_DATABASE_URL=\"postgresql+asyncpg://postgres:password@localhost:5432/wsn\"\n   ```\n\n3. **Run Migrations \u0026 Seeding**:\n   ```bash\n   python -m alembic upgrade head\n   python src/db/seed.py\n   ```\n\n4. **Launch Backend Processes** (Run in three separate terminals/tabs with active `.venv`):\n   ```bash\n   # Terminal 1: Ingestion Subscriber\n   python src/backend.py\n\n   # Terminal 2: Background Retraining Daemon\n   python src/ml/training_manager.py\n\n   # Terminal 3: FastAPI REST Server\n   python -m uvicorn src.api.main:app --host 127.0.0.1 --port 8000 --reload\n   ```\n\n5. **Run Client Dashboard** (In Terminal 4):\n   ```bash\n   echo \"VITE_API_URL=http://localhost:8000\" \u003e dashboard/.env.local\n   cd dashboard\n   npm install\n   npm run dev\n   ```\n   Open **`http://localhost:5173`** to access the dashboard.\n\n---\n\n## 🌐 Production Cloud Deployment\n*   **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.\n*   **Backend \u0026 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.\n\n---\n\n## 🛠️ Continuous Integration (CI)\nThe project includes a robust **GitHub Actions** CI pipeline that validates code quality on every push or Pull Request to `main`.\n*   **Jobs Executed**:\n    1.  **Backend Verification**: Boots an ephemeral PostgreSQL 17 container, runs Alembic schema migrations (`alembic upgrade head`), and executes unittest suites.\n    2.  **Frontend Verification**: Installs npm dependencies and validates build assets bundling (`npm run build`).\n    3.  **Docker Build Verification**: Runs test builds on the Dockerfiles to ensure container health.\n\n---\n\n## 📚 Technical Documentation Reference\n\nTo explore the architecture, APIs, or database choices, check out the detailed manuals:\n*   **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**: Network/Ingestion blueprints and PostgreSQL schemas.\n*   **[docs/LOCAL_SETUP_GUIDE.md](docs/LOCAL_SETUP_GUIDE.md)**: Core local tools installation steps.\n*   **[docs/DOCKER_IMPLEMENTATION.md](docs/DOCKER_IMPLEMENTATION.md)**: Docker container boundaries and volume mounts.\n*   **[docs/PRODUCTION_CONTEXT.md](docs/PRODUCTION_CONTEXT.md)**: Cloud deployment configurations (Vercel \u0026 Render).\n*   **[docs/API.md](docs/API.md)**: REST endpoints contract.\n*   **[docs/ML_PIPELINE.md](docs/ML_PIPELINE.md)**: ML regression formulas and health calculation rules.\n*   **[docs/HARDWARE.md](docs/HARDWARE.md)**: Physical wiring and PlatformIO configurations.\n\n---\n\n## 👤 Author\n**Ahana Banerjee**  \n*JNTUH, ECE, 4th Year*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahana4banerjee%2Fwireless-sensor-network","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fahana4banerjee%2Fwireless-sensor-network","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahana4banerjee%2Fwireless-sensor-network/lists"}