6.5 KiB

Raw Blame History

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

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.

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.

Data Export: Export detailed periodic and event logs as CSV files for offline analysis and record-keeping.

Station & User Management: Securely add, remove, and manage swap stations and user accounts.

Dockerized for Deployment: The entire application is containerized using Docker, Nginx, and Gunicorn, ensuring consistent and reliable deployment to any cloud environment.

► Tech Stack

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 (for station communication), WebSockets (for client communication)

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

Clone the Repository

git clone cd SWAPSTATION_WEBAPP

Backend Setup

Navigate to the backend directory:

cd backend

Create and activate a Python virtual environment:

For macOS/Linux

python3 -m venv venv source venv/bin/activate

For Windows

python -m venv venv .\venv\Scripts\activate

Install Python dependencies:

pip install -r requirements.txt

Set up the PostgreSQL Database:

 Start your local PostgreSQL service.

 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;

Configure Environment Variables:

 Create a .env file inside the backend/ directory.

 Copy the contents of .env.example (if it exists) or use the template below, filling in your local database details.

 # 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

Frontend Setup

Navigate to the frontend directory:

From the project root

cd frontend

Install Node.js dependencies:

npm install

► Running the Application Locally

Start the Backend Server:

    Make sure you are in the backend/ directory with your virtual environment activated.

    Run the Flask application. The first time you run this, it will create the necessary database tables.

    flask run --host=0.0.0.0 --port=5000

    The backend API and WebSocket server is now running on http://localhost:5000.

Serve the Frontend:

    The simplest way to serve the frontend for local development is using the Live Server extension in Visual Studio Code.

    Right-click on the frontend/index.html file and select "Open with Live Server".

    This will open the application in your browser, typically at http://127.0.0.1:5500.

► API Endpoints Overview

The backend provides the following main RESTful API endpoints. All are prefixed with /api.

Endpoint

Method

Description

/login

POST

Authenticates a user.

/users

POST

Adds a new user account.

/stations

GET

Retrieves a list of all stations.

/stations

POST

Adds a new station to the system.

/stations/

DELETE

Removes a station from the system.

/stations/daily-stats

GET

Gets swap statistics for all stations (last 24h).

/analytics

GET

Fetches detailed historical analytics data.

/logs/recent/

GET

Retrieves recent logs for a specific station.

/logs/export

GET

Exports logs as a CSV file.

/uptime/

GET

Gets the live uptime percentage for a station. ► 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:

➡️ DEPLOYMENT.md ► Contributing

Contributions are welcome! If you'd like to contribute to the project, please follow these steps:

Fork the repository on GitHub.

Create a new branch for your feature or bug fix (git checkout -b feature/your-feature-name).

Make your changes and commit them with a clear, descriptive message.

Push your branch to your fork (git push origin feature/your-feature-name).

Create a Pull Request back to the main repository.

Please report any bugs or suggest features using the GitHub Issues tab. ► License

This project is licensed under the MIT License. See the LICENSE file for details. ► Project Structure

6.5 KiB Raw Blame History

For macOS/Linux

For Windows

From the project root

6.5 KiB

Raw Blame History