⚡ Gram Meter

Smart Energy Monitoring Platform for Rural India
Real-time insights · AI-powered anomaly detection · Multilingual support

---

📖 Overview

Gram Meter is a full-stack smart energy monitoring platform built for rural communities in India. It connects IoT smart meters to an AI-powered backend that provides real-time energy monitoring, anomaly detection, billing, and insights — all in local languages.

Built for Square Hacks Hackathon.

---

🏗️ Architecture

┌─────────────────┐     MQTT      ┌──────────────────┐
│  Virtual Meter  │─────────────▶│  MQTT Broker     │
│  (IoT Sim)      │              │  (HiveMQ)        │
└─────────────────┘              └────────┬─────────┘
                                          │
                              ┌───────────▼──────────┐
                              │   Django Backend      │
                              │   (REST API + WS)     │
                              │   Port: 8000          │
                              └───────────┬──────────┘
                                          │
                    ┌─────────────────────▼─────────────────┐
                    │         FastAPI ML Gateway             │
                    │  Forecast · Anomaly · Efficiency       │
                    │  Port: 8001                            │
                    └─────────────────────┬─────────────────┘
                                          │
                              ┌───────────▼──────────┐
                              │   React Frontend     │
                              │   (Vite + Tailwind)  │
                              │   Port: 5173         │
                              └──────────────────────┘

---

✨ Features

Feature	Description
📡 Real-time Monitoring	Live meter readings via WebSockets and MQTT
🤖 AI Anomaly Detection	Detects voltage spikes, drops, overcurrent & phantom loads
📈 Energy Forecasting	24-hour predictions with confidence intervals
🏆 Efficiency Scoring	0–100 score with actionable recommendations
💸 Smart Billing	Auto-generated bills with tariff rate management
🌐 Multilingual	Full support for English, Hindi (हिंदी), and Gujarati (ગુજરાતી)
🔐 JWT + 2FA Auth	Secure role-based access (Farmer, Sarpanch, Utility, Government)
🗺️ Admin Console	Government panel with live village map visualization
📊 Analytics Engine	Historical trends, usage patterns, cost savings reports

---

📁 Project Structure

gram-meter/
├── backend/               # Django REST API + FastAPI ML Gateway
│   ├── meters/            # Core meters app (models, views, WebSockets)
│   ├── analytics/         # Forecasting & pattern analysis
│   ├── billing/           # Invoices & tariff management
│   ├── ml_gateway/        # FastAPI ML microservice
│   └── scripts/           # Sample data & live data generator
│
├── frontend/              # React + Vite frontend
│   └── src/
│       ├── components/    # Reusable UI components
│       ├── pages/         # Dashboard, Billing, Analytics, etc.
│       ├── contexts/      # Language, Theme, Translation providers
│       └── services/      # API & auth service layer
│
├── ML/                    # Machine learning models & training
│   ├── model_trainer.py   # Train forecast & anomaly models
│   ├── virtual_meter.py   # IoT meter simulator (MQTT publisher)
│   ├── analytics_engine.py
│   └── mqtt_listner.py
│
├── Admin console/         # Government admin panel (React)
│
├── start_platform.sh      # One-command startup (macOS/Linux)
└── start_platform.bat     # One-command startup (Windows)

---

🚀 Quick Start

Prerequisites

• Python 3.10+
• Node.js 18+
• pip

1. Clone the repository

git clone https://github.com/Jaimin2687/gram-meter.git
cd gram-meter

2. Backend Setup

cd backend
python -m venv ../.venv
source ../.venv/bin/activate        # Windows: ..\.venv\Scripts\activate
pip install -r requirements.txt

# Apply migrations & seed sample data
python manage.py migrate
python scripts/populate_sample_data.py

3. Frontend Setup

cd frontend
npm install

4. Start Everything

macOS / Linux:

chmod +x start_platform.sh
./start_platform.sh

Windows:

start_platform.bat

Or manually:

# Terminal 1 — Django API
source .venv/bin/activate && cd backend && python manage.py runserver

# Terminal 2 — FastAPI ML Gateway
source .venv/bin/activate && cd backend && uvicorn ml_gateway.main:app --reload --port 8001

# Terminal 3 — React Frontend
cd frontend && npm run dev

# Terminal 4 — Virtual IoT Meter (optional)
source .venv/bin/activate && cd ML && python virtual_meter.py

---

🔗 Service URLs

Service	URL
React Frontend	http://localhost:5173
Django REST API	http://localhost:8000/api/v1/
API Docs (Swagger)	http://localhost:8000/swagger/
FastAPI ML Gateway	http://localhost:8001
ML Docs	http://localhost:8001/docs

---

🔐 Demo Credentials

Username	Password	Role
farmer_ramesh	password123	Farmer
farmer_priya	password123	Farmer
sarpanch_kumar	password123	Sarpanch

---

🤖 ML Capabilities

Anomaly Detection

Automatically detects:

• ⚡ Voltage spikes / drops
• 🔴 Overcurrent faults
• 👻 Phantom loads (energy theft)
• 🌑 Power outages

Energy Forecasting

• 24-hour prediction window
• Confidence intervals (upper/lower bounds)
• Powered by trained forecast_model (MQTT-collected data)

Efficiency Scoring

Grades each meter on:

• Power factor performance
• Load profile consistency
• Peak usage patterns
• Monthly trends

Note: Large ML model files (forecast_model.pkl, anomaly_model.pkl) are excluded from this repo due to GitHub's 100MB file limit. Run ML/model_trainer.py to regenerate them locally.

---

📡 Key API Endpoints

POST   /api/v1/auth/login/              → Get JWT token
GET    /api/v1/dashboard/stats/         → Dashboard summary
GET    /api/v1/meters/                  → List all meters
GET    /api/v1/meters/{id}/readings/    → Historical readings
GET    /api/v1/meters/{id}/live_status/ → Real-time status
GET    /api/v1/alerts/                  → Active alerts
GET    /api/v1/billing/invoices/        → Bills & invoices
POST   /api/v1/anomaly/detect           → Run anomaly detection (ML)
POST   /api/v1/forecast/predict         → Energy forecast (ML)

WebSocket endpoints:

ws://localhost:8000/ws/meters/{id}/     → Live meter stream
ws://localhost:8000/ws/dashboard/       → Dashboard updates
ws://localhost:8000/ws/alerts/          → Real-time alerts

---

🛠️ Tech Stack

Layer	Technology
Frontend	React 18, Vite, Tailwind CSS
Backend API	Django 5, Django REST Framework
ML Service	FastAPI, scikit-learn
Auth	JWT (SimpleJWT) + 2FA
Real-time	Django Channels (WebSocket), Redis
IoT	MQTT (paho-mqtt, HiveMQ broker)
Database	SQLite (dev) / PostgreSQL-ready
ML/Data	pandas, scikit-learn, numpy

---

🐛 Troubleshooting

Port already in use:

lsof -ti:8000 | xargs kill -9
lsof -ti:8001 | xargs kill -9

Database reset:

cd backend
rm db.sqlite3
python manage.py migrate
python scripts/populate_sample_data.py

Virtual environment issues:

python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt

---

📄 License

This project was built for Square Hacks 2025.

---

Built with ❤️ for Rural India