mychron 0.3.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: de882c005d17be9699b196963985e0943f5ee13772d93c66b060856ad51e10ed
+  data.tar.gz: da81ac312aa45a6cac77b20efef3496d83e5d717da38838cbf8ba1157965c459
+SHA512:
+  metadata.gz: 432ef0662a41526af7ea02b91e9c86ae4783918ed818f2e3e81557662cea4bfdfc5d9a39ca6815bda829b5228ac71b845ef4c31c1cbbc7056f467f4abf604b57
+  data.tar.gz: '089f0204b3ebf293894d235b445ceff31d0fbf046f35f72108bda0e21b5fc5c07c2149067cfa326dd98bf54f4e5a1cbbed2952feab5f6654114924e731af210c'

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,539 @@
+# MyChron 6 Implementation Notes
+
+This document captures everything learned during reverse engineering and implementation.
+Use this as the authoritative reference when working on this gem.
+
+**Last updated: 2026-02-07 (v0.3.1)**
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Critical Discoveries](#critical-discoveries)
+3. [UDP Discovery](#udp-discovery)
+4. [TCP Packet Format](#tcp-packet-format)
+5. [Session Listing Protocol](#session-listing-protocol)
+6. [File Download Protocol](#file-download-protocol)
+7. [Gotchas and Pitfalls](#gotchas-and-pitfalls)
+8. [Data Structures](#data-structures)
+9. [Performance](#performance)
+10. [Debugging Guide](#debugging-guide)
+
+---
+
+## Overview
+
+### What This Library Does
+
+1. **Discovers** MyChron 6 devices on the local network via UDP broadcast
+2. **Lists** recorded sessions (lap data files) stored on the device
+3. **Downloads** session files (`.xrz`, `.hrz`) from the device
+
+### Network Architecture
+
+```
+Ruby Client                         MyChron 6 (ESP32)
+    │                                     │
+    │── UDP 36002: "aim-ka" ────────────▶│
+    │◀── 236-byte device info ───────────│
+    │                                     │
+    │══ TCP 2000: session listing ═══════│  (8-step protocol)
+    │══ TCP 2000: file download  ════════│  (fresh connection required)
+```
+
+### Core Constants
+
+```ruby
+DISCOVERY_PORT = 36002      # UDP
+DATA_PORT = 2000            # TCP
+BEACON = "aim-ka"           # 6 bytes
+RESPONSE_SIZE = 236         # bytes (UDP response)
+```
+
+---
+
+## Critical Discoveries
+
+These are the hardest-won findings. If you forget everything else, remember these:
+
+### 1. Tail Bytes are a 16-bit Payload Checksum (v0.3.0)
+
+**THE most important discovery.** Every packet's tail bytes are NOT constants - they
+are a checksum calculated from the payload bytes.
+
+```
+checksum = sum_of_all_payload_bytes  (as a simple integer sum)
+tail = [tail_marker] [checksum & 0xFF] [(checksum >> 8) & 0xFF] [0x3E]
+```
+
+This was hardcoded to `0x2F 0x05` in v0.2.1, which happened to be the correct
+checksum for `a_0077.xrz` only. ALL other files silently failed because the device
+rejects packets with wrong checksums without any error response.
+
+**Verified across ALL packet types:**
+- Handshake: payload sum=14 -> tail `0E 00 3E`
+- Init (0x10): payload sum=82 -> tail `52 00 3E`
+- List query (0x51): payload sum=1104 -> tail `50 04 3E`
+- Finalize (0x24): payload sum=39 -> tail `27 00 3E`
+- Download a_0077.xrz: payload sum=1327 -> tail `2F 05 3E`
+- Download a_0065.xrz: payload sum=1324 -> tail `2C 05 3E`
+- Data ACK #0: payload sum=447 -> tail `BF 01 3E`
+
+### 2. Session Listing is an 8-Step Protocol (v0.2.0)
+
+NOT a single request/response. The full sequence is:
+
+```
+1. Handshake (CMD 0x08)
+2. Init request (type 0x10 in STNC frame)
+3. Date query (CMD 0x44 with type 0x07)
+4. ACK
+5. List query (type 0x51 - requests CSV)
+6. Finalize query (type 0x24 - triggers CSV output)
+7. ACK
+8. Receive CSV data
+```
+
+Skipping any step = empty results.
+
+### 3. Date Query Requires Current Date (v0.2.0)
+
+The date query (step 3) uses the current year/month. Using a wide range like
+2020-2030 returns 0 sessions. RS3 always uses the first day of the current month.
+
+### 4. Downloads Need Fresh Connections (v0.2.1)
+
+Session listing leaves the device in a state incompatible with downloads.
+**Always disconnect and reconnect before downloading a file.**
+
+### 5. File Info Response Has TWO Blocks (v0.2.1)
+
+The download response contains two 84-byte info blocks:
+- Block 1: has the file path but size field is zeros
+- Block 2: has the file path AND the actual file size at offset +8 from flags
+
+Parse the SECOND `02 00 04 00` occurrence to find the size.
+
+### 6. Device IP Changes via DHCP
+
+The device gets a different IP each time it connects to the network.
+Known IPs so far: .29, .30, .23. **Always discover via UDP broadcast first.**
+
+### 7. Device Gets Stuck on Incomplete Downloads
+
+If a download starts but doesn't complete (e.g., wrong checksum, network error),
+the device enters "DATA DOWNLOAD" state and won't respond to new requests.
+Race Studio 3 can unstick it by connecting.
+
+---
+
+## UDP Discovery
+
+### Protocol
+
+1. Send `aim-ka` (6 bytes) to UDP port 36002 (broadcast or unicast)
+2. Device responds with 236 bytes
+
+### Response Layout
+
+```
+Offset 0x14 (20):  Device Name (48 bytes, null-terminated)
+Offset 0x58 (88):  Firmware Version (3x uint16 LE: major.minor.patch)
+Offset 0x60 (96):  Serial Number (uint32 LE)
+Offset 0x94 (148): WiFi Config Name (48 bytes, null-terminated)
+```
+
+### Implementation
+
+```ruby
+socket = UDPSocket.new
+socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_BROADCAST, true)
+socket.bind("0.0.0.0", 0)
+socket.send("aim-ka", 0, "255.255.255.255", 36002)
+
+# Wait for response
+if IO.select([socket], nil, nil, timeout)
+  data, addr = socket.recvfrom(512)
+  # data.length should be 236
+  # addr[3] is the device IP
+end
+```
+
+---
+
+## TCP Packet Format
+
+### Structure
+
+```
+[Header: 6 bytes] [CMD: 1] [0x00: 1] [Suffix: 4] [Payload: N] [Tail: 5] [Checksum: 2] [0x3E: 1]
+```
+
+Total overhead: 6 + 2 + 4 + 5 + 2 + 1 = 20 bytes per packet
+
+### Header Types
+
+| Type | Marker | Hex | Usage |
+|------|--------|-----|-------|
+| STCP | `<hSTCP` | `3C 68 53 54 43 50` | Handshake, ACK |
+| STNC | `<hSTNC` | `3C 68 53 54 4E 43` | Init, queries, downloads |
+
+### Tail Types
+
+| Type | Marker | Hex |
+|------|--------|-----|
+| STCP | `<STCP` | `3C 53 54 43 50` |
+| STNC | `<STNC` | `3C 53 54 4E 43` |
+
+### Checksum Calculation (CRITICAL)
+
+```ruby
+def build_packet(header_marker, cmd, suffix, payload, tail_marker)
+  checksum = payload.sum  # Simple sum of all byte values
+  packet = header_marker.dup
+  packet << cmd.chr << 0x00.chr
+  suffix.each { |b| packet << b.chr }
+  payload.each { |b| packet << b.chr }
+  packet << tail_marker
+  packet << (checksum & 0xFF).chr          # Low byte
+  packet << ((checksum >> 8) & 0xFF).chr   # High byte
+  packet << 0x3E.chr                       # Always '>'
+  packet
+end
+```
+
+### Handshake (Required Before Everything)
+
+```
+Request:  <hSTCP 08 00 [00 00 00 3E] [00 00 00 00 06 08 00 00] <STCP [0E 00 3E]
+Response: <hSTCP 08 00 00 00 00 3E (12 bytes min)
+          + additional data: [00 00 00 00 06 09 00 00] <STCP [0F 00 3E]
+```
+
+### ACK Packet
+
+```
+Simple: <hSTCP 04 00 [00 00 00 3E] [00 00 00 00] <STCP [00 00 3E]
+```
+
+---
+
+## Session Listing Protocol
+
+### Full 8-Step Sequence
+
+**Step 1-2: Handshake** (see above)
+
+**Step 3: Init Request (type 0x10)**
+```
+Frame: <hSTNC 40 00 [00 00 00 3E] [64-byte payload] <STNC [checksum] 3E
+Payload offsets:
+  8-9:   0x10 0x00  (type = init)
+  10-11: 0x01 0x00  (flags)
+  16-19: 0x40 0x00 0x00 0x00
+  24-27: 0x01 0x00 0x00 0x00  (count)
+```
+
+**Step 4: Date Query (CMD 0x44)**
+```
+Frame: <hSTCP 44 00 [00 00 00 3E] [68-byte payload] <STCP [checksum] 3E
+Payload offsets:
+  12-15: year (uint32 LE, current year)
+  16-19: month (uint32 LE, current month)
+  20-23: day (uint32 LE, always 1)
+  24-27: 0x15 (constant param1)
+  28-31: 0x07 (type = session list)
+  44-47: year (repeat)
+  48-51: month (repeat)
+  52-55: day (repeat)
+  56-59: 0x16 (constant param2 = param1 + 1)
+  60-63: 0x07 (type repeat)
+```
+
+**Step 5: ACK**
+
+**Step 6: List Query (type 0x51)**
+```
+Frame: <hSTNC 40 00 [00 00 00 3E] [64-byte payload] <STNC [checksum] 3E
+Payload offsets:
+  8-9:   0x51 0x00  (type = query)
+  10-11: 0x02 0x00  (flags)
+  24-27: 0x01 0x00 0x00 0x00  (count)
+  32-35: 0xFF 0xFF 0xFF 0xFF  (all dates)
+```
+
+**Step 7: Finalize Query (type 0x24)**
+```
+Frame: <hSTNC 40 00 [00 00 00 3E] [64-byte payload] <STNC [checksum] 3E
+Payload offsets:
+  8-9:   0x24 0x00  (type = finalize)
+  10-11: 0x02 0x00  (flags)
+  24-27: 0x01 0x00 0x00 0x00  (count)
+```
+
+**Step 8: ACK + Receive CSV**
+
+### CSV Format
+
+```
+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,3,56789,Driver1,,,,,,,,0,JD-AT,0,0,0,...
+```
+
+Field indices: 0=name, 1=size, 2=date, 3=hour, 4=nlap, 5=nbest, 6=best(ms),
+7=pilota, 12=mode, 13=trk_type, 14=motivolap, 16=device, 17=lat, 18=lon, 19=dur
+
+---
+
+## File Download Protocol
+
+### Connection Requirements
+
+- MUST use a fresh TCP connection (disconnect after session listing)
+- MUST send handshake before download request
+- Device accepts only ONE concurrent connection
+
+### Download Request
+
+```
+Frame: <hSTNC 40 00 [00 00 00 3E] [64-byte payload] <STNC [checksum] 3E
+
+Payload:
+  Offset 8-11:  02 00 04 00  (flags - 0x04 marks as "downloaded" in RS3)
+  Offset 24-27: 01 00 00 00  (count)
+  Offset 32-55: "1:/mem/<filename>" (null-terminated, max 24 bytes)
+```
+
+The checksum varies per filename since the path bytes are part of the payload.
+
+### File Info Response (168 bytes)
+
+Two 84-byte blocks:
+
+```
+Block 1 (size field = 0):
+  [12-byte header] [8 zeros] [02 00 04 00] [00 00 00 00] [C0 FF 00 00] ... [path] [8-byte tail]
+
+Block 2 (has actual size):
+  [12-byte header] [8 zeros] [02 00 04 00] [00 00 00 00] [size: 4 bytes LE] [C0 FF 00 00] ... [path] [8-byte tail]
+```
+
+To extract size: find SECOND occurrence of `02 00 04 00`, read 4 bytes at offset +8.
+
+### Data Transfer with ACKs
+
+After sending initial ACK, device streams data in ~64KB chunks with protocol markers
+interspersed. Send a data ACK every ~64KB to keep the transfer going.
+
+**Data ACK format:**
+```
+<hSTCP 04 00 [00 00 00 3E] [counter_lo, counter_hi, seq_lo, 0x00] <STCP [checksum] 3E
+```
+
+Counter starts at `0xFFC0`, decrements by `0x40` per ACK:
+- ACK 0: counter=0xFFC0, payload=[C0 FF 00 00]
+- ACK 1: counter=0xFF80, payload=[80 FF 01 00]
+- ACK 2: counter=0xFF40, payload=[40 FF 02 00]
+- etc.
+
+The tail checksum is auto-calculated from the 4-byte payload, same as all other packets.
+
+### Marker Stripping
+
+Data stream contains `<hSTCP` headers (**16 bytes**) and `<STCP` tails
+(8 bytes) that must be stripped to get the raw file data.
+
+**CRITICAL**: Data frame headers during download are **16 bytes, not 12**.
+The standard 12-byte header is followed by a 4-byte counter/sequence field:
+
+```text
+Data frame header (16 bytes):
+  <hSTCP (6) + cmd (1) + 0xFF (1) + suffix (4) + counter (4)
+
+  Counter values:
+  - 00 00 00 00 for the initial data frame
+  - C0 FF 00 00 after chunk 0 ACK (counter echoes send_data_ack values)
+  - 80 FF 01 00 after chunk 1 ACK
+  - etc.
+```
+
+Each ~65KB download chunk has this exact structure (confirmed by raw TCP capture):
+- **16-byte header** + **65,472 bytes file data** + **8-byte tail** = 65,496 bytes total
+- One frame per chunk, no intermediate frames
+- No separate ACK response packets (counter is embedded in the header)
+
+---
+
+## Gotchas and Pitfalls
+
+### Things That Silently Fail (No Error Response)
+
+1. **Wrong checksum** -> device returns 0 bytes (discovered v0.3.0)
+2. **Wrong date range in query** -> device returns 0 sessions (discovered v0.2.0)
+3. **Downloading on reused connection** -> device returns 0 bytes (discovered v0.2.1)
+4. **Incomplete download** -> device gets stuck in DATA DOWNLOAD state
+5. **Wrong header strip size** -> correct file size but corrupted content (discovered v0.3.1)
+
+### Things That Must Be Exact
+
+1. Payload checksum in tail bytes
+2. `1:/mem/` prefix for file paths
+3. Current date (year/month) in date query
+4. Handshake before every operation
+5. Fresh connection for downloads
+
+### Common Mistakes
+
+- Using wide date ranges (2020-2030) instead of current month
+- Expecting CSV from a single request (need 8-step sequence)
+- Hardcoding tail bytes instead of calculating checksums
+- Reusing a connection after session listing for downloads
+- Not sending periodic ACKs during data transfer (~64KB intervals)
+- Looking at the FIRST info block for file size (it's in the SECOND)
+
+### Device Behavior
+
+- **DHCP**: IP address changes every connection (always discover first)
+- **Single client**: Only one TCP connection at a time
+- **Stuck state**: Incomplete downloads leave device stuck (RS3 can recover)
+- **Sleep mode**: Device must be awake for UDP discovery
+- **File marking**: Flag 0x04 marks files as "downloaded" in RS3 UI (doesn't delete)
+- **Download speed**: ~23-34 KB/s (ESP32 WiFi limitation)
+
+---
+
+## Data Structures
+
+### SessionInfo (from CSV)
+
+```ruby
+SessionInfo = Struct.new(
+  :filename,     # "a_0077.xrz"
+  :size,         # 2224965 (bytes)
+  :date,         # "25/01/2026"
+  :time,         # "10:45:25"
+  :laps,         # 10
+  :best_lap,     # 3 (lap number)
+  :best_time,    # 56789 (milliseconds)
+  :driver,       # "Driver1"
+  :speed_type,   # field 12
+  :status,       # field 13
+  :stop_mode,    # field 14
+  :timestamp,    # field 15
+  :device_name,  # "JD-AT"
+  :longitude,    # field 17
+  :latitude,     # field 18
+  :duration,     # field 19 (milliseconds)
+  keyword_init: true
+)
+```
+
+### DeviceInfo (from UDP)
+
+```ruby
+DeviceInfo = Struct.new(
+  :ip,                # "192.168.1.23"
+  :device_name,       # "JD-AT"
+  :wifi_name,         # "Wifi P2"
+  :serial_number,     # 35016462
+  :firmware_version,  # "56.355.437"
+  keyword_init: true
+)
+```
+
+---
+
+## Performance
+
+### Measured (Real Device, v0.3.0)
+
+| Operation | Time | Notes |
+|-----------|------|-------|
+| UDP Discovery | <1s | Broadcast or unicast |
+| Session Listing | ~3s | 60 sessions, 8-step protocol |
+| Download 28KB | 0.8s | 34 KB/s |
+| Download 45KB | 1.3s | 34 KB/s |
+| Download 709KB | 30.7s | 23 KB/s |
+| Download 2.2MB | ~90s | 23 KB/s |
+| Download 2.5MB | ~106s | 23 KB/s |
+
+Small files download faster (~34 KB/s), large files settle at ~23 KB/s.
+
+### Recommendations
+
+- Use background jobs for downloads >500KB
+- Cache session lists (refresh on demand)
+- Always discover device IP first (DHCP changes it)
+- Show progress callbacks for files >100KB
+
+---
+
+## Debugging Guide
+
+### Enable Logging
+
+```ruby
+require 'logger'
+MyChron::Logging.logger = Logger.new(STDOUT).tap do |l|
+  l.level = Logger::DEBUG
+  l.formatter = proc { |sev, time, _, msg| "[#{sev}] #{msg}\n" }
+end
+```
+
+### Compare Packet Hex Dumps
+
+```ruby
+packet = build_nc_packet(...)
+puts packet.bytes.map { |b| format('%02X', b) }.join(' ')
+# Compare with pcap capture in Wireshark
+```
+
+### Verify Checksum
+
+```ruby
+payload = [...]  # Your payload array
+sum = payload.sum
+puts "Checksum: 0x#{format('%04X', sum)} -> tail bytes: #{format('%02X', sum & 0xFF)} #{format('%02X', (sum >> 8) & 0xFF)}"
+```
+
+### Test Single Download
+
+```ruby
+ruby -I lib -r mychron -e "
+  MyChron::Logging.logger = Logger.new(STDOUT)
+  device = MyChron.device('192.168.1.23')
+  data = device.download('a_0065.xrz')
+  puts data.bytesize
+"
+```
+
+### pcap Captures
+
+Reference captures in project root:
+- `rs3_session_list.pcap` - Full session listing sequence
+- `download_capture.pcap` - Download of a_0077.xrz (tail 0x2F 0x05)
+- `download_capture2.pcap` - Download of a_0065.xrz (tail 0x2C 0x05)
+
+Open with: `tcpdump -r capture.pcap -X` or Wireshark
+
+### Capture New Traffic
+
+```bash
+sudo tcpdump -i any host <device_ip> -w capture.pcap -s 0
+```
+
+---
+
+## Version History of Discoveries
+
+| Version | Date | Discovery |
+|---------|------|-----------|
+| v0.1.0 | Jan 2026 | UDP discovery, basic TCP framing |
+| v0.2.0 | Feb 4, 2026 | 8-step session listing, date query, CSV parsing |
+| v0.2.1 | Feb 4, 2026 | Fresh connections for downloads, dual info blocks, read_available fix |
+| v0.3.0 | Feb 7, 2026 | **Tail byte checksum** - all files downloadable |
+| v0.3.1 | Feb 7, 2026 | **16-byte data frame headers** - byte-identical downloads |
+
+---
+
+*This document contains everything needed to rebuild the MyChron client from scratch.*
+*Last updated: 2026-03-24*

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugeniu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.