mychron 0.3.2

data/lib/mychron/protocol/client.rb

@@ -0,0 +1,946 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module MyChron
+  module Protocol
+    # TCP Protocol client for communicating with MyChron devices
+    # Uses custom binary protocol with <hSTCP>/<STCP> framing on port 2000
+    class Client
+      include Logging
+
+      DATA_PORT = 2000
+      CONNECT_TIMEOUT = 5.0
+      READ_TIMEOUT = 30.0
+
+      # Protocol markers
+      HEADER_MARKER = "<hSTCP"
+      TAIL_MARKER = "<STCP"
+      HEADER_NC = "<hSTNC"
+      TAIL_NC = "<STNC"
+
+      # Command types (byte after header)
+      CMD_PING = 0x08
+      CMD_LIST = 0x44
+      CMD_DATA = 0x40
+
+      # Session info parsed from CSV
+      SessionInfo = Struct.new(
+        :filename,
+        :size,
+        :date,
+        :time,
+        :laps,
+        :best_lap,
+        :best_time,
+        :driver,
+        :speed_type,
+        :status,
+        :stop_mode,
+        :timestamp,
+        :device_name,
+        :longitude,
+        :latitude,
+        :duration,
+        keyword_init: true
+      )
+
+      def initialize(host, port: DATA_PORT)
+        @host = host
+        @port = port
+        @socket = nil
+      end
+
+      # Connect to device
+      def connect
+        log_debug( "Connecting to #{@host}:#{@port}")
+        @socket = Socket.new(Socket::AF_INET, Socket::SOCK_STREAM)
+        @socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, true)
+
+        addr = Socket.sockaddr_in(@port, @host)
+        begin
+          @socket.connect_nonblock(addr)
+        rescue IO::WaitWritable
+          IO.select(nil, [@socket], nil, CONNECT_TIMEOUT)
+          begin
+            @socket.connect_nonblock(addr)
+          rescue Errno::EISCONN
+            # Connected
+          rescue Errno::EALREADY, Errno::EINPROGRESS
+            raise ConnectionError, "Connection timeout to #{@host}:#{@port}"
+          end
+        rescue Errno::EHOSTUNREACH
+          raise ConnectionError, "No route to host #{@host} - device may be in sleep mode, try waking it"
+        rescue Errno::ECONNREFUSED
+          raise ConnectionError, "Connection refused by #{@host}:#{@port}"
+        rescue Errno::ENETUNREACH
+          raise ConnectionError, "Network unreachable for #{@host}"
+        end
+
+        log_info( "Connected to #{@host}:#{@port}")
+        true
+      end
+
+      # Disconnect from device
+      def disconnect
+        return unless @socket
+
+        @socket.close rescue nil
+        @socket = nil
+        log_debug( "Disconnected from #{@host}")
+      end
+
+      # List sessions on device
+      # Returns array of SessionInfo
+      #
+      # Protocol sequence (from RS3 capture analysis):
+      # 1. Handshake (type 0x08)
+      # 2. Init request (type 0x10 in STNC frame)
+      # 3. Date query (type 0x44/'D' with type 0x07) - initializes session list
+      # 4. ACK (type 0x04)
+      # 5. Type 0x51 Query (with 0xFFFFFFFF for all dates) - requests CSV
+      # 6. Type 0x24 Query - finalizes and triggers CSV output
+      # 7. Receive CSV response
+      def list_sessions
+        ensure_connected
+
+        # Send initial handshake
+        send_handshake
+        receive_handshake_response
+
+        # Send initialization (type 0x10) - required before query
+        send_init_request
+        receive_init_response
+
+        # Send date range query (type 0x44/D) - this initializes the session list
+        send_date_query
+        receive_date_response
+
+        # Send ACK
+        send_ack
+        sleep(0.1)
+
+        # Send type 0x51 Query (requests session list CSV)
+        send_list_request
+        receive_query_response
+
+        # Send type 0x24 Query (triggers CSV output)
+        send_finalize_query
+        sleep(0.1)
+
+        # Send ACK to signal ready for CSV data
+        send_ack
+
+        # Receive CSV response
+        csv_data = receive_list_response
+
+        parse_session_csv(csv_data)
+      end
+
+      # Download a session file
+      # Returns raw file data (bytes)
+      #
+      # IMPORTANT: Download requires a fresh connection.
+      # The session listing protocol leaves the connection in a different state,
+      # so we always reconnect before downloading.
+      def download_session(filename, &progress_block)
+        # Always start with a fresh connection for downloads
+        # This is critical because session listing leaves the device in a different state
+        disconnect if @socket
+        connect
+
+        # Send handshake first
+        send_handshake
+        receive_handshake_response
+
+        # Send download request
+        file_path = "1:/mem/#{filename}"
+        send_download_request(file_path)
+
+        # Receive file info and get size
+        file_size = receive_file_info(file_path)
+        log_info( "Downloading #{filename} (#{file_size} bytes)")
+
+        # Acknowledge info
+        send_ack
+
+        # Receive file data
+        receive_file_data(file_size, &progress_block)
+      end
+
+      private
+
+      def ensure_connected
+        connect unless @socket
+      end
+
+      def send_handshake
+        # Initial handshake packet:
+        # <hSTCP 08 00 0000 003e 00000000 0608 0000 <STCP 0e 00 3e
+        packet = build_packet(CMD_PING, [0x00, 0x00, 0x00, 0x3E], [0x00, 0x00, 0x00, 0x00, 0x06, 0x08, 0x00, 0x00])
+        log_debug( "Sending handshake: #{packet.bytes.map { |b| format('%02X', b) }.join(' ')}")
+        @socket.write(packet)
+      end
+
+      def receive_handshake_response
+        # Expect: <hSTCP 08 00 0000 003e
+        response = read_bytes(12)
+        log_debug("Handshake response: #{response.bytes.map { |b| format('%02X', b) }.join(' ')}")
+
+        unless response.start_with?(HEADER_MARKER)
+          raise ProtocolError, "Invalid handshake response: expected #{HEADER_MARKER}"
+        end
+
+        # May receive follow-up data
+        sleep(0.1)
+        if IO.select([@socket], nil, nil, 0.5)
+          extra = read_available
+          log_debug("Extra handshake data: #{extra.bytes.map { |b| format('%02X', b) }.join(' ')}")
+        end
+
+        true
+      end
+
+      def send_init_request
+        # Send initialization packet (type 0x10)
+        # From RS3 capture:
+        # <hSTNC 40 00 0000 003e [64-byte payload] <STNC 52 00 3e
+        #
+        # Payload:
+        # Bytes 8-9:  0x10 0x00 (type = init)
+        # Bytes 10-11: 0x01 0x00 (flags)
+        # Bytes 16-19: 0x40 0x00 0x00 0x00
+        # Bytes 24-27: 0x01 0x00 0x00 0x00 (count)
+
+        payload = Array.new(64, 0)
+
+        # Type 0x10 (init) at offset 8
+        payload[8] = 0x10
+        payload[9] = 0x00
+
+        # Flags at offset 10
+        payload[10] = 0x01
+        payload[11] = 0x00
+
+        # Value at offset 16
+        payload[16] = 0x40
+        payload[17] = 0x00
+        payload[18] = 0x00
+        payload[19] = 0x00
+
+        # Count at offset 24
+        payload[24] = 0x01
+        payload[25] = 0x00
+        payload[26] = 0x00
+        payload[27] = 0x00
+
+        packet = build_nc_packet(0x40, [0x00, 0x00, 0x00, 0x3E], payload)
+        log_debug("Sending init request (type 0x10): #{packet.bytesize} bytes")
+        @socket.write(packet)
+      end
+
+      def receive_init_response
+        # Wait for and consume the init response
+        # Server responds with <hSTCP>@ and possibly more data
+        data = read_available(timeout: 2.0)
+        log_debug("Init response: #{data.bytesize} bytes")
+
+        # May receive multiple response packets, consume them all
+        while IO.select([@socket], nil, nil, 0.5)
+          extra = read_available(timeout: 0.5)
+          break if extra.empty?
+          data += extra
+          log_debug("Additional init data: #{extra.bytesize} bytes (total: #{data.bytesize})")
+        end
+
+        true
+      end
+
+      def send_date_query
+        # Send date range query (type 0x44/'D' with type 0x07)
+        # From RS3 capture - this is a <hSTCP>D packet (88 bytes total)
+        #
+        # CRITICAL: RS3 uses specific current date values, not wide ranges!
+        # Using wide date ranges (2020-2030) returns 0 sessions.
+        # RS3 capture shows: year=2026, month=2, day=1, params=21/22
+        #
+        # Packet structure:
+        # <hSTCP>D (8 bytes header)
+        # Header suffix: 0x00 0x00 0x00 0x3E (4 bytes)
+        # Payload (68 bytes):
+        #   0-11: zeros
+        #   12-15: year (uint32 LE) - current year
+        #   16-19: month (uint32 LE) - current month
+        #   20-23: day (uint32 LE) - first day of month
+        #   24-27: param1 (uint32 LE) - calculated value
+        #   28-31: type (uint32 LE) - 0x07 for session list
+        #   32-43: zeros
+        #   44-47: year (uint32 LE) - same year
+        #   48-51: month (uint32 LE) - same month
+        #   52-55: day (uint32 LE) - same day
+        #   56-59: param2 (uint32 LE) - param1 + 1
+        #   60-63: type (uint32 LE) - 0x07
+        #   64-67: zeros
+        # Tail: <STCP>! 0x02 0x3E (8 bytes)
+
+        # Use current date values (matching RS3 behavior)
+        now = Time.now
+        year = now.year
+        month = now.month
+        day = 1  # RS3 uses first day of month
+
+        # Params from RS3 capture: 21 and 22 (0x15 and 0x16)
+        # These appear to be constant or calculated values
+        param1 = 0x15  # 21
+        param2 = 0x16  # 22
+
+        payload = Array.new(68, 0)
+
+        # Start date block
+        payload[12..15] = [year & 0xFF, (year >> 8) & 0xFF, 0x00, 0x00]
+        payload[16..19] = [month & 0xFF, 0x00, 0x00, 0x00]
+        payload[20..23] = [day & 0xFF, 0x00, 0x00, 0x00]
+        payload[24..27] = [param1 & 0xFF, 0x00, 0x00, 0x00]
+        payload[28..31] = [0x07, 0x00, 0x00, 0x00]  # Type 0x07
+
+        # End date block (same date)
+        payload[44..47] = [year & 0xFF, (year >> 8) & 0xFF, 0x00, 0x00]
+        payload[48..51] = [month & 0xFF, 0x00, 0x00, 0x00]
+        payload[52..55] = [day & 0xFF, 0x00, 0x00, 0x00]
+        payload[56..59] = [param2 & 0xFF, 0x00, 0x00, 0x00]
+        payload[60..63] = [0x07, 0x00, 0x00, 0x00]  # Type 0x07
+
+        # Build packet with STCP header and auto-calculated checksum
+        packet = build_packet(CMD_LIST, [0x00, 0x00, 0x00, 0x3E], payload)
+        log_debug("Sending date query (type 0x44/D): #{packet.bytesize} bytes, date: #{year}-#{month}-#{day}")
+        log_debug("Date query packet: #{packet.bytes.map { |b| format('%02X', b) }.join(' ')}")
+        @socket.write(packet)
+      end
+
+      def receive_date_response
+        # Wait for date query response
+        # Server should respond with session info
+        data = read_available(timeout: 3.0)
+        log_debug("Date response: #{data.bytesize} bytes")
+
+        # Consume any additional response data
+        while IO.select([@socket], nil, nil, 1.0)
+          extra = read_available(timeout: 1.0)
+          break if extra.empty?
+          data += extra
+          log_debug("Additional date data: #{extra.bytesize} bytes (total: #{data.bytesize})")
+        end
+
+        log_debug("Total date response: #{data.bytesize} bytes")
+        true
+      end
+
+      def send_list_request
+        # Send session list query (type 0x51 = 'Q' for Query)
+        # Discovered from RS3 capture analysis:
+        # - The 0x51 query type triggers session list CSV response
+        # - 0xFFFFFFFF at offset 32 means "all dates"
+        #
+        # Payload structure (64 bytes):
+        # Bytes 0-7:   zeros
+        # Bytes 8-9:   0x51 0x00 (type = Query)
+        # Bytes 10-11: 0x02 0x00 (flags)
+        # Bytes 12-23: zeros
+        # Bytes 24-27: 0x01 0x00 0x00 0x00 (count = 1)
+        # Bytes 28-31: zeros
+        # Bytes 32-35: 0xFF 0xFF 0xFF 0xFF (all dates)
+        # Bytes 36-63: zeros
+        #
+        # Tail bytes: 0x50 0x04 0x3E (P, checksum, >)
+
+        payload = Array.new(64, 0)
+
+        # Type 0x51 (Query) at offset 8
+        payload[8] = 0x51
+        payload[9] = 0x00
+
+        # Flags 0x02 at offset 10
+        payload[10] = 0x02
+        payload[11] = 0x00
+
+        # Count = 1 at offset 24
+        payload[24] = 0x01
+        payload[25] = 0x00
+        payload[26] = 0x00
+        payload[27] = 0x00
+
+        # All dates (0xFFFFFFFF) at offset 32
+        payload[32] = 0xFF
+        payload[33] = 0xFF
+        payload[34] = 0xFF
+        payload[35] = 0xFF
+
+        packet = build_nc_packet(0x40, [0x00, 0x00, 0x00, 0x3E], payload)
+        log_debug("Sending list request (type 0x51 Query): #{packet.bytesize} bytes")
+        log_debug("List packet: #{packet.bytes.map { |b| format('%02X', b) }.join(' ')}")
+        @socket.write(packet)
+      end
+
+      def receive_query_response
+        # Receive and consume the response to type 0x51 query
+        # Device responds with ACK and some data
+        data = read_available(timeout: 3.0)
+        log_debug("Query response: #{data.bytesize} bytes")
+
+        # Consume any additional response data
+        while IO.select([@socket], nil, nil, 1.0)
+          extra = read_available(timeout: 1.0)
+          break if extra.empty?
+          data += extra
+          log_debug("Additional query data: #{extra.bytesize} bytes (total: #{data.bytesize})")
+        end
+
+        true
+      end
+
+      def send_finalize_query
+        # Send type 0x24 query that triggers CSV output
+        # From RS3 capture: <hSTNC 40 00 0000 003e [payload] <STNC ' 00 3e
+        #
+        # Payload structure (64 bytes):
+        # Bytes 0-7:   zeros
+        # Bytes 8-9:   0x24 0x00 (type = 0x24)
+        # Bytes 10-11: 0x02 0x00 (flags)
+        # Bytes 12-23: zeros
+        # Bytes 24-27: 0x01 0x00 0x00 0x00 (count)
+        # Bytes 28-63: zeros
+
+        payload = Array.new(64, 0)
+
+        # Type 0x24 at offset 8
+        payload[8] = 0x24
+        payload[9] = 0x00
+
+        # Flags 0x02 at offset 10
+        payload[10] = 0x02
+        payload[11] = 0x00
+
+        # Count = 1 at offset 24
+        payload[24] = 0x01
+        payload[25] = 0x00
+        payload[26] = 0x00
+        payload[27] = 0x00
+
+        # Tail bytes: 0x27 0x00 0x3E (apostrophe, 0, >)
+        packet = build_nc_packet(0x40, [0x00, 0x00, 0x00, 0x3E], payload)
+        log_debug("Sending finalize query (type 0x24): #{packet.bytesize} bytes")
+        log_debug("Finalize packet: #{packet.bytes.map { |b| format('%02X', b) }.join(' ')}")
+        @socket.write(packet)
+      end
+
+      def receive_list_response
+        # Read all response data until we see the end marker or CSV data ends
+        # Server responds to type 0x51 query with:
+        # 1. ACK (<hSTCP>@ type 0x40)
+        # 2. Some config data
+        # 3. More exchanges
+        # 4. Eventually <hSTCP>J (type 0x4A) followed by CSV data
+        data = ""
+        deadline = Time.now + READ_TIMEOUT
+        received_csv = false
+
+        while Time.now < deadline
+          chunk = read_available(timeout: 2.0)
+
+          if chunk.empty?
+            # Check if we have enough CSV data
+            break if received_csv && data.include?("\n")
+            next
+          end
+
+          data += chunk
+
+          # Check if we've received CSV header
+          if data.include?("name,size,date,hour,") || data.include?("name,size,date,time,")
+            received_csv = true
+          end
+
+          # Check for end marker after CSV data
+          if received_csv && (data.include?("<STCP;") || data.rindex("<STCP") && data.rindex("<STCP") > data.rindex("xrz"))
+            log_debug("Received complete session list: #{data.bytesize} bytes")
+            break
+          end
+
+          # Safety: if we've received a lot of data, check if CSV is complete
+          if received_csv && data.bytesize > 10000
+            # Check if last session line seems complete
+            last_newline = data.rindex("\n")
+            if last_newline && (data.bytesize - last_newline) > 200
+              log_debug("Received #{data.bytesize} bytes, CSV appears complete")
+              break
+            end
+          end
+        end
+
+        log_debug("Total response: #{data.bytesize} bytes")
+
+        # Extract CSV content between headers
+        extract_csv_content(data)
+      end
+
+      def extract_csv_content(data)
+        # Find CSV data - it's between the binary headers
+        # Look for the CSV header line (RS3 uses "hour" instead of "time")
+        csv_start = data.index("name,size,date,hour,")
+        csv_start ||= data.index("name,size,date,time,")
+        return "" unless csv_start
+
+        # Find end of CSV data - look for protocol marker after the CSV
+        csv_end = data.length
+
+        # Find the last session file reference (ends with .xrz, .hrz, etc.)
+        last_session_match = data.rindex(/\.(xrz|hrz|xrk|drk),/)
+        if last_session_match
+          # Find the next newline after the last session
+          next_newline = data.index("\n", last_session_match)
+          if next_newline
+            csv_end = next_newline + 1
+          end
+        end
+
+        # Also check for protocol markers
+        marker_idx = data.index("<STCP", csv_start)
+        marker_idx ||= data.index("<hSTCP", csv_start)
+        csv_end = [csv_end, marker_idx].compact.min if marker_idx
+
+        csv_data = data[csv_start...csv_end]
+        csv_data.force_encoding("UTF-8")
+      end
+
+      def parse_session_csv(csv_data)
+        return [] if csv_data.nil? || csv_data.empty?
+
+        lines = csv_data.split(/\r?\n/)
+        return [] if lines.empty?
+
+        # First line is header
+        header = lines.shift
+        fields = header.split(",").map(&:strip)
+
+        sessions = []
+        lines.each do |line|
+          next if line.strip.empty?
+          next if line.start_with?("<") # Skip protocol markers
+
+          values = line.split(",")
+          next if values.length < 5 # Skip incomplete lines
+
+          session = parse_session_line(fields, values)
+          sessions << session if session
+        end
+
+        sessions
+      end
+
+      def parse_session_line(fields, values)
+        # CSV format from RS3 capture:
+        # 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,...
+        #
+        # Field indices:
+        # 0: name (filename)
+        # 1: size
+        # 2: date
+        # 3: hour (time)
+        # 4: nlap (laps)
+        # 5: nbest (best lap number)
+        # 6: best (best time in ms)
+        # 7: pilota (driver)
+        # 8: track_name
+        # 9: veicolo (vehicle)
+        # 10: campionato (championship)
+        # 11: venue_type
+        # 12: mode (speed_type)
+        # 13: trk_type (status)
+        # 14: motivolap (stop_mode)
+        # 15: maxvel (max velocity)
+        # 16: device
+        # 17: track_lat
+        # 18: track_lon
+        # 19: test_dur (duration)
+
+        filename = values[0]
+        return nil unless filename&.match?(/\.(xrz|xrk|hrz|drk)$/i)
+
+        SessionInfo.new(
+          filename: filename,
+          size: values[1]&.to_i,
+          date: values[2],
+          time: values[3],
+          laps: values[4]&.to_i,
+          best_lap: values[5]&.to_i,
+          best_time: values[6]&.to_i,
+          driver: values[7],
+          speed_type: values[12],
+          status: values[13],
+          stop_mode: values[14],
+          timestamp: values[15]&.to_i,
+          device_name: values[16],
+          longitude: values[17]&.to_i,
+          latitude: values[18]&.to_i,
+          duration: values[19]&.to_i
+        )
+      rescue StandardError => e
+        log_warn("Failed to parse session line: #{e.message}")
+        nil
+      end
+
+      # Build a STCP packet with auto-calculated 16-bit payload checksum tail
+      def build_packet(cmd, header_suffix, payload)
+        checksum = payload.sum
+        packet = HEADER_MARKER.dup
+        packet << cmd.chr
+        packet << 0x00.chr
+        header_suffix.each { |b| packet << b.chr }
+        payload.each { |b| packet << b.chr }
+        packet << TAIL_MARKER
+        packet << (checksum & 0xFF).chr
+        packet << ((checksum >> 8) & 0xFF).chr
+        packet << 0x3E.chr
+        packet
+      end
+
+      # Build a STNC packet with auto-calculated 16-bit payload checksum tail
+      def build_nc_packet(cmd, header_suffix, payload)
+        checksum = payload.sum
+        packet = HEADER_NC.dup
+        packet << cmd.chr
+        packet << 0x00.chr
+        header_suffix.each { |b| packet << b.chr }
+        payload.each { |b| packet << b.chr }
+        packet << TAIL_NC
+        packet << (checksum & 0xFF).chr
+        packet << ((checksum >> 8) & 0xFF).chr
+        packet << 0x3E.chr
+        packet
+      end
+
+      def read_bytes(n)
+        data = ""
+        deadline = Time.now + READ_TIMEOUT
+
+        while data.bytesize < n && Time.now < deadline
+          remaining = n - data.bytesize
+          chunk = @socket.recv(remaining)
+          raise ConnectionError, "Connection closed" if chunk.empty?
+
+          data += chunk
+        end
+
+        data
+      end
+
+      def read_available(timeout: 0.5)
+        data = "".b
+        deadline = Time.now + timeout
+        got_data = false
+
+        while Time.now < deadline
+          readable = IO.select([@socket], nil, nil, 0.1)
+
+          unless readable
+            # No data available yet - if we already got some data, we can stop
+            # Otherwise keep waiting until timeout
+            break if got_data
+            next
+          end
+
+          begin
+            chunk = @socket.recv_nonblock(4096)
+            break if chunk.nil? || chunk.empty?
+
+            data += chunk
+            got_data = true
+          rescue IO::WaitReadable
+            # No more data available right now
+            next
+          rescue Errno::ECONNRESET
+            raise ConnectionError, "Connection reset by peer"
+          end
+        end
+
+        data
+      end
+
+      # Download protocol methods
+
+      def send_download_request(file_path)
+        # Build download request packet
+        # <hSTNC 40 00 0000 003e [64-byte payload] <STNC 2f 05 3e
+        #
+        # Payload structure (64 bytes, from capture analysis):
+        # Offset 0-7:   zeros
+        # Offset 8-11:  flags (0x02 0x00 0x04 0x00)
+        # Offset 12-23: zeros
+        # Offset 24-27: count (0x01 0x00 0x00 0x00)
+        # Offset 28-31: zeros
+        # Offset 32-55: file path (24 bytes, null-terminated)
+        # Offset 56-63: zeros
+
+        payload = Array.new(64, 0)
+
+        # Flags at offset 8 - verified from capture: 02 00 04 00
+        # (0x04 does NOT delete - files are just hidden from RS3 after download)
+        payload[8] = 0x02
+        payload[9] = 0x00
+        payload[10] = 0x04
+        payload[11] = 0x00
+
+        # Count at offset 24
+        payload[24] = 0x01
+        payload[25] = 0x00
+        payload[26] = 0x00
+        payload[27] = 0x00
+
+        # File path at offset 32 (null-terminated, max 24 bytes)
+        path_bytes = file_path.bytes
+        path_bytes.each_with_index do |b, i|
+          break if i >= 23  # Leave room for null terminator
+          payload[32 + i] = b
+        end
+
+        # Tail bytes are auto-calculated 16-bit checksum of payload
+        # (e.g., a_0077.xrz -> 0x052F, a_0065.xrz -> 0x052C)
+        packet = build_nc_packet(0x40, [0x00, 0x00, 0x00, 0x3E], payload)
+        log_debug( "Sending download request for #{file_path} (#{packet.bytesize} bytes)")
+        log_debug( "Download packet: #{packet.bytes.map { |b| format('%02X', b) }.join(' ')}")
+        @socket.write(packet)
+      end
+
+      def receive_file_info(file_path)
+        # Read response until we get file size info
+        # Response contains TWO info blocks:
+        # 1. First block: has path but size field is zeros
+        # 2. Second block: has path AND the actual file size
+        #
+        # Each block has format:
+        # <hSTCP@...> header (12 bytes)
+        # 8 bytes zeros
+        # 02 00 04 00 (flags)
+        # 00 00 00 00 OR [size] (4 bytes - zeros in first, size in second)
+        # C0 FF 00 00 (marker)
+        # ...
+        # path string
+        # <STCP...> tail
+
+        data = read_available(timeout: 2.0)
+
+        log_debug("File info response (#{data.bytesize} bytes): #{data.bytes.take(100).map { |b| format('%02X', b) }.join(' ')}")
+
+        if data.bytesize < 100
+          log_debug("Response too short, looking for path: #{file_path}")
+          raise ProtocolError, "File info response too short (#{data.bytesize} bytes)"
+        end
+
+        data.force_encoding('ASCII-8BIT')
+
+        # Find file size in the SECOND info block
+        # Look for the second occurrence of flags 0x02 0x00 0x04 0x00
+        # Size is at offset +8 from the flags
+        flag_pattern = "\x02\x00\x04\x00".b
+        first_idx = data.index(flag_pattern)
+
+        if first_idx.nil?
+          log_debug("No flags found in response")
+          raise ProtocolError, "File info response missing flags pattern"
+        end
+
+        second_idx = data.index(flag_pattern, first_idx + 4)
+        if second_idx && second_idx + 12 <= data.bytesize
+          # Size is at offset +8 from the SECOND flags occurrence
+          size_bytes = data.byteslice(second_idx + 8, 4)
+          file_size = size_bytes.unpack1("V")
+
+          if file_size > 0 && file_size < 100_000_000
+            log_debug("File size: #{file_size} bytes (from second info block)")
+            return file_size
+          end
+        end
+
+        # Fallback: try the first block (in case there's only one)
+        if first_idx + 12 <= data.bytesize
+          size_bytes = data.byteslice(first_idx + 8, 4)
+          file_size = size_bytes.unpack1("V")
+
+          if file_size > 0 && file_size < 100_000_000
+            log_debug("File size: #{file_size} bytes (from first info block)")
+            return file_size
+          end
+        end
+
+        log_debug("Could not find valid file size in response")
+        raise ProtocolError, "Could not determine file size from response"
+      end
+
+      def send_ack
+        # Send simple acknowledgment: <hSTCP 04 00 0000 003e 00000000 <STCP 00 00 3e
+        packet = build_packet(0x04, [0x00, 0x00, 0x00, 0x3E], [0x00, 0x00, 0x00, 0x00])
+        @socket.write(packet)
+      end
+
+      def send_data_ack(bytes_received, chunk_num)
+        # Send data transfer acknowledgment with progress counter
+        # Payload: 2-byte counter (starts 0xFFC0, decrements 0x40/ACK) + 2-byte sequence
+        # Tail checksum is auto-calculated by build_packet
+        counter = [0xFFC0 - (chunk_num * 0x40), 0].max
+
+        payload = [
+          counter & 0xFF,
+          (counter >> 8) & 0xFF,
+          chunk_num & 0xFF,
+          0x00
+        ]
+
+        packet = build_packet(0x04, [0x00, 0x00, 0x00, 0x3E], payload)
+        log_debug( "Sending data ACK ##{chunk_num}: #{packet.bytes.map { |b| format('%02X', b) }.join(' ')}")
+        @socket.write(packet)
+      end
+
+      def receive_file_data(file_size, &progress_block)
+        # Read file data, stripping protocol markers
+        # Data comes with <hSTCP c4 ff> header and periodic <STCP XX YY> markers
+        # We need to collect raw data until we have file_size bytes
+        #
+        # IMPORTANT: The device sends ~64KB chunks and then waits for an ACK
+        # We must send periodic ACKs to continue receiving data
+
+        file_data = "".b  # Binary string
+        buffer = "".b
+        deadline = Time.now + 300  # 5 minute timeout for large files
+
+        # ACK tracking
+        chunk_size = 64 * 1024  # ~64KB per chunk
+        last_ack_at = 0
+        chunk_num = 0
+        no_data_count = 0
+
+        while file_data.bytesize < file_size && Time.now < deadline
+          # Read more data
+          chunk = read_available(timeout: 2.0)
+
+          if chunk.empty?
+            no_data_count += 1
+
+            # If we've received some data since last ACK but data stopped, send ACK quickly
+            # Device may have a short timeout, so respond within 1-2 seconds
+            bytes_since_ack = file_data.bytesize - last_ack_at
+            if bytes_since_ack > 0 && no_data_count >= 1
+              log_debug( "No data for ~2s, sending ACK ##{chunk_num} (received #{bytes_since_ack} since last ACK)")
+              send_data_ack(file_data.bytesize, chunk_num)
+              chunk_num += 1
+              last_ack_at = file_data.bytesize
+              no_data_count = 0
+              next
+            end
+
+            # Give up after extended no-data period (20 seconds)
+            break if no_data_count > 10 && buffer.empty?
+            next
+          end
+
+          no_data_count = 0
+          buffer += chunk
+
+          # Process buffer, extracting data and removing protocol markers
+          prev_size = file_data.bytesize
+          buffer = extract_file_data(buffer, file_data, file_size)
+
+          # Check if we need to send an ACK (every ~64KB)
+          bytes_since_ack = file_data.bytesize - last_ack_at
+          if bytes_since_ack >= chunk_size
+            log_debug( "Received #{bytes_since_ack} bytes since last ACK, sending ACK ##{chunk_num}")
+            send_data_ack(file_data.bytesize, chunk_num)
+            chunk_num += 1
+            last_ack_at = file_data.bytesize
+          end
+
+          # Report progress
+          if progress_block && file_data.bytesize > prev_size
+            progress_block.call(file_data.bytesize, file_size)
+          end
+        end
+
+        if file_data.bytesize < file_size
+          log_warn( "Incomplete download: got #{file_data.bytesize}/#{file_size} bytes")
+        else
+          log_info( "Download complete: #{file_data.bytesize} bytes")
+        end
+
+        file_data
+      end
+
+      def extract_file_data(buffer, file_data, target_size)
+        # Remove protocol markers from buffer and append data to file_data
+        #
+        # Data frame structure (from raw TCP stream capture):
+        #   Header: <hSTCP (6) + cmd (1) + 0xFF (1) + suffix (4) + counter (4) = 16 bytes
+        #   Payload: ~65KB of file data
+        #   Tail: <STCP (5) + checksum_lo (1) + checksum_hi (1) + 0x3E (1) = 8 bytes
+        #
+        # The 4-byte counter field at offset 12-15 contains:
+        #   - 00 00 00 00 for the initial data frame
+        #   - ACK counter values (C0 FF 00 00, etc.) for subsequent frames
+        # This counter is NOT file data and must be stripped with the header.
+
+        remaining = buffer.dup
+
+        loop do
+          break if remaining.empty?
+          break if file_data.bytesize >= target_size
+
+          # Look for protocol markers
+          header_idx = remaining.index(HEADER_MARKER)
+          tail_idx = remaining.index(TAIL_MARKER)
+
+          if header_idx == 0
+            if remaining.bytesize < 16
+              break # Need more data to process full header (16 bytes)
+            end
+
+            # Strip 16-byte data frame header:
+            # <hSTCP (6) + cmd (1) + flag (1) + suffix (4) + counter (4)
+            remaining = remaining.byteslice(16..-1) || ""
+            next
+          elsif tail_idx == 0
+            # Skip tail (8 bytes: <STCP + 2 suffix + > or just <STCP XX XX)
+            # Tail format: <STCP followed by 2 bytes then > (or end)
+            skip_len = [8, remaining.bytesize].min
+            remaining = remaining.byteslice(skip_len..-1) || ""
+            next
+          end
+
+          # Find next marker
+          next_marker = [header_idx, tail_idx].compact.min
+
+          if next_marker
+            # Copy data up to marker
+            data_chunk = remaining.byteslice(0, next_marker)
+            needed = target_size - file_data.bytesize
+            to_copy = [data_chunk.bytesize, needed].min
+            file_data << data_chunk.byteslice(0, to_copy)
+            remaining = remaining.byteslice(next_marker..-1) || ""
+          else
+            # No marker found, copy all remaining (but keep some buffer for partial markers)
+            safe_len = [remaining.bytesize - 12, 0].max  # Keep 12 bytes for partial marker
+            if safe_len > 0
+              needed = target_size - file_data.bytesize
+              to_copy = [safe_len, needed].min
+              file_data << remaining.byteslice(0, to_copy)
+              remaining = remaining.byteslice(to_copy..-1) || ""
+            end
+            break  # Need more data
+          end
+        end
+
+        remaining
+      end
+    end
+
+    class ConnectionError < StandardError; end
+    class ProtocolError < StandardError; end
+  end
+end