mychron 0.3.2

data/lib/mychron/protocol/discovery.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module MyChron
+  module Protocol
+    # UDP Discovery protocol for finding MyChron devices
+    # Sends "aim-ka" beacon on port 36002, receives 236-byte device info
+    class Discovery
+      include Logging
+
+      DISCOVERY_PORT = 36002
+      BEACON = "aim-ka"
+      RESPONSE_SIZE = 236
+      DEFAULT_TIMEOUT = 2.0
+
+      DeviceInfo = Struct.new(
+        :ip,
+        :device_name,
+        :wifi_name,
+        :serial_number,
+        :firmware_version,
+        :raw_data,
+        keyword_init: true
+      )
+
+      def initialize(timeout: DEFAULT_TIMEOUT)
+        @timeout = timeout
+      end
+
+      # Discover devices via UDP broadcast
+      # Returns array of DeviceInfo
+      def discover(target_ip: nil, broadcast: true)
+        devices = []
+        socket = UDPSocket.new
+
+        begin
+          socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_BROADCAST, true) if broadcast
+          socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_REUSEADDR, true)
+          socket.bind("0.0.0.0", 0)
+
+          # Send beacon
+          begin
+            if target_ip
+              log_debug("Sending beacon to #{target_ip}:#{DISCOVERY_PORT}")
+              socket.send(BEACON, 0, target_ip, DISCOVERY_PORT)
+            else
+              log_debug("Sending broadcast beacon to 255.255.255.255:#{DISCOVERY_PORT}")
+              socket.send(BEACON, 0, "255.255.255.255", DISCOVERY_PORT)
+            end
+          rescue Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::EADDRNOTAVAIL => e
+            log_warn("Network error sending beacon: #{e.message}")
+            return devices
+          end
+
+          # Wait for responses
+          deadline = Time.now + @timeout
+          while Time.now < deadline
+            remaining = deadline - Time.now
+            break if remaining <= 0
+
+            readable = IO.select([socket], nil, nil, [remaining, 0.5].min)
+            next unless readable
+
+            begin
+              data, addr = socket.recvfrom_nonblock(RESPONSE_SIZE + 100)
+              sender_ip = addr[3]
+
+              if data.bytesize >= RESPONSE_SIZE
+                device = parse_response(data, sender_ip)
+                devices << device if device
+                log_info("Found device: #{device.device_name} at #{sender_ip}")
+              end
+            rescue IO::WaitReadable
+              # No data yet, continue
+            end
+          end
+        ensure
+          socket.close
+        end
+
+        devices
+      end
+
+      # Probe a specific IP address
+      def probe(ip)
+        devices = discover(target_ip: ip, broadcast: false)
+        devices.first
+      end
+
+      private
+
+      def parse_response(data, ip)
+        # Response structure (236 bytes) - verified from actual device capture:
+        # Offset 0x00 (0):   Magic (0xEC000000)
+        # Offset 0x04 (4):   Protocol version (0x02000000)
+        # Offset 0x08 (8):   IP address (little-endian)
+        # Offset 0x0C (12):  Flags/status
+        # Offset 0x14 (20):  Device name (null-terminated string)
+        # Offset 0x54 (84):  "idn" marker + version byte
+        # Offset 0x58 (88):  Firmware version components (3x uint16 LE)
+        # Offset 0x60 (96):  Serial number (uint32 LE)
+        # Offset 0x94 (148): WiFi config name (null-terminated string)
+
+        # Extract device name at offset 0x14 (20 decimal)
+        device_name = extract_string(data, 0x14, 48)
+
+        # Extract WiFi name at offset 0x94 (148 decimal)
+        wifi_name = extract_string(data, 0x94, 48)
+
+        # Extract serial number at offset 0x60 (96 decimal) - uint32 little-endian
+        serial_number = extract_serial_number(data, 0x60)
+
+        # Extract firmware version from offset 0x58 (88 decimal) - 3x uint16 LE
+        firmware_version = extract_firmware_version(data, 0x58)
+
+        DeviceInfo.new(
+          ip: ip,
+          device_name: device_name,
+          wifi_name: wifi_name,
+          serial_number: serial_number,
+          firmware_version: firmware_version,
+          raw_data: data
+        )
+      rescue StandardError => e
+        log_warn("Failed to parse response from #{ip}: #{e.message}")
+        nil
+      end
+
+      def extract_string(data, offset, max_length)
+        return "" if offset >= data.bytesize
+
+        str_bytes = data.byteslice(offset, max_length)
+        return "" if str_bytes.nil? || str_bytes.empty?
+
+        # Find null terminator
+        null_idx = str_bytes.index("\x00")
+        str = null_idx ? str_bytes[0...null_idx] : str_bytes
+
+        # Clean up - remove non-printable chars
+        str.encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
+           .gsub(/[^[:print:]]/, "")
+           .strip
+      end
+
+      def extract_serial_number(data, offset)
+        # Serial number is a 32-bit little-endian unsigned integer
+        return nil if offset + 4 > data.bytesize
+
+        data.byteslice(offset, 4).unpack1("V")
+      end
+
+      def extract_firmware_version(data, offset)
+        # Firmware version is 3x uint16 little-endian values
+        # Format appears to be: major.minor.patch or similar
+        return nil if offset + 6 > data.bytesize
+
+        v1, v2, v3 = data.byteslice(offset, 6).unpack("v3")
+        "#{v1}.#{v2}.#{v3}"
+      end
+    end
+  end
+end

data/lib/mychron/session.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "date"
+
+module MyChron
+  # Represents a telemetry session recorded on a MyChron device
+  # Wraps the raw SessionInfo struct with convenience methods
+  class Session
+    attr_reader :filename, :size, :date, :time, :laps, :best_lap,
+                :best_time_ms, :driver, :device_name, :speed_type,
+                :status, :stop_mode, :timestamp, :longitude, :latitude, :duration
+
+    # Create a Session from a Protocol::Client::SessionInfo struct
+    # @param session_info [Protocol::Client::SessionInfo] Raw session data
+    def initialize(session_info)
+      @filename = session_info.filename
+      @size = session_info.size || 0
+      @date = session_info.date
+      @time = session_info.time
+      @laps = session_info.laps || 0
+      @best_lap = session_info.best_lap
+      @best_time_ms = session_info.best_time
+      @driver = session_info.driver
+      @device_name = session_info.device_name
+      @speed_type = session_info.speed_type
+      @status = session_info.status
+      @stop_mode = session_info.stop_mode
+      @timestamp = session_info.timestamp
+      @longitude = session_info.longitude
+      @latitude = session_info.latitude
+      @duration = session_info.duration
+    end
+
+    # Parse the recording date and time into a DateTime object
+    # @return [DateTime, nil] The recording timestamp
+    def recorded_at
+      return nil unless @date && @time
+
+      DateTime.strptime("#{@date} #{@time}", "%d/%m/%Y %H:%M:%S")
+    rescue Date::Error
+      nil
+    end
+
+    # Format the best lap time as "M:SS.mmm"
+    # @return [String, nil] Formatted time or nil if not available
+    def best_time_formatted
+      return nil unless @best_time_ms&.positive?
+
+      total_ms = @best_time_ms
+      minutes = total_ms / 60_000
+      remaining_ms = total_ms % 60_000
+      seconds = remaining_ms / 1000
+      milliseconds = remaining_ms % 1000
+
+      format("%d:%02d.%03d", minutes, seconds, milliseconds)
+    end
+
+    # Format file size in human-readable format
+    # @return [String] Formatted size (e.g., "512.5 KB")
+    def size_formatted
+      return "0 B" if @size.zero?
+
+      units = %w[B KB MB GB]
+      exp = (Math.log(@size) / Math.log(1024)).to_i
+      exp = [exp, units.length - 1].min
+      format("%.1f %s", @size.to_f / (1024**exp), units[exp])
+    end
+
+    # Check if this is a valid telemetry file
+    # @return [Boolean]
+    def valid?
+      filename&.match?(/\.(xrz|xrk|hrz|drk)$/i)
+    end
+
+    # Get the file extension
+    # @return [String, nil]
+    def extension
+      File.extname(@filename).downcase if @filename
+    end
+
+    # Duration in seconds (if available)
+    # @return [Float, nil]
+    def duration_seconds
+      @duration.to_f / 1000 if @duration&.positive?
+    end
+
+    # Hash representation for serialization
+    # @return [Hash]
+    def to_h
+      {
+        filename: @filename,
+        size: @size,
+        date: @date,
+        time: @time,
+        laps: @laps,
+        best_lap: @best_lap,
+        best_time_ms: @best_time_ms,
+        driver: @driver,
+        device_name: @device_name,
+        recorded_at: recorded_at&.iso8601
+      }
+    end
+
+    # JSON representation
+    # @return [String]
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    def inspect
+      "#<MyChron::Session #{@filename} (#{size_formatted}, #{@laps} laps)>"
+    end
+
+    def to_s
+      "#{@filename} - #{size_formatted} - #{@laps} laps"
+    end
+  end
+end

data/lib/mychron/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MyChron
+  VERSION = "0.3.2"
+end

data/lib/mychron.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "timeout"
+require "ipaddr"
+require "open3"
+require "time"
+require "fileutils"
+
+# Core modules
+require_relative "mychron/version"
+require_relative "mychron/errors"
+require_relative "mychron/logging"
+require_relative "mychron/configuration"
+require_relative "mychron/session"
+require_relative "mychron/device"
+
+# Protocol implementation
+require_relative "mychron/protocol/discovery"
+require_relative "mychron/protocol/client"
+
+# Network utilities (for advanced discovery)
+require_relative "mychron/network/arp"
+require_relative "mychron/network/scanner"
+require_relative "mychron/network/http_probe"
+
+# Discovery orchestration
+require_relative "mychron/discovery/scorer"
+require_relative "mychron/discovery/detector"
+
+# MyChron - Ruby library for AiM MyChron 6 telemetry devices
+#
+# This gem provides a clean API for:
+# - Discovering MyChron devices on your network
+# - Listing recorded telemetry sessions
+# - Downloading session files (.xrz format)
+#
+# @example Basic discovery and download
+#   # Find devices on the network
+#   devices = MyChron.discover
+#   puts "Found #{devices.count} device(s)"
+#
+#   # Work with a specific device
+#   device = MyChron.device("192.168.1.29")
+#   sessions = device.sessions
+#   data = device.download(sessions.first.filename)
+#
+# @example Rails integration
+#   # In an initializer or controller
+#   MyChron.configure do |config|
+#     config.download_dir = Rails.root.join("storage/telemetry")
+#     config.logger = Rails.logger
+#   end
+#
+#   # In a service or job
+#   device = MyChron.device(params[:device_ip])
+#   sessions = device.sessions
+#
+module MyChron
+  class << self
+    # Configure the MyChron gem
+    # @yield [Configuration] Configuration object
+    # @return [Configuration]
+    #
+    # @example
+    #   MyChron.configure do |config|
+    #     config.download_dir = "/path/to/downloads"
+    #     config.discovery_timeout = 5.0
+    #     config.logger = Rails.logger
+    #   end
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Get the current configuration
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    alias config configuration
+
+    # Get the logger
+    # @return [Logger]
+    def logger
+      configuration.logger
+    end
+
+    # Set a custom logger
+    # @param logger [Logger] A Logger-compatible instance
+    def logger=(logger)
+      Logging.logger = logger
+    end
+
+    # Reset configuration to defaults
+    def reset!
+      @configuration = nil
+      Logging.reset!
+    end
+
+    # ----- Primary API: Device Discovery -----
+
+    # Discover all MyChron devices on the network via UDP broadcast
+    # @param timeout [Float] Timeout in seconds (default: 2.0)
+    # @return [Array<Protocol::Discovery::DeviceInfo>] Array of discovered devices
+    #
+    # @example
+    #   devices = MyChron.discover
+    #   devices.each do |device|
+    #     puts "Found: #{device.device_name} at #{device.ip}"
+    #   end
+    def discover(timeout: nil)
+      timeout ||= configuration.discovery_timeout
+      Protocol::Discovery.new(timeout: timeout).discover
+    end
+
+    # Probe a specific IP address to check for a MyChron device
+    # @param ip [String] IP address to probe
+    # @param timeout [Float] Timeout in seconds (default: 2.0)
+    # @return [Protocol::Discovery::DeviceInfo, nil] Device info or nil if not found
+    #
+    # @example
+    #   device_info = MyChron.find_device("192.168.1.29")
+    #   if device_info
+    #     puts "Found: #{device_info.device_name}"
+    #   end
+    def find_device(ip, timeout: nil)
+      timeout ||= configuration.discovery_timeout
+      Protocol::Discovery.new(timeout: timeout).probe(ip)
+    end
+
+    # Create a Device instance for interacting with a specific device
+    # @param ip [String] IP address of the MyChron device
+    # @return [Device] Device instance
+    #
+    # @example
+    #   device = MyChron.device("192.168.1.29")
+    #   sessions = device.sessions
+    #   data = device.download("a_0077.xrz")
+    def device(ip)
+      Device.new(ip)
+    end
+
+    # ----- Convenience Methods -----
+
+    # List sessions on a device (convenience method)
+    # @param ip [String] IP address of the device
+    # @return [Array<Session>] Array of sessions
+    def sessions(ip)
+      device(ip).sessions
+    end
+
+    # Download a session file (convenience method)
+    # @param ip [String] IP address of the device
+    # @param filename [String] Session filename
+    # @yield [bytes_received, total_bytes] Progress callback
+    # @return [String] Binary file data
+    def download(ip, filename, &progress_block)
+      device(ip).download(filename, &progress_block)
+    end
+
+    # Download a session to a directory (convenience method)
+    # @param ip [String] IP address of the device
+    # @param filename [String] Session filename
+    # @param destination_dir [String] Directory to save the file
+    # @yield [bytes_received, total_bytes] Progress callback
+    # @return [String] Full path to saved file
+    def download_to(ip, filename, destination_dir, &progress_block)
+      device(ip).download_to(filename, destination_dir, &progress_block)
+    end
+
+    # ----- Advanced Discovery -----
+
+    # Perform network-based discovery using ARP + port scanning
+    # Use this if UDP discovery doesn't work (firewall, etc.)
+    # @param subnet [String, nil] Subnet to scan (auto-detected if nil)
+    # @param scan_ports [Boolean] Whether to scan ports
+    # @param probe_http [Boolean] Whether to probe HTTP endpoints
+    # @return [Array<Hash>] Array of candidate device hashes
+    def network_discover(subnet: nil, scan_ports: true, probe_http: true)
+      detector = Discovery::Detector.new(subnet: subnet)
+      # Convert boolean to nil (use default ports) or pass array through
+      ports = case scan_ports
+              when true then nil
+              when false then []
+              when Array then scan_ports
+              else nil
+              end
+      detector.run(scan_ports: ports, probe_http: probe_http)
+    end
+  end
+end

data/mychron.gemspec

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "lib/mychron/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "mychron"
+  spec.version = MyChron::VERSION
+  spec.authors = ["Eugeniu"]
+  spec.email = ["eugeniu.rtj@gmail.com"]
+
+  spec.summary = "Ruby library for AiM MyChron 6 telemetry devices"
+  spec.description = <<~DESC
+    A Ruby gem for discovering and downloading telemetry data from AiM MyChron 6
+    kart data loggers over Wi-Fi. Works with Ruby on Rails and any Ruby application.
+
+    Features:
+    - UDP device discovery
+    - Session listing with lap times and metadata
+    - File download with progress callbacks
+    - Rails.logger integration
+  DESC
+  spec.homepage = "https://gitlab.com/eugeniu-rtj/mychron"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.glob(%w[
+    lib/**/*.rb
+    Gemfile
+    mychron.gemspec
+    README.md
+    LICENSE
+    PROTOCOL.md
+    IMPLEMENTATION_NOTES.md
+  ]).reject { |f| f.match?(%r{spec/|test/|\.git|exe/|cli\.rb}) }
+
+  spec.require_paths = ["lib"]
+
+  # No runtime dependencies - pure Ruby implementation
+  # The gem uses only standard library: socket, json, timeout, etc.
+
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "rubocop", "~> 1.60"
+  spec.add_development_dependency "webmock", "~> 3.23"
+  spec.add_development_dependency "yard", "~> 0.9"
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: mychron
+version: !ruby/object:Gem::Version
+  version: 0.3.2
+platform: ruby
+authors:
+- Eugeniu
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: |
+  A Ruby gem for discovering and downloading telemetry data from AiM MyChron 6
+  kart data loggers over Wi-Fi. Works with Ruby on Rails and any Ruby application.
+
+  Features:
+  - UDP device discovery
+  - Session listing with lap times and metadata
+  - File download with progress callbacks
+  - Rails.logger integration
+email:
+- eugeniu.rtj@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- IMPLEMENTATION_NOTES.md
+- LICENSE
+- PROTOCOL.md
+- README.md
+- lib/mychron.rb
+- lib/mychron/configuration.rb
+- lib/mychron/device.rb
+- lib/mychron/discovery/detector.rb
+- lib/mychron/discovery/scorer.rb
+- lib/mychron/errors.rb
+- lib/mychron/logging.rb
+- lib/mychron/monitor/watcher.rb
+- lib/mychron/network/arp.rb
+- lib/mychron/network/http_probe.rb
+- lib/mychron/network/scanner.rb
+- lib/mychron/protocol/client.rb
+- lib/mychron/protocol/discovery.rb
+- lib/mychron/session.rb
+- lib/mychron/version.rb
+- mychron.gemspec
+homepage: https://gitlab.com/eugeniu-rtj/mychron
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://gitlab.com/eugeniu-rtj/mychron
+  changelog_uri: https://gitlab.com/eugeniu-rtj/mychron/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby library for AiM MyChron 6 telemetry devices
+test_files: []