mychron 0.3.2

data/PROTOCOL.md

@@ -0,0 +1,848 @@
+# AiM MyChron 6 Protocol Documentation
+
+This document describes the reverse-engineered communication protocols used by AiM MyChron 6 kart data loggers. The protocols were discovered through packet capture analysis of Race Studio 3 communications.
+
+## Table of Contents
+
+1. [Device Overview](#device-overview)
+2. [UDP Discovery Protocol](#udp-discovery-protocol)
+3. [TCP Data Protocol](#tcp-data-protocol)
+4. [Session Listing](#session-listing)
+5. [File Download Protocol](#file-download-protocol)
+6. [Protocol State Machine](#protocol-state-machine)
+7. [Magic Bytes Reference](#magic-bytes-reference)
+
+---
+
+## Device Overview
+
+### Hardware Specifications
+
+| Property | Value |
+|----------|-------|
+| Device | AiM MyChron 6 Kart Data Logger |
+| WiFi Chip | Espressif ESP32 |
+| MAC OUI | `88:57:21` (Espressif) |
+| Discovery Port | UDP 36002 |
+| Data Port | TCP 2000 |
+| File Formats | `.xrz`, `.xrk`, `.hrz`, `.drk` |
+
+### WiFi Modes
+
+1. **AP Mode**: Device creates hotspot with SSID `AiM-MYC6-XXXXXX`
+2. **WLAN Mode**: Device joins existing network (recommended for this tool)
+
+### Known Test Device
+
+- Device Name: `JD-AT`
+- WiFi Config: `Wifi P2`
+- IP Address: `192.168.1.29`
+
+---
+
+## UDP Discovery Protocol
+
+**Port**: 36002
+**Purpose**: Discover MyChron devices on the local network
+
+### Request
+
+Send a 6-byte ASCII beacon:
+
+```
+Payload: "aim-ka"
+Hex:     61 69 6D 2D 6B 61
+```
+
+**Transmission Methods**:
+- **Broadcast**: Send to `255.255.255.255:36002`
+- **Unicast**: Send to specific IP address
+
+### Response
+
+The device responds with a 236-byte binary packet:
+
+```
+Offset  | Length | Field              | Description
+--------|--------|--------------------|---------------------------------
+0x00    | 4      | Magic              | 0xEC000000
+0x04    | 4      | Version            | 0x02000000
+0x08    | 4      | Device IP          | Little-endian 32-bit IP address
+0x0C    | 8      | Flags/Status       | Device state information
+0x14    | 48     | Device Name        | Null-terminated ASCII (e.g., "JD-AT")
+0x44    | 16     | Reserved           | Unknown data
+0x54    | 4      | IDN Marker         | "idn" + protocol version byte (0x01)
+0x58    | 6      | Firmware Version   | 3x uint16 LE (e.g., 56.355.437)
+0x5E    | 2      | Reserved           | Unknown data
+0x60    | 4      | Serial Number      | uint32 LE (e.g., 35016462)
+0x64    | 48     | Reserved           | Unknown data
+0x94    | 48     | WiFi Config Name   | Null-terminated ASCII (e.g., "Wifi P2")
+0xC4    | 52     | Reserved           | Unknown data (total: 236 bytes)
+```
+
+### Response Parsing
+
+```ruby
+def parse_response(data)
+  return nil unless data.length >= 236
+
+  device_name      = data[0x14, 48].unpack1('Z*').gsub(/[^[:print:]]/, '')
+  wifi_name        = data[0x94, 48].unpack1('Z*').gsub(/[^[:print:]]/, '')
+  serial_number    = data[0x60, 4].unpack1('V')  # uint32 little-endian
+  fw_v1, fw_v2, fw_v3 = data[0x58, 6].unpack('v3')  # 3x uint16 LE
+  firmware_version = "#{fw_v1}.#{fw_v2}.#{fw_v3}"
+
+  { name: device_name, wifi: wifi_name, serial: serial_number, firmware: firmware_version }
+end
+```
+
+### Implementation Notes
+
+- Use `UDPSocket` with `SO_BROADCAST` for broadcast discovery
+- Timeout: 2 seconds is sufficient for local network
+- Multiple devices may respond; collect all responses
+- Handle `EHOSTUNREACH`, `ENETUNREACH` gracefully (device may be asleep)
+
+---
+
+## TCP Data Protocol
+
+**Port**: 2000
+**Purpose**: Session listing and file downloads
+
+### Framing Structure
+
+All TCP packets use consistent binary framing with ASCII markers:
+
+```
+[Header Marker] [CMD] [00] [4-byte suffix] [Payload] [Tail Marker] [tail bytes]
+```
+
+#### Header Markers (6 bytes)
+
+| Marker | Hex | Usage |
+|--------|-----|-------|
+| `<hSTCP` | `3C 68 53 54 43 50` | Standard commands |
+| `<hSTNC` | `3C 68 53 54 4E 43` | File/data commands |
+
+#### Tail Markers (8 bytes: 5 marker + 2 checksum + 1 close)
+
+| Marker | Hex | Usage |
+|--------|-----|-------|
+| `<STCP` | `3C 53 54 43 50` | Standard commands |
+| `<STNC` | `3C 53 54 4E 43` | File/data commands |
+
+#### Tail Checksum
+
+The 2 bytes after the tail marker are a **16-bit little-endian checksum** of the payload:
+
+```
+checksum = sum_of_all_payload_bytes
+tail = [Marker] [checksum & 0xFF] [(checksum >> 8) & 0xFF] [0x3E]
+```
+
+The final byte is always `0x3E` (`>`).
+
+**Examples** (verified across all packet types):
+
+- Handshake payload `[00 00 00 00 06 08 00 00]` → sum=14 → tail `0E 00 3E`
+- Download `a_0077.xrz` → sum=1327=0x052F → tail `2F 05 3E`
+- Download `a_0065.xrz` → sum=1324=0x052C → tail `2C 05 3E`
+- List query (type 0x51) → sum=1104=0x0450 → tail `50 04 3E`
+
+### Command Bytes
+
+| Command | Value | Description |
+|---------|-------|-------------|
+| `CMD_PING` | `0x08` | Handshake/ping |
+| `CMD_DATA` | `0x40` | Data operations |
+| `CMD_LIST` | `0x44` | List operations |
+| `CMD_ACK` | `0x04` | Acknowledgment |
+
+### Connection Handshake
+
+Before any operation, a handshake must be performed:
+
+**Handshake Request** (32 bytes):
+```
+<hSTCP 08 00 00 00 00 3E    Header (12 bytes)
+00 00 00 00 06 08 00 00     Payload (8 bytes)
+<STCP 0E 00 3E              Tail (8 bytes)
+```
+
+**Handshake Response**:
+```
+<hSTCP 08 00 00 00 00 3E    (minimum expected)
+[additional data may follow]
+```
+
+---
+
+## Session Listing
+
+**Purpose**: Retrieve list of recorded sessions on device
+
+> **IMPORTANT**: Session listing requires a specific multi-step protocol sequence.
+> A single request does NOT work - the full sequence below must be followed.
+
+### Protocol Sequence (Verified 2026-02-04)
+
+The session listing protocol requires the following sequence:
+
+| Step | Type | Frame | Description |
+|------|------|-------|-------------|
+| 1 | Handshake | `<hSTCP` 0x08 | Connection handshake (28 bytes) |
+| 2 | Init | `<hSTNC` 0x10 | Initialize session (84 bytes) |
+| 3 | Date Query | `<hSTCP` 0x44 | Date range query with current date (88 bytes) |
+| 4 | ACK | `<hSTCP` 0x04 | Acknowledge date query (24 bytes) |
+| 5 | Query | `<hSTNC` 0x51 | Request session list (84 bytes) |
+| 6 | Finalize | `<hSTNC` 0x24 | Trigger CSV output (84 bytes) |
+| 7 | ACK | `<hSTCP` 0x04 | Signal ready for data (24 bytes) |
+| 8 | Response | `<hSTCPJ` 0x4A | Device sends CSV data |
+
+### Step 2: Init Request (Type 0x10)
+
+**Total Size**: 84 bytes (12 header + 64 payload + 8 tail)
+
+```
+Header: <hSTNC 40 00 00 00 00 3E
+Payload (64 bytes):
+  Offset 8-9:   0x10 0x00  (type = init)
+  Offset 10-11: 0x01 0x00  (flags)
+  Offset 16-19: 0x40 0x00 0x00 0x00
+  Offset 24-27: 0x01 0x00 0x00 0x00 (count)
+Tail: <STNC 52 00 3E
+```
+
+### Step 3: Date Query (Type 0x44)
+
+**Total Size**: 88 bytes (12 header + 68 payload + 8 tail)
+
+> **CRITICAL**: Must use current date values, not wide ranges like 2020-2030.
+> Wide date ranges return 0 sessions.
+
+```
+Header: <hSTCP 44 00 00 00 00 3E
+Payload (68 bytes):
+  Offset 12-15: year (uint32 LE)   - current year (e.g., 0xEA07 = 2026)
+  Offset 16-19: month (uint32 LE)  - current month
+  Offset 20-23: day (uint32 LE)    - 1 (first day of month)
+  Offset 24-27: param1 (uint32 LE) - 0x15 (21)
+  Offset 28-31: type (uint32 LE)   - 0x07
+  Offset 44-47: year (uint32 LE)   - same year
+  Offset 48-51: month (uint32 LE)  - same month
+  Offset 52-55: day (uint32 LE)    - 1
+  Offset 56-59: param2 (uint32 LE) - 0x16 (22)
+  Offset 60-63: type (uint32 LE)   - 0x07
+Tail: <STCP 21 02 3E
+```
+
+### Step 5: Query Request (Type 0x51)
+
+**Total Size**: 84 bytes
+
+```
+Header: <hSTNC 40 00 00 00 00 3E
+Payload (64 bytes):
+  Offset 8-9:   0x51 0x00  (type = Query)
+  Offset 10-11: 0x02 0x00  (flags)
+  Offset 24-27: 0x01 0x00 0x00 0x00 (count)
+  Offset 32-35: 0xFF 0xFF 0xFF 0xFF (all dates)
+Tail: <STNC 50 04 3E
+```
+
+### Step 6: Finalize Query (Type 0x24)
+
+**Total Size**: 84 bytes
+
+> **CRITICAL**: Type 0x51 alone does NOT return CSV. Must send Type 0x24 after.
+
+```
+Header: <hSTNC 40 00 00 00 00 3E
+Payload (64 bytes):
+  Offset 8-9:   0x24 0x00  (type = finalize)
+  Offset 10-11: 0x02 0x00  (flags)
+  Offset 24-27: 0x01 0x00 0x00 0x00 (count)
+Tail: <STNC 27 00 3E
+```
+
+### Response Format
+
+After the finalize query and ACK, the device sends `<hSTCPJ` (type 0x4A) followed by CSV:
+
+```
+<hSTCPJ....>
+name,size,date,hour,nlap,nbest,best,pilota,track_name,veicolo,campionato,venue_type,mode,trk_type,motivolap,maxvel,device,track_lat,track_lon,test_dur,...
+a_0079.xrz,2518552,25/01/2026,13:21:40,13,10,66282,,GuerreroK,,,,speed,closed,stop,1079590912,JD-AT,395074512,-7469880,822949,,,,,,
+a_0078.xrz,733838,25/01/2026,12:53:13,1,,,,GuerreroK,,,,speed,closed,stop,1072064102,JD-AT,395074512,-7469880,270928,,,,,,
+...
+```
+
+### CSV Field Definitions
+
+| Index | Field | Type | Description |
+|-------|-------|------|-------------|
+| 0 | `name` | string | Filename (e.g., `a_0052.xrz`) |
+| 1 | `size` | integer | File size in bytes |
+| 2 | `date` | string | Recording date (DD/MM/YYYY) |
+| 3 | `hour` | string | Recording time (HH:MM:SS) |
+| 4 | `nlap` | integer | Number of laps |
+| 5 | `nbest` | integer | Best lap number |
+| 6 | `best` | integer | Best lap time (milliseconds) |
+| 7 | `pilota` | string | Driver name (usually empty) |
+| 8 | `track_name` | string | Track name |
+| 9 | `veicolo` | string | Vehicle name |
+| 10 | `campionato` | string | Championship |
+| 11 | `venue_type` | string | Venue type |
+| 12 | `mode` | string | Speed type (`speed`, etc.) |
+| 13 | `trk_type` | string | Track type (`closed`, `open`) |
+| 14 | `motivolap` | string | Stop mode (`stop`, `pause`) |
+| 15 | `maxvel` | integer | Max velocity (float as int) |
+| 16 | `device` | string | Device name (e.g., `JD-AT`) |
+| 17 | `track_lat` | integer | Track latitude (scaled) |
+| 18 | `track_lon` | integer | Track longitude (scaled) |
+| 19 | `test_dur` | integer | Test duration (milliseconds) |
+
+### Parsing Sessions
+
+```ruby
+SessionInfo = Struct.new(
+  :filename, :size, :date, :time, :laps, :best_lap,
+  :best_time, :driver, :device_name, :timestamp,
+  keyword_init: true
+)
+
+def parse_csv_line(line)
+  fields = line.split(',')
+  SessionInfo.new(
+    filename:    fields[0],
+    size:        fields[1].to_i,
+    date:        fields[2],
+    time:        fields[3],
+    laps:        fields[4].to_i,
+    best_lap:    fields[5].to_i,
+    best_time:   fields[6].to_i,
+    driver:      fields[8],
+    device_name: fields[16],
+    timestamp:   fields[17].to_i
+  )
+end
+```
+
+---
+
+## File Download Protocol
+
+**Command**: `0x40` with `<hSTNC>` markers
+**Purpose**: Download session files from device
+
+### IMPORTANT: Connection State
+
+**CRITICAL**: Download MUST use a fresh connection. The session listing protocol
+(8-step sequence with init, date query, 0x51, 0x24) leaves the device in a
+different state that is incompatible with the download protocol.
+
+If you call `list_sessions` then try to download on the same connection,
+the device will return 0 bytes. **Always disconnect and reconnect before downloading.**
+
+```ruby
+# WRONG - download fails after session listing
+client.connect
+sessions = client.list_sessions
+data = client.download_session(filename)  # Returns 0 bytes!
+
+# CORRECT - use separate connections
+client.connect
+sessions = client.list_sessions
+client.disconnect
+
+client.connect  # Fresh connection
+data = client.download_session(filename)  # Works!
+```
+
+### Download Request Packet
+
+**Total Size**: 85 bytes
+
+```
+Header (12 bytes):
+  3C 68 53 54 4E 43         <hSTNC
+  40 00                     CMD_DATA, 0x00
+  00 00 00 3E               Suffix
+
+Payload (64 bytes):
+  00 00 00 00 00 00 00 00   Offset 0-7:  Zeros
+  02 00 04 00               Offset 8-11: Flags (CRITICAL - see below)
+  00 00 00 00 00 00 00 00   Offset 12-19: Zeros
+  00 00 00 00               Offset 20-23: Zeros
+  01 00 00 00               Offset 24-27: Count (1)
+  00 00 00 00               Offset 28-31: Zeros
+  [file_path, 24 bytes]     Offset 32-55: File path
+  00 00 00 00 00 00 00 00   Offset 56-63: Zeros
+
+Tail (8 bytes):
+  3C 53 54 4E 43            <STNC
+  2C 05 3E                  Tail bytes
+```
+
+### File Path Format
+
+```
+Path: "1:/mem/<filename>\0"
+Example: "1:/mem/a_0077.xrz\0"
+Max Length: 24 bytes (including null terminator)
+```
+
+### Download Flags
+
+```
+Offset 8-11: 02 00 04 00
+
+Byte 0 (0x02): Type indicator - file download
+Byte 1 (0x00): Reserved
+Byte 2 (0x04): CRITICAL - Marks file as "downloaded" in Race Studio 3
+               This flag does NOT delete the file from the device.
+               Without this flag, RS3 continues to show file as "new"
+Byte 3 (0x00): Reserved
+```
+
+### File Info Response
+
+After the download request, the device sends file metadata. Extract file size:
+
+**Pattern 1**: Look for marker `0xC0 0xFF 0x00 0x00`
+- File size is 4 bytes BEFORE this marker
+- Unpack as little-endian 32-bit unsigned integer
+
+**Pattern 2**: Look for flags `0x02 0x00 0x04 0x00`
+- File size is at offset +8 from flags
+- Unpack as little-endian 32-bit unsigned integer
+
+```ruby
+def extract_file_size(data)
+  # Pattern 1: Look for 0xC0FF0000 marker
+  idx = data.index("\xC0\xFF\x00\x00")
+  if idx && idx >= 4
+    return data[idx - 4, 4].unpack1('V')
+  end
+
+  # Pattern 2: Look for flags 0x02000400
+  idx = data.index("\x02\x00\x04\x00")
+  if idx
+    return data[idx + 8, 4].unpack1('V')
+  end
+
+  nil
+end
+```
+
+### Data Transfer with ACK Protocol
+
+**CRITICAL**: The device sends data in ~64KB chunks and waits for acknowledgment before sending more. Failure to send ACKs causes timeout and connection reset.
+
+#### ACK Packet Structure
+
+```
+Header (12 bytes):
+  3C 68 53 54 43 50         <hSTCP
+  04 00                     CMD_ACK, 0x00
+  00 00 00 3E               Suffix
+
+Payload (4 bytes):
+  [counter_low] [counter_high] [seq_low] [seq_high]
+
+Tail (8 bytes):
+  3C 53 54 43 50            <STCP
+  [tail_byte] 01 3E
+```
+
+#### ACK Counter Mechanics
+
+```
+Initial counter: 0xFFC0
+Decrement:       0x40 per ACK
+Sequence:        Starts at 0, increments by 1 per ACK
+
+Counter progression:
+  ACK #0: 0xFFC0
+  ACK #1: 0xFF80
+  ACK #2: 0xFF40
+  ACK #3: 0xFF00
+  ACK #4: 0xFEC0  (high byte wraps)
+  ACK #5: 0xFE80
+  ...
+
+Tail byte calculation:
+  high_byte_drops = 0xFF - counter_high
+  tail_byte = (counter_low + seq - 1 - high_byte_drops) & 0xFF
+```
+
+#### ACK Examples from Capture
+
+| ACK # | Counter | Seq | Payload | Tail |
+|-------|---------|-----|---------|------|
+| 0 | 0xFFC0 | 0 | `C0 FF 00 00` | `BF 01 3E` |
+| 1 | 0xFF80 | 1 | `80 FF 01 00` | `80 01 3E` |
+| 2 | 0xFF40 | 2 | `40 FF 02 00` | `41 01 3E` |
+| 3 | 0xFF00 | 3 | `00 FF 03 00` | `02 01 3E` |
+| 4 | 0xFEC0 | 4 | `C0 FE 04 00` | `C2 01 3E` |
+| 5 | 0xFE80 | 5 | `80 FE 05 00` | `83 01 3E` |
+
+#### Building ACK Packets
+
+```ruby
+def build_ack_packet(chunk_number)
+  # Calculate counter (starts at 0xFFC0, decrements by 0x40)
+  counter = 0xFFC0 - (chunk_number * 0x40)
+  counter_low = counter & 0xFF
+  counter_high = (counter >> 8) & 0xFF
+
+  # Sequence number
+  seq_low = chunk_number & 0xFF
+  seq_high = (chunk_number >> 8) & 0xFF
+
+  # Calculate tail byte
+  high_byte_drops = 0xFF - counter_high
+  tail_byte = (counter_low + chunk_number - 1 - high_byte_drops) & 0xFF
+
+  # Build packet
+  header = "<hSTCP\x04\x00\x00\x00\x00\x3E"
+  payload = [counter_low, counter_high, seq_low, seq_high].pack('CCCC')
+  tail = "<STCP" + [tail_byte, 0x01, 0x3E].pack('CCC')
+
+  header + payload + tail
+end
+```
+
+### Data Reception Algorithm
+
+```ruby
+def download_file(socket, filename)
+  file_size = receive_file_info(socket)
+  return nil unless file_size
+
+  data = ""
+  chunk_number = 0
+  bytes_since_ack = 0
+
+  # Send initial ACK
+  socket.write(build_ack_packet(chunk_number))
+  chunk_number += 1
+
+  while data.length < file_size
+    chunk = socket.recv_nonblock(65536) rescue nil
+
+    if chunk && !chunk.empty?
+      # Strip protocol markers (16-byte data frame headers + 8-byte tails)
+      clean_data = strip_markers(chunk)
+      data << clean_data
+      bytes_since_ack += clean_data.length
+
+      # Send ACK every ~64KB
+      if bytes_since_ack >= 65536
+        socket.write(build_ack_packet(chunk_number))
+        chunk_number += 1
+        bytes_since_ack = 0
+      end
+    else
+      # No data - send ACK if pending
+      if bytes_since_ack > 0
+        socket.write(build_ack_packet(chunk_number))
+        chunk_number += 1
+        bytes_since_ack = 0
+      end
+    end
+  end
+
+  data
+end
+```
+
+### Marker Stripping
+
+Remove protocol overhead from received data.
+
+**IMPORTANT**: Data frame headers during download are **16 bytes**, not 12.
+The standard 12-byte header is followed by a 4-byte counter field:
+
+```text
+Data frame header (16 bytes):
+  <hSTCP (6) + cmd (1) + flag (1) + suffix (4) + counter (4)
+
+  Counter values:
+  - 00 00 00 00 for the initial frame
+  - C0 FF 00 00 after chunk 0 ACK (counter = 0xFFC0)
+  - 80 FF 01 00 after chunk 1 ACK (counter = 0xFF80)
+  - etc.
+
+Each ~65KB download chunk structure:
+  16-byte header + ~65,472 bytes data + 8-byte tail = 65,496 bytes
+```
+
+```ruby
+def strip_markers(data)
+  result = data.dup
+
+  # Remove header markers (16 bytes each for data frames)
+  while (idx = result.index("<hSTCP"))
+    result.slice!(idx, 16)
+  end
+  while (idx = result.index("<hSTNC"))
+    result.slice!(idx, 16)
+  end
+
+  # Remove tail markers (8 bytes each)
+  while (idx = result.index("<STCP"))
+    result.slice!(idx, 8)
+  end
+  while (idx = result.index("<STNC"))
+    result.slice!(idx, 8)
+  end
+
+  result
+end
+```
+
+---
+
+## Protocol State Machine
+
+```
+                              ┌─────────────┐
+                              │    START    │
+                              └──────┬──────┘
+                                     │
+                                     ▼
+                          ┌──────────────────┐
+                          │ TCP Connect :2000│
+                          └────────┬─────────┘
+                                   │
+                                   ▼
+                          ┌──────────────────┐
+                          │ Send Handshake   │
+                          │ <hSTCP 08 00...> │
+                          └────────┬─────────┘
+                                   │
+                                   ▼
+                          ┌──────────────────┐
+                          │ Recv Handshake   │
+                          │ Response         │
+                          └────────┬─────────┘
+                                   │
+                  ┌────────────────┴────────────────┐
+                  │                                 │
+                  ▼                                 ▼
+         ┌────────────────┐                ┌────────────────┐
+         │ LIST SESSIONS  │                │ DOWNLOAD FILE  │
+         └───────┬────────┘                └───────┬────────┘
+                 │                                 │
+                 ▼                                 ▼
+         ┌────────────────┐                ┌────────────────┐
+         │ Send List Req  │                │ Send Download  │
+         │ <hSTNC 40 00..>│                │ Request        │
+         └───────┬────────┘                └───────┬────────┘
+                 │                                 │
+                 ▼                                 ▼
+         ┌────────────────┐                ┌────────────────┐
+         │ Recv CSV Data  │                │ Recv File Info │
+         │ (in <STNC>)    │                │ (extract size) │
+         └───────┬────────┘                └───────┬────────┘
+                 │                                 │
+                 ▼                                 ▼
+         ┌────────────────┐                ┌────────────────┐
+         │ Parse Sessions │                │ Send ACK #0    │
+         └───────┬────────┘                └───────┬────────┘
+                 │                                 │
+                 │                                 ▼
+                 │                         ┌────────────────┐
+                 │                    ┌───▶│ Recv Data Chunk│
+                 │                    │    └───────┬────────┘
+                 │                    │            │
+                 │                    │            ▼
+                 │                    │    ┌────────────────┐
+                 │                    │    │ Strip Markers  │
+                 │                    │    │ Accumulate Data│
+                 │                    │    └───────┬────────┘
+                 │                    │            │
+                 │                    │            ▼
+                 │                    │    ┌────────────────┐
+                 │                    │    │ >= 64KB chunk? │
+                 │                    │    └───────┬────────┘
+                 │                    │            │
+                 │                    │      Yes   │   No
+                 │                    │    ┌───────┴───────┐
+                 │                    │    ▼               │
+                 │                    │ ┌────────────────┐ │
+                 │                    │ │ Send ACK #N    │ │
+                 │                    │ └───────┬────────┘ │
+                 │                    │         │          │
+                 │                    │    ┌────┴──────────┘
+                 │                    │    ▼
+                 │                    │ ┌────────────────┐
+                 │                    │ │ All data recv? │
+                 │                    │ └───────┬────────┘
+                 │                    │         │
+                 │                    │   No    │   Yes
+                 │                    └─────────┘    │
+                 │                                   ▼
+                 │                          ┌────────────────┐
+                 │                          │ Verify Size    │
+                 │                          └───────┬────────┘
+                 │                                  │
+                 └──────────────┬───────────────────┘
+                                │
+                                ▼
+                       ┌────────────────┐
+                       │ Close Socket   │
+                       └───────┬────────┘
+                               │
+                               ▼
+                       ┌────────────────┐
+                       │     END        │
+                       └────────────────┘
+```
+
+---
+
+## Magic Bytes Reference
+
+### Protocol Headers
+
+| Marker | ASCII | Hex | Length | Usage |
+|--------|-------|-----|--------|-------|
+| Header Standard | `<hSTCP` | `3C 68 53 54 43 50` | 6 | Handshake, ACK |
+| Header Data | `<hSTNC` | `3C 68 53 54 4E 43` | 6 | List, Download |
+| Tail Standard | `<STCP` | `3C 53 54 43 50` | 5 | Handshake, ACK |
+| Tail Data | `<STNC` | `3C 53 54 4E 43` | 5 | List, Download |
+
+### UDP Discovery
+
+| Name | Value | Notes |
+|------|-------|-------|
+| Beacon | `aim-ka` | 6 bytes ASCII |
+| Port | `36002` | UDP |
+| Response Size | `236` | bytes |
+| Device Name Offset | `0x14` | 48 bytes max |
+| Firmware Version Offset | `0x58` | 3x uint16 LE |
+| Serial Number Offset | `0x60` | uint32 LE |
+| WiFi Name Offset | `0x94` | 48 bytes max |
+
+### TCP Commands
+
+| Command | Value | Description |
+|---------|-------|-------------|
+| Ping/Handshake | `0x08` | Connection handshake |
+| Data | `0x40` | Data operations |
+| List | `0x44` | List operations |
+| ACK | `0x04` | Data acknowledgment |
+
+### Download Flags
+
+| Offset | Value | Purpose |
+|--------|-------|---------|
+| 8-11 | `02 00 04 00` | Standard download, mark as downloaded |
+
+### ACK Constants
+
+| Name | Value | Notes |
+|------|-------|-------|
+| Initial Counter | `0xFFC0` | Decrements by 0x40 |
+| Chunk Size | `65536` | ~64KB triggers ACK |
+| Tail Byte 2 | `0x01` | Always 0x01 |
+| Tail Byte 3 | `0x3E` | Always 0x3E |
+
+---
+
+## Error Handling
+
+### Connection Errors
+
+| Error | Cause | Recovery |
+|-------|-------|----------|
+| `EHOSTUNREACH` | Device in sleep mode | Wake device, retry |
+| `ECONNREFUSED` | Port 2000 not responding | Check device state |
+| `ENETUNREACH` | Network unreachable | Check WiFi connection |
+| `ETIMEDOUT` | Connection timeout | Increase timeout, retry |
+| `ECONNRESET` | Connection reset by peer | Missing ACK, restart |
+
+### Protocol Errors
+
+| Error | Cause | Recovery |
+|-------|-------|----------|
+| Invalid handshake | Wrong marker in response | Reconnect |
+| File size 0 | Parse failure | Try alternate pattern |
+| Incomplete download | Missing ACKs | Implement proper ACK |
+| CSV parse error | Unexpected format | Skip malformed lines |
+
+---
+
+## Timeouts
+
+| Operation | Timeout | Notes |
+|-----------|---------|-------|
+| UDP Discovery | 2 seconds | Per broadcast |
+| TCP Connect | 5 seconds | Initial connection |
+| Read Timeout | 30 seconds | Per recv operation |
+| Total Transfer | 300 seconds | 5 minutes max |
+| ACK Response | 1-2 seconds | Device wait time |
+
+---
+
+## Appendix: Packet Captures
+
+### Handshake Exchange
+
+**Client Request:**
+```
+3C 68 53 54 43 50 08 00 00 00 00 3E    <hSTCP....>
+00 00 00 00 06 08 00 00                ........
+3C 53 54 43 50 0E 00 3E                <STCP..>
+```
+
+**Device Response:**
+```
+3C 68 53 54 43 50 08 00 00 00 00 3E    <hSTCP....>
+[additional bytes...]
+```
+
+### Session List Request
+
+**Client Request:**
+```
+3C 68 53 54 4E 43 40 00 00 00 00 3E    <hSTNC@...>
+00 00 00 00 00 00 00 00 07 00 01 00    ............
+00 00 00 00 00 00 00 00 00 00 00 00    ............
+00 00 01 00 00 00 00 00 00 00 00 00    ............
+00 00 00 00 00 00 00 00 00 00 00 00    ............
+00 00 00 00 00 00 00 00 00 00 00 00    ............
+00 00 00 00                            ....
+3C 53 54 4E 43 09 00 3E                <STNC..>
+```
+
+### Download Request (file: a_0077.xrz)
+
+**Client Request:**
+```
+3C 68 53 54 4E 43 40 00 00 00 00 3E    <hSTNC@...>
+00 00 00 00 00 00 00 00 02 00 04 00    ............
+00 00 00 00 00 00 00 00 00 00 00 00    ............
+01 00 00 00 00 00 00 00                ........
+31 3A 2F 6D 65 6D 2F 61 5F 30 30 37    1:/mem/a_007
+37 2E 78 72 7A 00 00 00 00 00 00 00    7.xrz.......
+00 00 00 00 00 00 00 00                ........
+3C 53 54 4E 43 2C 05 3E                <STNC,.>
+```
+
+### ACK Packet (chunk 0)
+
+**Client ACK:**
+```
+3C 68 53 54 43 50 04 00 00 00 00 3E    <hSTCP....>
+C0 FF 00 00                            ....
+3C 53 54 43 50 BF 01 3E                <STCP..>
+```
+
+---
+
+*Documentation generated from reverse engineering of Race Studio 3 protocol communications.*
+*Last updated: 2026-03-24*