Update README.md
parent
a85b279b57
commit
1390bc21c6
278
README.md
278
README.md
|
|
@ -1,181 +1,227 @@
|
||||||
Swap Station Real-Time Monitoring & Analytics Dashboard
|
# ⚡ Swap Station Real-Time Monitoring & Analytics Dashboard
|
||||||
|
|
||||||
A full-stack web application designed for the real-time monitoring, control, and historical analysis of battery swap stations. This dashboard provides a comprehensive interface for administrators and operators to track station health, manage operations, and derive insights from performance data.
|
- A **full-stack web application** for real-time monitoring, control, and analytics of battery swap stations.
|
||||||
► Key Features
|
- It provides an end-to-end interface for administrators and operators to **track station health**, **manage operations**, and **analyze performance trends** — all from a unified dashboard.
|
||||||
|
|
||||||
Real-Time Dashboard: Live monitoring of station status, slot occupancy, battery vitals (Voltage, SoC, Temperature), and ongoing swap processes via WebSocket communication.
|
---
|
||||||
|
|
||||||
Remote Control: Send commands directly to stations to open/close slots, enable/disable chargers, initiate swaps, and perform system reboots.
|
## 🚀 Key Features
|
||||||
|
|
||||||
Advanced Analytics: An interactive analytics page with customizable date ranges to visualize historical data, including swap activity, hourly distribution, abort reasons, and slot utilization heatmaps.
|
### 🟢 Real-Time Dashboard
|
||||||
|
- Live visualization of station and slot status.
|
||||||
|
- Displays battery vitals (Voltage, SoC, Temperature) and swap progress in real time.
|
||||||
|
- Powered by WebSocket communication for instant updates.
|
||||||
|
|
||||||
Data Export: Export detailed periodic and event logs as CSV files for offline analysis and record-keeping.
|
### ⚙️ Remote Control
|
||||||
|
- Securely send commands to swap stations:
|
||||||
|
- Open/close slots
|
||||||
|
- Enable/disable chargers
|
||||||
|
- Initiate swap cycles
|
||||||
|
- Trigger system reboot or maintenance actions
|
||||||
|
|
||||||
Station & User Management: Securely add, remove, and manage swap stations and user accounts.
|
### 📊 Advanced Analytics
|
||||||
|
- Rich, interactive analytics with date-range filters.
|
||||||
|
- Visualizations include:
|
||||||
|
- Swap frequency and activity trends
|
||||||
|
- Hourly distribution charts
|
||||||
|
- Abort-reason statistics
|
||||||
|
- Slot utilization heatmaps
|
||||||
|
|
||||||
Dockerized for Deployment: The entire application is containerized using Docker, Nginx, and Gunicorn, ensuring consistent and reliable deployment to any cloud environment.
|
### 📤 Data Export
|
||||||
|
- Export detailed periodic data and event logs as **CSV** for offline analysis or compliance archiving.
|
||||||
|
|
||||||
► Tech Stack
|
### 🧑💼 Station & User Management
|
||||||
|
- Role-based access control for administrators and operators.
|
||||||
|
- Add, update, or remove stations and users through a secure management panel.
|
||||||
|
|
||||||
Component
|
### 🐳 Dockerized Deployment
|
||||||
|
- Fully containerized setup using **Docker**, **Nginx**, and **Gunicorn**.
|
||||||
|
- Ensures consistent, reproducible deployments to any cloud or on-prem environment.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
Technology
|
## 🧠 Tech Stack
|
||||||
|
|
||||||
Backend
|
| Component | Technology |
|
||||||
|
|------------|-------------|
|
||||||
|
| **Backend** | Python 3, Flask, Flask-SocketIO, SQLAlchemy, PostgreSQL |
|
||||||
|
| **Frontend** | HTML5, CSS3, JavaScript (ES6+), Tailwind CSS, Chart.js, Flatpickr.js |
|
||||||
|
| **Real-Time Engine** | MQTT (station communication), WebSockets (client communication) |
|
||||||
|
| **Deployment** | Docker, Docker Compose, Nginx (reverse proxy), Gunicorn (WSGI server) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
Python 3, Flask, Flask-SocketIO, SQLAlchemy, PostgreSQL
|
## 🧩 Local Installation & Setup Guide
|
||||||
|
|
||||||
Frontend
|
Follow these steps to set up the application locally for development or testing.
|
||||||
|
|
||||||
|
### ✅ Prerequisites
|
||||||
|
Ensure the following are installed:
|
||||||
|
|
||||||
HTML5, CSS3, JavaScript (ES6+), Tailwind CSS, Chart.js, Flatpickr.js
|
- **Python** ≥ 3.9
|
||||||
|
- **Node.js** ≥ 16 and **npm**
|
||||||
|
- **PostgreSQL** (local instance running)
|
||||||
|
- **Git**
|
||||||
|
|
||||||
Real-Time Engine
|
---
|
||||||
|
|
||||||
|
### 1️⃣ Clone the Repository
|
||||||
|
|
||||||
MQTT (for station communication), WebSockets (for client communication)
|
```bash
|
||||||
|
|
||||||
Deployment
|
|
||||||
|
|
||||||
|
|
||||||
Docker, Docker Compose, Nginx (Reverse Proxy), Gunicorn (WSGI Server)
|
|
||||||
► Local Installation & Setup Guide
|
|
||||||
|
|
||||||
These instructions will guide a developer in setting up the project on their local machine for development and testing.
|
|
||||||
Prerequisites
|
|
||||||
|
|
||||||
Ensure you have the following software installed on your system:
|
|
||||||
|
|
||||||
Python (version 3.9+) & Pip
|
|
||||||
|
|
||||||
Node.js (version 16+) & Npm
|
|
||||||
|
|
||||||
PostgreSQL (a running local instance)
|
|
||||||
|
|
||||||
Git
|
|
||||||
|
|
||||||
1. Clone the Repository
|
|
||||||
|
|
||||||
git clone <your-repository-url>
|
git clone <your-repository-url>
|
||||||
cd SWAPSTATION_WEBAPP
|
cd SWAPSTATION_WEBAPP
|
||||||
|
```
|
||||||
|
|
||||||
2. Backend Setup
|
### 2️⃣ Backend Setup
|
||||||
|
```bash
|
||||||
|
cd backend
|
||||||
|
```
|
||||||
|
---
|
||||||
|
|
||||||
Navigate to the backend directory:
|
### Create and Activate Virtual Environment
|
||||||
|
|
||||||
cd backend
|
macOS/Linux
|
||||||
|
```bash
|
||||||
|
python3 -m venv venv
|
||||||
|
source venv/bin/activate
|
||||||
|
```
|
||||||
|
|
||||||
Create and activate a Python virtual environment:
|
---
|
||||||
|
Windows
|
||||||
|
```bash
|
||||||
|
python -m venv venv
|
||||||
|
.\venv\Scripts\activate
|
||||||
|
```
|
||||||
|
Install Dependencies
|
||||||
|
```bash
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
---
|
||||||
|
|
||||||
# For macOS/Linux
|
### Configure PostgreSQL
|
||||||
python3 -m venv venv
|
|
||||||
source venv/bin/activate
|
|
||||||
|
|
||||||
# For Windows
|
1. Start your local PostgreSQL service.
|
||||||
python -m venv venv
|
|
||||||
.\venv\Scripts\activate
|
|
||||||
|
|
||||||
Install Python dependencies:
|
2. Create a database and user.
|
||||||
|
|
||||||
pip install -r requirements.txt
|
```bash
|
||||||
|
CREATE DATABASE swap_station_db;
|
||||||
|
CREATE USER swap_app_user WITH PASSWORD 'your_secure_password';
|
||||||
|
ALTER DATABASE swap_station_db OWNER TO swap_app_user;
|
||||||
|
```
|
||||||
|
---
|
||||||
|
|
||||||
Set up the PostgreSQL Database:
|
### Set Environment Variables
|
||||||
|
Create a .env file in the backend/ directory:
|
||||||
|
```bash
|
||||||
|
# backend/.env
|
||||||
|
SECRET_KEY="a_random_secret_key_for_flask"
|
||||||
|
DATABASE_URL="postgresql://swap_app_user:your_secure_password@localhost:5432/swap_station_db"
|
||||||
|
CORS_ALLOWED_ORIGIN="http://127.0.0.1:5500"
|
||||||
|
```
|
||||||
|
|
||||||
Start your local PostgreSQL service.
|
---
|
||||||
|
### 3️⃣ Frontend Setup
|
||||||
|
```bash
|
||||||
|
cd ../frontend
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
Create a new user and a new database for the application. For example, using psql:
|
---
|
||||||
|
|
||||||
CREATE DATABASE swap_station_db;
|
### ▶️ Running the Application Locally
|
||||||
CREATE USER swap_app_user WITH PASSWORD 'your_secure_password';
|
|
||||||
ALTER DATABASE swap_station_db OWNER TO swap_app_user;
|
|
||||||
|
|
||||||
Configure Environment Variables:
|
Start Backend
|
||||||
|
```bash
|
||||||
|
cd backend
|
||||||
|
flask run --host=0.0.0.0 --port=5000
|
||||||
|
```
|
||||||
|
Backend API and WebSocket server → http://localhost:5000
|
||||||
|
|
||||||
Create a .env file inside the backend/ directory.
|
### Start Frontend
|
||||||
|
- Open frontend/index.html with VS Code Live Server
|
||||||
|
|
||||||
Copy the contents of .env.example (if it exists) or use the template below, filling in your local database details.
|
- The app will be served at → http://127.0.0.1:5500
|
||||||
|
|
||||||
# backend/.env
|
---
|
||||||
SECRET_KEY="a_random_secret_key_for_flask"
|
|
||||||
DATABASE_URL="postgresql://swap_app_user:your_secure_password@localhost:5432/swap_station_db"
|
|
||||||
CORS_ALLOWED_ORIGIN="[http://127.0.0.1:5500](http://127.0.0.1:5500)" # For VS Code Live Server
|
|
||||||
|
|
||||||
3. Frontend Setup
|
### ☁️ Deployment
|
||||||
|
|
||||||
Navigate to the frontend directory:
|
- This project is production-ready and designed for Docker-based deployment.
|
||||||
|
|
||||||
# From the project root
|
- For detailed step-by-step cloud deployment instructions (e.g., on AWS EC2), see:
|
||||||
cd frontend
|
|
||||||
|
|
||||||
Install Node.js dependencies:
|
📘 **DEPLOYMENT.md**
|
||||||
|
|
||||||
npm install
|
---
|
||||||
|
|
||||||
► Running the Application Locally
|
### 🤝 Contributing
|
||||||
|
|
||||||
Start the Backend Server:
|
We welcome contributions!
|
||||||
|
To propose changes:
|
||||||
|
|
||||||
Make sure you are in the backend/ directory with your virtual environment activated.
|
1. Fork the repository.
|
||||||
|
|
||||||
Run the Flask application. The first time you run this, it will create the necessary database tables.
|
2. Create a new branch:
|
||||||
|
|
||||||
flask run --host=0.0.0.0 --port=5000
|
```bash
|
||||||
|
git checkout -b feature/your-feature-name
|
||||||
|
```
|
||||||
|
|
||||||
The backend API and WebSocket server is now running on http://localhost:5000.
|
3. Make and commit your changes with a clear message.
|
||||||
|
|
||||||
Serve the Frontend:
|
4. Push your branch:
|
||||||
|
|
||||||
The simplest way to serve the frontend for local development is using the Live Server extension in Visual Studio Code.
|
```bash
|
||||||
|
git push origin feature/your-feature-name
|
||||||
|
```
|
||||||
|
|
||||||
Right-click on the frontend/index.html file and select "Open with Live Server".
|
5. Open a Pull Request to the main branch.
|
||||||
|
|
||||||
This will open the application in your browser, typically at http://127.0.0.1:5500.
|
Report issues or request features using the **GitHub Issues** tab.
|
||||||
|
|
||||||
► Deployment
|
---
|
||||||
|
|
||||||
This application is designed for production deployment using Docker. For detailed, step-by-step instructions on how to deploy the application to an AWS server, please refer to the official guide:
|
### ⚖️ License
|
||||||
|
|
||||||
➡️ DEPLOYMENT.md
|
Licensed under the MIT License.
|
||||||
► Contributing
|
See the **LICENSE** file for details.
|
||||||
|
|
||||||
Contributions are welcome! If you'd like to contribute to the project, please follow these steps:
|
---
|
||||||
|
|
||||||
Fork the repository on GitHub.
|
### 🗂️ Project Structure
|
||||||
|
|
||||||
Create a new branch for your feature or bug fix (git checkout -b feature/your-feature-name).
|
```bash
|
||||||
|
SWAPSTATION_WEBAPP/
|
||||||
|
├── backend/ # Flask backend
|
||||||
|
│ ├── core/ # Core app logic and services
|
||||||
|
│ ├── models/ # Database ORM models
|
||||||
|
│ ├── proto/ # Protobuf definitions (if applicable)
|
||||||
|
│ ├── main.py # Flask entry point
|
||||||
|
│ └── requirements.txt
|
||||||
|
│
|
||||||
|
├── frontend/ # Frontend source files
|
||||||
|
│ ├── js/ # JavaScript logic
|
||||||
|
│ ├── css/ # Tailwind and custom styles
|
||||||
|
│ ├── assets/ # Images, icons, and static content
|
||||||
|
│ └── *.html # UI pages
|
||||||
|
│
|
||||||
|
├── Dockerfile # Build definition for backend container
|
||||||
|
├── docker-compose.yml # Multi-service container orchestration
|
||||||
|
├── nginx.conf # Reverse proxy configuration
|
||||||
|
├── DEPLOYMENT.md # Cloud deployment instructions
|
||||||
|
├── .gitignore
|
||||||
|
└── README.md # This file
|
||||||
|
```
|
||||||
|
|
||||||
Make your changes and commit them with a clear, descriptive message.
|
---
|
||||||
|
|
||||||
Push your branch to your fork (git push origin feature/your-feature-name).
|
### 🌐 Future Enhancements
|
||||||
|
|
||||||
Create a Pull Request back to the main repository.
|
- Integration with Grafana or Plotly Dash for richer analytics
|
||||||
|
|
||||||
Please report any bugs or suggest features using the GitHub Issues tab.
|
- Mobile-friendly responsive layout
|
||||||
► License
|
|
||||||
|
|
||||||
This project is licensed under the MIT License. See the LICENSE file for details.
|
- Integration with real swap station MQTT brokers for live hardware testing
|
||||||
► Project Structure
|
|
||||||
|
|
||||||
/SWAPSTATION_WEBAPP
|
|
||||||
|-- backend/ # Contains all Python/Flask backend source code
|
|
||||||
| |-- core/
|
|
||||||
| |-- models/
|
|
||||||
| |-- proto/
|
|
||||||
| |-- main.py # Main Flask application entry point
|
|
||||||
| |-- requirements.txt
|
|
||||||
|
|
|
||||||
|-- frontend/ # Contains all frontend assets
|
|
||||||
| |-- js/ # JavaScript files
|
|
||||||
| |-- css/ # CSS files
|
|
||||||
| |-- assets/ # Images and other static assets
|
|
||||||
| |-- *.html # HTML pages
|
|
||||||
|
|
|
||||||
|-- .gitignore # Specifies files to be ignored by Git
|
|
||||||
|-- Dockerfile # Instructions to build the production Docker image
|
|
||||||
|-- docker-compose.yml # Defines services for Docker Compose
|
|
||||||
|-- nginx.conf # Nginx configuration for the reverse proxy
|
|
||||||
|-- DEPLOYMENT.md # Detailed deployment guide
|
|
||||||
|-- README.md # This file
|
|
||||||
|
|
||||||
|
- Role-based dashboards (admin/operator views)
|
||||||
Loading…
Reference in New Issue