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.
|
||||
► Key Features
|
||||
- A **full-stack web application** for real-time monitoring, control, and analytics of battery swap stations.
|
||||
- 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
|
||||
---
|
||||
|
||||
Backend
|
||||
|
||||
## 🧠 Tech Stack
|
||||
|
||||
Python 3, Flask, Flask-SocketIO, SQLAlchemy, PostgreSQL
|
||||
| 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) |
|
||||
|
||||
Frontend
|
||||
|
||||
---
|
||||
|
||||
HTML5, CSS3, JavaScript (ES6+), Tailwind CSS, Chart.js, Flatpickr.js
|
||||
## 🧩 Local Installation & Setup Guide
|
||||
|
||||
Real-Time Engine
|
||||
|
||||
Follow these steps to set up the application locally for development or testing.
|
||||
|
||||
MQTT (for station communication), WebSockets (for client communication)
|
||||
### ✅ Prerequisites
|
||||
Ensure the following are installed:
|
||||
|
||||
Deployment
|
||||
|
||||
- **Python** ≥ 3.9
|
||||
- **Node.js** ≥ 16 and **npm**
|
||||
- **PostgreSQL** (local instance running)
|
||||
- **Git**
|
||||
|
||||
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
|
||||
### 1️⃣ Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone <your-repository-url>
|
||||
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
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
### Configure PostgreSQL
|
||||
|
||||
# For Windows
|
||||
python -m venv venv
|
||||
.\venv\Scripts\activate
|
||||
1. Start your local PostgreSQL service.
|
||||
|
||||
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;
|
||||
CREATE USER swap_app_user WITH PASSWORD 'your_secure_password';
|
||||
ALTER DATABASE swap_station_db OWNER TO swap_app_user;
|
||||
### ▶️ Running the Application Locally
|
||||
|
||||
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
|
||||
cd frontend
|
||||
- For detailed step-by-step cloud deployment instructions (e.g., on AWS EC2), see:
|
||||
|
||||
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
|
||||
► Contributing
|
||||
Licensed under the MIT License.
|
||||
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.
|
||||
► License
|
||||
- Mobile-friendly responsive layout
|
||||
|
||||
This project is licensed under the MIT License. See the LICENSE file for details.
|
||||
► 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
|
||||
- Integration with real swap station MQTT brokers for live hardware testing
|
||||
|
||||
- Role-based dashboards (admin/operator views)
|
||||
Loading…
Reference in New Issue