Add doc/device-signals.md
This commit is contained in:
parent
e7ab7afb66
commit
abb6312c61
390
doc/device-signals.md
Normal file
390
doc/device-signals.md
Normal file
@ -0,0 +1,390 @@
|
||||
# 📡 Taekwondo Scoring System – Device Signals & Communication Protocol
|
||||
|
||||
> **Version:** 2.0 (Full Device Coverage)
|
||||
> **Last Updated:** July 2025
|
||||
> **Target Developer:** Embedded (ESP32) & Android (.NET) Developers
|
||||
> **Purpose:** Define **two-way communication** for **all battery-powered devices**: joysticks, hogu, and headgear
|
||||
|
||||
---
|
||||
|
||||
## 📌 Table of Contents
|
||||
|
||||
- [1. Overview](#1-overview)
|
||||
- [2. Device Types](#2-device-types)
|
||||
- [3. Communication Model (TCP Full-Duplex)](#3-communication-model-tcp-full-duplex)
|
||||
- [4. Common Device Signals](#4-common-device-signals)
|
||||
- [5. Referee Joystick](#5-referee-joystick)
|
||||
- [6. Hogu (Trunk Protector)](#6-hogu-trunk-protector)
|
||||
- [7. Headgear](#7-headgear)
|
||||
- [8. OLED Display (128x64, I2C 0x3C)](#8-oled-display-128x64-i2c-0x3c)
|
||||
- [9. Telemetry: Battery & Health Monitoring](#9-telemetry-battery--health-monitoring)
|
||||
- [10. Feedback: Vibration, LED, Buzzer](#10-feedback-vibration-led-buzzer)
|
||||
- [11. Command & Response Format](#11-command--response-format)
|
||||
- [12. ESP32 Code Structure (Modular)](#12-esp32-code-structure-modular)
|
||||
- [13. Android .NET Server Integration](#13-android-net-server-integration)
|
||||
- [14. Best Practices](#14-best-practices)
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
All **battery-powered devices** in the system support **two-way TCP communication**:
|
||||
|
||||
- ✅ **Send**: Sensor data, telemetry, events
|
||||
- ✅ **Receive**: Feedback commands, display updates, calibration
|
||||
- ✅ **Device Types**:
|
||||
- **Referee Joysticks** (4 units)
|
||||
- **Hogu (Trunk Protector)** – Red & Blue
|
||||
- **Headgear** – Red & Blue
|
||||
|
||||
Each device identifies itself with:
|
||||
```
|
||||
DEVICE:NAME=...,TYPE=...,MAC=...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Device Types
|
||||
|
||||
| Device | Type | Key Features |
|
||||
|-------|------|-------------|
|
||||
| **Joystick** | `JOYSTICK` | Button, OLED, vibration, LED, buzzer, battery telemetry |
|
||||
| **Hogu** | `SENSOR` | Force sensor (FSR), MPU6050 (spinning), OLED, vibration, battery |
|
||||
| **Headgear** | `SENSOR` | Force sensor, MPU6050, OLED, vibration, battery |
|
||||
|
||||
> All use **ESP32-C3**, **LiPo battery**, and **I2C OLED (0x3C)**.
|
||||
|
||||
---
|
||||
|
||||
## 3. Communication Model (TCP Full-Duplex)
|
||||
|
||||
```
|
||||
[All Devices] ↔ [Android Tablet: TCP Server (Port 5000)]
|
||||
```
|
||||
|
||||
- Devices connect to `192.168.4.1:5000` (hotspot mode)
|
||||
- First message: `DEVICE:NAME=...,TYPE=...,MAC=...`
|
||||
- Subsequent messages: JSON `\n`-terminated
|
||||
- Server can send commands at any time
|
||||
|
||||
> Full-duplex: **Send and receive on same connection**.
|
||||
|
||||
---
|
||||
|
||||
## 4. Common Device Signals
|
||||
|
||||
### 4.1 Device Identity (Mandatory First Message)
|
||||
```
|
||||
DEVICE:NAME=HOGU_RED,TYPE=SENSOR,MAC=30:85:A9:12:34:56
|
||||
```
|
||||
|
||||
### 4.2 Telemetry (Periodic, Every 60 sec)
|
||||
```json
|
||||
{
|
||||
"type": "telemetry",
|
||||
"device": "HOGU_RED",
|
||||
"battery_level": 88,
|
||||
"battery_voltage": 4.02,
|
||||
"rssi": -65,
|
||||
"uptime": 3420,
|
||||
"timestamp": 1712345679000
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 Command Acknowledgment
|
||||
```json
|
||||
{"ack": "vibrate", "time": 1712345679100}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Referee Joystick
|
||||
|
||||
### 📥 Outgoing
|
||||
- `button` press
|
||||
- `telemetry`
|
||||
|
||||
### 📤 Incoming Commands
|
||||
- `vibrate` – tactile feedback
|
||||
- `buzz` – audible alert
|
||||
- `led` – status indication
|
||||
- `display` – show text
|
||||
- `ping` – liveness check
|
||||
|
||||
### Example Button Press
|
||||
```json
|
||||
{"type":"button","device":"JOYSTICK_CORNER_1","pressed":true,"time":1712345678905}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Hogu (Trunk Protector)
|
||||
|
||||
### 📥 Outgoing
|
||||
|
||||
#### 6.1 Impact Detection
|
||||
```json
|
||||
{
|
||||
"type": "impact",
|
||||
"device": "hogu_red",
|
||||
"force": 850,
|
||||
"spinning": true,
|
||||
"time": 1712345678901
|
||||
}
|
||||
```
|
||||
|
||||
- `force`: 0–1023 (analog read)
|
||||
- `spinning`: from MPU6050 (rotation > 180°)
|
||||
|
||||
#### 6.2 Telemetry
|
||||
Same as joystick, includes sensor health.
|
||||
|
||||
---
|
||||
|
||||
### 📤 Incoming Commands
|
||||
|
||||
| Command | Effect |
|
||||
|--------|--------|
|
||||
| `vibrate` | Confirm impact registered |
|
||||
| `led` | Flash green/red for status |
|
||||
| `display` | Show "HOGU RED", battery, status |
|
||||
| `calibrate` | Recalibrate force sensor |
|
||||
| `ping` | Liveness check |
|
||||
|
||||
#### Example: Calibrate Command
|
||||
```json
|
||||
{"cmd": "calibrate", "mode": "zero"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Headgear
|
||||
|
||||
### 📥 Outgoing
|
||||
|
||||
#### 7.1 Impact Detection
|
||||
```json
|
||||
{
|
||||
"type": "impact",
|
||||
"device": "head_blue",
|
||||
"force": 720,
|
||||
"spinning": false,
|
||||
"time": 1712345678903
|
||||
}
|
||||
```
|
||||
|
||||
> Lower force threshold (safety).
|
||||
|
||||
#### 7.2 Telemetry
|
||||
Same format, sent every 60 sec.
|
||||
|
||||
---
|
||||
|
||||
### 📤 Incoming Commands
|
||||
|
||||
| Command | Effect |
|
||||
|--------|--------|
|
||||
| `vibrate` | Confirm head kick detected |
|
||||
| `led` | Status light (e.g., red = fault) |
|
||||
| `display` | Show "HEAD BLUE", battery |
|
||||
| `ping` | Liveness check |
|
||||
|
||||
> No `calibrate` — headgear is sealed.
|
||||
|
||||
---
|
||||
|
||||
## 8. OLED Display (128x64, I2C 0x3C)
|
||||
|
||||
All devices have the same OLED for **status and feedback**.
|
||||
|
||||
### 8.1 Display Modes
|
||||
|
||||
| Device | Normal | Active | Low Battery | Error |
|
||||
|-------|--------|--------|-------------|-------|
|
||||
| **Joystick** | `CORNER 1`<br>`READY` | `PRESSED!` | `⚠️ BATT: 20%` | `NO SIGNAL` |
|
||||
| **Hogu** | `HOGU RED`<br>`OK` | `IMPACT!` | `⚠️ BATT: 15%` | `SENSOR FAULT` |
|
||||
| **Headgear** | `HEAD BLUE`<br>`ACTIVE` | `HIT DETECTED` | `⚠️ BATT: 10%` | `DISCONNECTED` |
|
||||
|
||||
---
|
||||
|
||||
### 8.2 Server Command
|
||||
```json
|
||||
{
|
||||
"cmd": "display",
|
||||
"lines": [
|
||||
{"text": "HOGU RED", "y": 0},
|
||||
{"text": "IMPACT!", "y": 30, "color": "green"}
|
||||
],
|
||||
"refresh": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Telemetry: Battery & Health Monitoring
|
||||
|
||||
### 9.1 Battery Measurement (All Devices)
|
||||
```cpp
|
||||
float readBatteryVoltage() {
|
||||
int adc = analogRead(BATTERY_PIN);
|
||||
float voltage = (adc / 4095.0) * 3.3 * 2.0; // 2:1 divider
|
||||
return voltage;
|
||||
}
|
||||
|
||||
int getBatteryLevel(float voltage) {
|
||||
if (voltage >= 4.2) return 100;
|
||||
if (voltage <= 3.3) return 0;
|
||||
return (int)((voltage - 3.3) / 0.9 * 100);
|
||||
}
|
||||
```
|
||||
|
||||
### 9.2 Telemetry Frequency
|
||||
- Every **60 seconds**
|
||||
- Or on **significant change** (e.g., battery drop >5%)
|
||||
|
||||
---
|
||||
|
||||
## 10. Feedback: Vibration, LED, Buzzer
|
||||
|
||||
### 10.1 Pin Assignments (Shared)
|
||||
|
||||
| Component | GPIO |
|
||||
|---------|------|
|
||||
| Vibration Motor | 4 |
|
||||
| Buzzer | 5 |
|
||||
| LED (RGB) | 6 (R), 7 (G), 8 (B) |
|
||||
| OLED (SDA) | 21 |
|
||||
| OLED (SCL) | 22 |
|
||||
| FSR (Hogu) | 34 |
|
||||
| FSR (Head) | 35 |
|
||||
| MPU6050 (SCL/SDA) | 21, 22 (shared with OLED) |
|
||||
|
||||
> Use **I2C multiplexer** if needed.
|
||||
|
||||
---
|
||||
|
||||
### 10.2 Feedback Examples
|
||||
|
||||
#### Vibrate (200ms)
|
||||
```json
|
||||
{"cmd": "vibrate", "duration": 200}
|
||||
```
|
||||
|
||||
#### LED: Green Blink (3 times)
|
||||
```json
|
||||
{"cmd": "led", "color": "#00FF00", "mode": "blink", "count": 3}
|
||||
```
|
||||
|
||||
#### Buzzer: Short beep
|
||||
```json
|
||||
{"cmd": "buzz", "tone": 1000, "duration": 150}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Command & Response Format
|
||||
|
||||
### 11.1 Outgoing (Device → Server)
|
||||
```json
|
||||
{"type":"impact","device":"head_blue","force":720,"spinning":false,"time":1712345678903}
|
||||
```
|
||||
```json
|
||||
{"type":"telemetry","device":"HOGU_RED","battery_level":88,"rssi":-65,"timestamp":1712345679000}
|
||||
```
|
||||
|
||||
### 11.2 Incoming (Server → Device)
|
||||
```json
|
||||
{"cmd":"vibrate","duration":200}
|
||||
{"cmd":"led","color":"#0000FF","mode":"solid"}
|
||||
{"cmd":"display","lines":[{"text":"IMPACT!","y":30}]}
|
||||
{"cmd":"ping"}
|
||||
```
|
||||
|
||||
> Device responds to `ping` with:
|
||||
```json
|
||||
{"ack":"ping","time":1712345679100}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. ESP32 Code Structure (Modular)
|
||||
|
||||
Use a **modular design** with shared components:
|
||||
|
||||
```
|
||||
/src/
|
||||
├── main.cpp
|
||||
├── wifi_manager.cpp
|
||||
├── tcp_client.cpp
|
||||
├── oled_display.cpp
|
||||
├── battery_monitor.cpp
|
||||
├── sensors/
|
||||
│ ├── fsr.cpp
|
||||
│ └── mpu6050.cpp
|
||||
├── feedback/
|
||||
│ ├── vibration.cpp
|
||||
│ ├── buzzer.cpp
|
||||
│ └── led.cpp
|
||||
└── device_config.h
|
||||
```
|
||||
|
||||
### Example: `device_config.h`
|
||||
```cpp
|
||||
#define DEVICE_NAME "HOGU_RED"
|
||||
#define DEVICE_TYPE "SENSOR"
|
||||
#define OLED_ADDR 0x3C
|
||||
#define BATTERY_PIN 35
|
||||
#define VIBRO_PIN 4
|
||||
#define BUZZER_PIN 5
|
||||
#define LED_PIN 6
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. Android .NET Server Integration
|
||||
|
||||
### Send Command to Any Device
|
||||
```csharp
|
||||
void SendCommand(string mac, string commandJson)
|
||||
{
|
||||
TcpClient client = GetDeviceByMac(mac);
|
||||
if (client?.Connected == true)
|
||||
{
|
||||
var stream = client.GetStream();
|
||||
var writer = new StreamWriter(stream);
|
||||
await writer.WriteLineAsync(commandJson);
|
||||
await writer.FlushAsync();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example: Confirm Impact
|
||||
```csharp
|
||||
// After auto-scoring
|
||||
SendCommand("30:85:A9:12:34:56", "{\"cmd\":\"vibrate\",\"duration\":200}");
|
||||
SendCommand("30:85:A9:12:34:56", "{\"cmd\":\"led\",\"color\":\"#00FF00\",\"mode\":\"blink\",\"count\":2}");
|
||||
```
|
||||
|
||||
### Broadcast to All Sensors
|
||||
```csharp
|
||||
foreach (var device in GetAllSensors())
|
||||
{
|
||||
SendCommand(device.Mac, "{\"cmd\":\"display\",\"lines\":[{\"text\":\"MATCH START\"}]}");
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. Best Practices
|
||||
|
||||
| Practice | Why |
|
||||
|--------|-----|
|
||||
| Send telemetry every 60 sec | Monitor battery and health |
|
||||
| Debounce sensor inputs | Prevent false triggers |
|
||||
| Use I2C for OLED & MPU6050 | Save pins |
|
||||
| Add `ping` command | Check device liveness |
|
||||
| Log all commands | Debugging and auditing |
|
||||
| Low-power mode | Extend battery life |
|
||||
| Clear OLED on boot | Avoid ghosting |
|
||||
| Validate MAC before sending | Prevent errors |
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user