Newer
Older
# 📘 **Arduino Jump Dash — Full Project README**
## 🎮 Overview
This project is a comprehensive IoT gaming system connecting a **React-based Geometry Dash–style game** with an **Arduino board** and a **real-time monitoring dashboard**.
The system is fully containerized using Docker and orchestrated via Docker Compose.
**Key Interactions:**
* **Player Input:** Controls the character via an **Arduino Button**, Keyboard, or Touch.
* **Game Control:** Adjust game speed in real-time using an **Arduino Physical Rotator**.
* **Feedback:** Score and Death counts are sent back to the Arduino **7-Segment Display**.
* **Monitoring:** A dedicated Monitor Server broadcasts game events to a **React Dashboard** for real-time analytics.
* **Persistence:** Game data is buffered and synced to a **PostgreSQL database**.
# 🧱 **Project Architecture**
The system is split into four main containerized services + a database.
```
┌──────────────────┐
│ PostgreSQL │
│ (Persistence) │
└────────▲─────────┘
│ (Buffer 10s)
│
┌─────────────────┐ ┌────────▼─────────┐ ┌──────────────────┐
│ Game Client │ <----> │ Game Server │ -----> │ Monitor Server │
│ (React + Vite) │ WS │ (Node + Serial) │ WS │ (Node) │
└─────────────────┘ └────────┬─────────┘ └────────┬─────────┘
│ │
│ Serial / USB │ WS
▼ ▼
┌──────────────────────────────┐ ┌──────────────────┐
│ Arduino │ │ Monitor Client │
│ - Button (Jump) │ │ (React + Vite) │
│ - Rotator (Game Speed) │ └──────────────────┘
│ - 7-Segment (Score Display) │
└──────────────────────────────┘
```
# 🛠️ **Technologies Used**
### **Frontend (Game & Monitor)**
* **React** with **Vite**
* TypeScript
* HTML5 Canvas (Game Logic)
* CSS Responsive Layout
* WebSocket Client
### **Backend (Game & Monitor Servers)**
* **Node.js** + Express
* **WebSocket** (ws) for real-time communication
* **SerialPort** (Hardware Interface)
* **PostgreSQL** (Data Persistence)
* **Docker** & **Docker Compose** (Containerization)
### **Hardware**
* Arduino Board
* Push Button (Jump Input)
* **Physical Rotator/Potentiometer** (Speed Control)
* Seven-Segment Display (SevSeg Library)
# 🔌 **Setup & Installation**
The entire stack is Dockerized. You do not need to install Node or Postgres locally to run the full system.
## 1️⃣ Hardware Setup
1. Connect the **Button**, **Rotator**, and **7-Segment Display** to your Arduino.
2. Upload the sketch found in `arduino/controller/controller.ino`.
3. Ensure the Arduino is connected via USB to the machine running the containers.
## 2️⃣ Docker Start (Recommended)
We use **Docker Compose** to bring up services in the correct order:
1. **PostgreSQL Database**
2. **Game Server** (Connects to DB & Arduino)
3. **Monitor Server** (Connects to Game Server)
4. **Clients** (Game & Monitor Frontends)
Run the following command in the root directory:
```bash
docker-compose up --build
```
*Note: You may need to map the specific USB port in `docker-compose.yml` depending on your OS (e.g., `/dev/ttyUSB0` or `COM3`).*
-----
# 📁 **Project Structure**
```
.
├── arduino
│ └── controller
│ └── controller.ino # Arduino Sketch (Button, Rotator, SevSeg)
├── docker-compose.yml # Orchestration for DB, Servers, Clients
├── game
│ ├── client # React + Vite Game Frontend
│ │ ├── Dockerfile
│ │ └── src/ # Game Logic & Canvas
│ └── server # Node.js Game Backend
│ ├── db/ # Postgres Connection & Schemas
│ ├── Dockerfile
│ └── server.js # Handles Serial, WS, and DB buffering
├── monitor
│ ├── client # React + Vite Dashboard Frontend
│ │ ├── Dockerfile
│ │ └── src/ # Charts & Stats Components
│ └── server # Node.js Monitor Backend
│ ├── Dockerfile
│ └── monitor-arduino.js # Broadcasts events to dashboards
└── readme.md
```
# 🖥️ **Frontend Features**
### **Game Client (React)**
* Geometry Dash–style gameplay via Canvas.
* **Input Methods:** Arduino Button, Keyboard (Space), Mobile Touch.
* **Speed Control:** Listens for speed updates triggered by the **Arduino Rotator**.
### **Monitor Client (React)**
* Real-time dashboard visualization.
* Displays live Score, Death counts, and Sensor data.
* Receives broadcasted data from the Monitor Server.
# 💾 **Data Persistence & Protocol**
### **Database Strategy**
To prevent database throttling during high-frequency game events, the Game Server implements an **In-Memory Buffer**:
1. Game events (Score, Death, Jump) are stored temporarily in RAM.
2. **Every 10 seconds**, the buffer is flushed and bulk-inserted into **PostgreSQL**.
3. **Storage Format:** Records include the Event Data, **Sensor ID**, and **Timestamp**.
### **WebSocket Protocol**
#### **Arduino → Game Server**
* `JUMP` → Trigger player jump.
* `SPEED:<value>` → Update game speed based on rotator position.
#### **Game Server → Monitor Server**
Forwards all game events to the monitor network.
#### **Backend → Arduino**
* `S<number>` → Update Score on 7-Segment.
* `D<number>` → Update Deaths on 7-Segment.
# 🔧 **Arduino Logic**
The Arduino sketch handles three main tasks:
1. **Input (Button):** Detects press and sends `JUMP` via Serial.
2. **Input (Rotator):** Reads analog value from potentiometer, maps it to a speed factor, and sends `SPEED:<val>` via Serial.
3. **Output (Display):** Parses incoming serial data (`S##`, `D##`) to update the 7-segment display.
# 🧪 **Testing & Simulation**
If you do not have the hardware attached, you can still run the stack. The Docker containers will attempt to connect to Serial, but the web interface will function independently (controlled via Keyboard).
To test the **Monitor Dashboard**:
1. Open the Game Client (`http://localhost:port`).
2. Open the Monitor Client (`http://localhost:port`).
3. Play the game; stats will update in real-time on the Monitor.