TAKEONE/takeone-event-managment
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
takeone-event-managment/doc
History

readme.md

🥋 Taekwondo Electronic Scoring System – Developer Documentation

Version: 4.0 (Final & Complete)
Last Updated: July 2025
Target Developer: .NET Android (MAUI/Xamarin) with TCP experience
Project Goal: Build a fully automated, secure, broadcast-quality Taekwondo scoring system that works without any technical knowledge from referees or staff.

📌 Table of Contents

1. System Overview

This system automates Taekwondo sparring (kyorugi) scoring for clubs, tournaments, and non-technical users.

🎯 Key Principles

  • No IP, port, or network configuration required
  • Center referee has no device — uses only voice and hand signals
  • Scorekeeper uses an Android tablet to manage the system
  • All devices auto-connect to a self-hosted Wi-Fi network
  • Fully automatic scoring based on sensors and corner referee votes
  • Broadcast-quality display flow for audience engagement

🧩 Components

Device Role
Android Tablet TCP server, score control, match manager
ESP32-C3 Sensors Detect impact on hogu and headgear
ESP32-C3 Joysticks Corner referee voting (4 units)
Android TV 1 Live scoreboard (ring display)
Android TV 2 Upcoming matches (lobby display)

All devices connect via Wi-Fi and identify themselves securely.

2. Network Setup (Zero-Config Wi-Fi Hotspot)

To eliminate technical barriers, the Android tablet creates its own Wi-Fi network.

📶 Wi-Fi Settings

  • SSID: TKD_SCORING_COURT1
  • Password: taekwondo123 (default, printed on device label)
  • Tablet IP: 192.168.4.1 (fixed in hotspot mode)
  • Server Ports:
    • TCP: 5000 (data)
    • UDP: 5002 (discovery)

🔧 How It Works

  1. Scorekeeper powers on tablet
  2. App automatically enables Wi-Fi hotspot
  3. Staff connects all devices to TKD_SCORING_COURT1
  4. Devices auto-discover and connect to 192.168.4.1
  5. No user enters IP or port

✅ Works offline — no internet required.

3. Device Connection & Discovery

All devices auto-discover the server and connect with zero input.

🔄 Connection Flow

  1. Device powers on → connects to TKD_SCORING_COURT1
  2. Sends UDP broadcast: 
    TKD_DISCOVER
  3. Tablet responds: 
    SERVER_IP:192.168.4.1
  4. Device connects to 192.168.4.1:5000
  5. Sends identity: 
    DEVICE:NAME=HOGU_RED,TYPE=SENSOR,MAC=30:85:A9:12:34:56
  6. Server validates and registers

📱 Android TV Setup

  • Pre-install app
  • Auto-connect to TKD_SCORING_COURT1
  • App starts on boot and connects to server

4. Device Identity Format (NAME, TYPE, MAC)

Every device must send this exact format as the first line after connection:

DEVICE:NAME=<name>,TYPE=<type>,MAC=<mac>
Field Description Example
NAME Descriptive name HOGU_RED, JOYSTICK_CORNER_1, TV_SCOREBOARD
TYPE Device category SENSOR, JOYSTICK, DISPLAY
MAC Uppercase, colon-separated 30:85:A9:12:34:56

✅ Valid Examples

DEVICE:NAME=HOGU_RED,TYPE=SENSOR,MAC=30:85:A9:12:34:56

DEVICE:NAME=HEAD_BLUE,TYPE=SENSOR,MAC=30:85:A9:12:34:57

DEVICE:NAME=JOYSTICK_CORNER_1,TYPE=JOYSTICK,MAC=30:85:A9:12:34:58

DEVICE:NAME=TV_SCOREBOARD,TYPE=DISPLAY,MAC=18:3D:A2:01:02:03

🛠️ ESP32: Get MAC Address

#include <WiFi.h>
String getMacAddress() {
  uint8_t mac[6];
  WiFi.macAddress(mac);
  char macStr[18];
  sprintf(macStr, "%02X:%02X:%02X:%02X:%02X:%02X", mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);
  return String(macStr);
}

🖥️ Server: Parse Identity (C#)

Dictionary<string, string> ParseDeviceIdentity(string line) {
    var result = new Dictionary<string, string>();
    if (!line.StartsWith("DEVICE:")) return result;
    var parts = line.Substring(7).Split(',');
    foreach (var part in parts) {
        var kv = part.Split('=');
        if (kv.Length == 2) result[kv[0]] = kv[1];
    }
    return result;
}

5. Score Control App (Android Tablet)

Built with .NET MAUI / Xamarin, this app is the central brain.

🎯 Responsibilities

  • Act as TCP server (Port 5000)
  • Receive sensor/joystick data
  • Apply WT scoring rules
  • Control Android TV displays (Port 5001)
  • Manage match lifecycle
  • Log results
  • Monitor connected devices

🖼️ UI Screens

🏁 Home Screen

[Start Setup Mode]

🔍 Setup Mode

  • Auto-detects devices: 
    ✅ HOGU_RED
✅ HEAD_BLUE
🔔 Waiting for JOYSTICK_CORNER_1...
  • When all found: 
    [Lock System & Start Match]

⚔️ Live Match Screen

  • Timer (2:00)
  • Score: 🔴 4 vs 2 🔵
  • Event log
  • Referee vote indicators
  • Controls: Shi-jak, Kal-yeo, Next Round

🖥️ Device Monitor

MAC Name Type Status
30:.. HOGU_RED SENSOR ✅

6. Android TV Apps

📺 TV 1: Scoreboard App (Ring Display)

Modes

  • faceoff: Fighter face-off
  • score: Live scoring
  • break: Ads + highlights
  • call_to_action: "Fighters, return!"
  • winner: Winner celebration

Connection

  • Connects to 192.168.4.1:5001
  • Sends device identity

📺 TV 2: Match Display App (Lobby)

Features

  • Scrollable list of next 3–5 matches
  • Pulls from CSV or cloud
  • Tournament logo and sponsors

Connection

  • Same as above, name: TV_MATCH_DISPLAY

7. Scoring Rules & Auto-Scoring Logic

Based on World Taekwondo (WT) 2024 rules.

✅ Valid Techniques

Technique Points
Kick to trunk 1
Kick to head 3
Spinning kick to trunk 4
Spinning kick to head 5
Punch to trunk 1
Gam-jeom (penalty) +1 to opponent

❗ No input from center referee — only voice and signals.

🔄 Auto-Scoring Logic

A point is awarded if:

  1. Sensor detects impact (force > threshold)
  2. ≥3 out of 4 corner referees press within 1 second
  3. For spinning kicks: MPU6050 confirms rotation > 180°

Force Thresholds

  • Hogu: ≥ 500 (analog) or 800g
  • Head: ≥ 400 (for safety)

Timing Window

  • Referee button presses must be within ±1 second of impact
  • Debounce: Ignore same sensor hits within 500ms
void CheckForValidPoint(ImpactEvent impact)
{
    var votes = GetJoystickPressesInRange(impact.Time, 1000);
    if (votes.Count >= 3)
    {
        int points = CalculatePoints(impact);
        AddPoints(impact.Attacker, points);
        BroadcastScoreUpdate();
    }
}

8. Scoreboard Display Requirements

The main scoreboard displays 13 elements:

# Element Source
1 Court Number Match data
2 Match Number Schedule
3 Match Timer App timer
4 Round Counter Match state
5 Country Flag Fighter data
6 Country ISO3 Fighter data
7 Team Logo Fighter data
8 Fighter Name Match setup
9 Fighter Score Scoring engine
10 Fighter Fouls Penalty tracker
11 Fighter Weight (kg) Fighter profile
12 Weight Class & Category Match data
13 Team Name Fighter data

🎨 Example Layout

COURT 1          MATCH #105          ROUND 2/3
       MEN'S -68KG SEMIFINAL

 🇰🇷 KIM Min-jae        vs        LEE Jung-ho 🇨🇳
 Seoul TKD Club       vs        Beijing TKD
 [Logo]              vs              [Logo]

                 8   vs   5
                ⚠️         ⚠️⚠️

                    ⏱️  01:45

       67.2 kg                 67.8 kg

9. Match Presentation Flow

1. Face-Off (10 sec)

  • Fighter photos, names, flags
  • Before "Shi-jak"

2. Live Scoring (2:00)

  • Real-time score, timer, fouls

3. Break (60 sec)

  • 0–50 sec: Sponsor ad
  • 50–58 sec: Round highlights (video)
  • 58–60 sec: Fade to next phase

4. Call to Action (10 sec)

  • Full-screen: "FIGHTERS, RETURN TO THE RING!"
  • Flashing text, sound cues at 5 and 1 sec

5. Winner Screen (15 sec)

  • Winner enlarged
  • Confetti animation
  • Final score

10. Match Management

Matches can be created in three ways:

1. Single Match (Manual)

  • Enter red/blue names, weight, team
  • Ideal for training

2. CSV Import

match_id,red_name,blue_name,weight,round,red_country,blue_country,red_photo,blue_photo
M101,Kim,Lee,-58kg,Quarter,KOR,CHN,https://...,https://...

3. Cloud API Sync

  • GET https://api.tournament.com/matches
  • Polls every 60 seconds

🔄 Auto-Advance

After match ends:

  1. Log result
  2. Load next match
  3. Show face-off on TVs
  4. Wait for "Start Match"

11. Result Logging

After each match, results are saved.

📄 JSON Format

{
  "match_id": "M105",
  "court": "1",
  "weight_class": "Men's -68kg",
  "round": "Final",
  "red": { "name": "Kim", "team": "Seoul", "score": 8, "fouls": 1 },
  "blue": { "name": "Lee", "team": "Beijing", "score": 5, "fouls": 2 },
  "winner": "red",
  "duration": 180,
  "timestamp": "2025-07-10T11:15:30Z"
}

💾 Export Options

  • Save to Documents/results.json
  • Append to results.csv
  • POST to cloud API
  • Share via email or USB

12. Security & Validation

🔐 Allowed Device List

  • Server has pre-loaded list of allowed MAC addresses
  • Stored in app (JSON or SQLite)
  • Unknown devices are ignored silently

🚫 Connection Rules

  • After "Lock System" → no new connections
  • Disconnected device → can only rejoin in Setup Mode
  • Only devices with correct TYPE and NAME are accepted

13. Full JSON Message Examples

From Sensor

{"type":"impact","device":"head_blue","force":900,"spinning":true,"time":1712345678901}

From Joystick

{"type":"button","device":"corner_2","pressed":true,"time":1712345678905}

To Scoreboard TV

{
  "mode": "score",
  "court": "1",
  "match_number": "105",
  "weight_class": "Men's -68kg",
  "category": "Semifinal",
  "round": "2",
  "timer": "01:45",
  "red": {
    "name": "Kim Min-jae",
    "country": "KOR",
    "team": "Seoul TKD Club",
    "logo": "https://logos/seoul.png",
    "flag": "https://flags/kor.png",
    "score": 8,
    "fouls": 1,
    "weight_kg": 67.2
  },
  "blue": {
    "name": "Lee Jung-ho",
    "country": "CHN",
    "team": "Beijing TKD",
    "logo": "https://logos/beijing.png",
    "flag": "https://flags/chn.png",
    "score": 5,
    "fouls": 2,
    "weight_kg": 67.8
  }
}

14. Developer To-Do List

Task Status
Implement Wi-Fi hotspot mode (Android) ☐
Build TCP server (Port 5000) ☐
Implement UDP discovery (Port 5002) ☐
Parse device identity (NAME,TYPE,MAC) ☐
Validate devices against allowed list ☐
Implement auto-scoring logic ☐
Design Match Setup UI with all fields ☐
Add country flag, team logo support ☐
Send rich scoreboard JSON (13 fields) ☐
Create Android TV apps ☐
Support video playback for highlights ☐
Implement break mode with ads ☐
Add call-to-action screen ☐
Create winner screen with animation ☐
Add match flow timer engine ☐
Implement CSV import with all fields ☐
Implement Cloud API sync ☐
Add match auto-advance ☐
Implement result logging (file + API) ☐
Export results to CSV ☐
Add Device Monitor screen ☐

15. Appendix: Resources

Hardware: ESP32-C3, FSR, MPU6050, push buttons, batteries

Testing: telnet 192.168.4.1 5000, Wireshark, Serial Monitor