mychron 0.3.2

data/README.md

@@ -0,0 +1,413 @@
+# MyChron
+
+A Ruby gem for discovering and downloading telemetry data from AiM MyChron 6 kart data loggers over Wi-Fi.
+
+## Features
+
+- **UDP Device Discovery** - Fast broadcast discovery of MyChron devices
+- **Session Listing** - View all recorded sessions with lap times and metadata
+- **File Download** - Download `.xrz` telemetry files with progress callbacks
+- **Rails Integration** - Auto-detects Rails.logger, works seamlessly with Rails apps
+- **Zero Dependencies** - Pure Ruby implementation using only standard library
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'mychron'
+```
+
+Or install directly:
+
+```bash
+gem install mychron
+```
+
+## Quick Start
+
+```ruby
+require 'mychron'
+
+# Discover devices on your network
+devices = MyChron.discover
+devices.each do |device|
+  puts "Found: #{device.device_name} at #{device.ip}"
+end
+
+# Work with a specific device
+device = MyChron.device("192.168.1.29")
+
+# List sessions
+sessions = device.sessions
+sessions.each do |session|
+  puts "#{session.filename} - #{session.laps} laps - #{session.best_time_formatted}"
+end
+
+# Download a file
+data = device.download("a_0077.xrz")
+File.binwrite("./telemetry/a_0077.xrz", data)
+```
+
+## API Reference
+
+### Discovery
+
+```ruby
+# Broadcast discovery (find all devices)
+devices = MyChron.discover
+devices = MyChron.discover(timeout: 5.0)  # Custom timeout
+
+# Probe a specific IP
+device_info = MyChron.find_device("192.168.1.29")
+if device_info
+  puts device_info.device_name  # => "JD-AT"
+  puts device_info.wifi_name    # => "Wifi P2"
+end
+```
+
+### Device Operations
+
+```ruby
+device = MyChron.device("192.168.1.29")
+
+# Check if device is reachable
+device.reachable?  # => true
+
+# Get device info
+info = device.info
+puts info.device_name
+
+# List all sessions
+sessions = device.sessions
+
+# Find a specific session
+session = device.find_session("a_0077.xrz")
+
+# Get the latest session
+latest = device.latest_session
+```
+
+### Downloading
+
+```ruby
+device = MyChron.device("192.168.1.29")
+
+# Download to memory
+data = device.download("a_0077.xrz")
+
+# Download with progress callback
+device.download("a_0077.xrz") do |received, total|
+  percent = (received.to_f / total * 100).round(1)
+  puts "Progress: #{percent}%"
+end
+
+# Download to a directory
+path = device.download_to("a_0077.xrz", "./downloads")
+# => "./downloads/a_0077.xrz"
+
+# Download latest session
+device.download_latest("./downloads")
+
+# Download multiple files
+paths = device.download_all(["a_0077.xrz", "a_0076.xrz"], "./downloads")
+
+# Download only new sessions (skip existing)
+new_paths = device.download_new("./downloads", skip_existing: true)
+```
+
+### Session Information
+
+```ruby
+session = device.sessions.first
+
+session.filename        # => "a_0077.xrz"
+session.size            # => 524288
+session.size_formatted  # => "512.0 KB"
+session.date            # => "25/01/2026"
+session.time            # => "14:30:00"
+session.recorded_at     # => DateTime object
+session.laps            # => 5
+session.best_lap        # => 3
+session.best_time_ms    # => 65432
+session.best_time_formatted  # => "1:05.432"
+session.driver          # => "Driver Name"
+session.to_h            # => Hash representation
+```
+
+### Convenience Methods
+
+```ruby
+# These create a temporary Device instance internally
+sessions = MyChron.sessions("192.168.1.29")
+data = MyChron.download("192.168.1.29", "a_0077.xrz")
+path = MyChron.download_to("192.168.1.29", "a_0077.xrz", "./downloads")
+```
+
+## Configuration
+
+```ruby
+MyChron.configure do |config|
+  # Default download directory
+  config.download_dir = "./downloads"
+
+  # Timeouts (seconds)
+  config.discovery_timeout = 2.0
+  config.connect_timeout = 5.0
+  config.read_timeout = 30.0
+  config.download_timeout = 300.0
+
+  # Debug mode
+  config.debug = true
+
+  # Custom logger
+  config.logger = Logger.new(STDOUT)
+end
+```
+
+### Environment Variables
+
+Configuration can also be set via environment variables:
+
+```bash
+MYCHRON_DOWNLOAD_DIR=/path/to/downloads
+MYCHRON_DISCOVERY_TIMEOUT=5.0
+MYCHRON_DEBUG=true
+```
+
+## Rails Integration
+
+### Basic Setup
+
+```ruby
+# config/initializers/mychron.rb
+MyChron.configure do |config|
+  config.download_dir = Rails.root.join("storage/telemetry")
+  # Logger auto-detects Rails.logger, no need to set it
+end
+```
+
+### Service Object Example
+
+```ruby
+# app/services/telemetry_service.rb
+class TelemetryService
+  def initialize(device_ip)
+    @device = MyChron.device(device_ip)
+  end
+
+  def sync_sessions
+    @device.sessions.each do |session|
+      TelemetrySession.find_or_create_by(filename: session.filename) do |record|
+        record.size = session.size
+        record.recorded_at = session.recorded_at
+        record.laps = session.laps
+        record.best_time_ms = session.best_time_ms
+        record.driver = session.driver
+      end
+    end
+  end
+
+  def download_session(filename)
+    destination = Rails.root.join("storage/telemetry")
+    @device.download_to(filename, destination)
+  end
+
+  def download_all_new
+    destination = Rails.root.join("storage/telemetry")
+    @device.download_new(destination)
+  end
+end
+```
+
+### Background Job Example
+
+```ruby
+# app/jobs/download_telemetry_job.rb
+class DownloadTelemetryJob < ApplicationJob
+  queue_as :default
+
+  def perform(device_ip, filename)
+    device = MyChron.device(device_ip)
+    destination = Rails.root.join("storage/telemetry")
+
+    path = device.download_to(filename, destination) do |received, total|
+      # Optionally broadcast progress via ActionCable
+      percent = (received.to_f / total * 100).round
+      ActionCable.server.broadcast("downloads", { filename: filename, progress: percent })
+    end
+
+    # Update database record
+    TelemetrySession.find_by(filename: filename)&.update!(
+      downloaded: true,
+      local_path: path
+    )
+  end
+end
+```
+
+### Controller Example
+
+```ruby
+# app/controllers/telemetry_controller.rb
+class TelemetryController < ApplicationController
+  def discover
+    devices = MyChron.discover
+    render json: devices.map { |d| { ip: d.ip, name: d.device_name } }
+  end
+
+  def sessions
+    device = MyChron.device(params[:device_ip])
+    sessions = device.sessions.map(&:to_h)
+    render json: sessions
+  end
+
+  def download
+    DownloadTelemetryJob.perform_later(params[:device_ip], params[:filename])
+    head :accepted
+  end
+end
+```
+
+## Error Handling
+
+```ruby
+begin
+  device = MyChron.device("192.168.1.29")
+  data = device.download("a_0077.xrz")
+rescue MyChron::ConnectionError => e
+  # Device not reachable or connection refused
+  puts "Connection failed: #{e.message}"
+rescue MyChron::DownloadError => e
+  # Download failed
+  puts "Download failed: #{e.message}"
+rescue MyChron::NoSessionsError => e
+  # No sessions found when trying to download latest
+  puts "No sessions: #{e.message}"
+rescue MyChron::Error => e
+  # Any other MyChron error
+  puts "Error: #{e.message}"
+end
+```
+
+## Protocol Documentation
+
+For detailed protocol information, see:
+- [PROTOCOL.md](PROTOCOL.md) - Complete protocol specification
+
+## Device Setup
+
+### WiFi Configuration
+
+The MyChron 6 must be in **WLAN mode** (joining your network) for this gem to work:
+
+1. On your MyChron, go to WiFi settings
+2. Select "WLAN" mode (not AP mode)
+3. Configure your network credentials
+4. Note the assigned IP address
+
+### Network Requirements
+
+- MyChron and your application must be on the same subnet
+- UDP port 36002 for device discovery
+- TCP port 2000 for data transfer
+
+## Development & Testing
+
+### Interactive Console (IRB)
+
+To test the gem interactively, start IRB with the library loaded:
+
+```bash
+# From the gem directory
+irb -I lib -r mychron
+
+# Or use the one-liner
+ruby -I lib -r mychron -e "binding.irb"
+```
+
+Then you can experiment with the API:
+
+```ruby
+# In IRB
+MyChron::VERSION
+# => "0.3.2"
+
+# Discover devices (requires device on network)
+devices = MyChron.discover
+# => [#<struct MyChron::Protocol::Discovery::DeviceInfo ip="192.168.1.29", ...>]
+
+# Create a device instance
+device = MyChron.device("192.168.1.29")
+
+# List sessions
+sessions = device.sessions
+sessions.each { |s| puts "#{s.filename} - #{s.laps} laps" }
+
+# Download a file
+data = device.download("a_0077.xrz")
+puts "Downloaded #{data.bytesize} bytes"
+
+# Check configuration
+MyChron.configuration.to_h
+
+# Enable debug logging
+MyChron.configure { |c| c.logger = Logger.new(STDOUT) }
+```
+
+### Running with Bundler
+
+If using Bundler:
+
+```bash
+bundle exec irb -I lib -r mychron
+```
+
+### Quick Test Script
+
+Create a test script to verify connectivity:
+
+```ruby
+#!/usr/bin/env ruby
+# test_device.rb
+require_relative 'lib/mychron'
+
+# Enable logging to see what's happening
+MyChron.configure do |c|
+  c.logger = Logger.new(STDOUT)
+end
+
+puts "Discovering devices..."
+devices = MyChron.discover(timeout: 3.0)
+
+if devices.empty?
+  puts "No devices found. Make sure MyChron is on and connected to WiFi."
+  exit 1
+end
+
+device_info = devices.first
+puts "Found: #{device_info.device_name} at #{device_info.ip}"
+
+device = MyChron.device(device_info.ip)
+sessions = device.sessions
+puts "Sessions: #{sessions.count}"
+
+sessions.first(5).each do |s|
+  puts "  #{s.filename} - #{s.size_formatted} - #{s.laps} laps"
+end
+```
+
+Run it:
+
+```bash
+ruby test_device.rb
+```
+
+## Requirements
+
+- Ruby >= 3.0
+- Network access to MyChron device
+
+## License
+
+MIT

data/lib/mychron/configuration.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module MyChron
+  # Configuration for the MyChron gem
+  # Supports both programmatic configuration and environment variables
+  #
+  # @example Programmatic configuration
+  #   MyChron.configure do |config|
+  #     config.download_dir = Rails.root.join("storage/telemetry")
+  #     config.discovery_timeout = 5.0
+  #     config.logger = Rails.logger
+  #   end
+  #
+  # @example Environment variables
+  #   MYCHRON_DOWNLOAD_DIR=/path/to/downloads
+  #   MYCHRON_DISCOVERY_TIMEOUT=5.0
+  #   MYCHRON_DEBUG=true
+  #
+  class Configuration
+    DEFAULTS = {
+      # Directories
+      download_dir: "./downloads",
+
+      # Timeouts (in seconds)
+      discovery_timeout: 2.0,
+      connect_timeout: 5.0,
+      read_timeout: 30.0,
+      download_timeout: 300.0,
+
+      # Network scanning (for advanced discovery)
+      scan_ports: [2000, 21, 22, 80, 443, 8080, 5000, 6000, 7000, 9000] + (10_000..10_100).to_a,
+      scan_timeout: 0.5,
+      http_timeout: 5,
+      http_endpoints: ["/", "/api/", "/sessions/", "/data/", "/info"],
+
+      # Debugging
+      debug: false
+    }.freeze
+
+    # Directories
+    attr_accessor :download_dir
+
+    # Timeouts
+    attr_accessor :discovery_timeout, :connect_timeout, :read_timeout, :download_timeout
+
+    # Network scanning
+    attr_accessor :scan_ports, :scan_timeout, :http_timeout, :http_endpoints
+
+    # Debugging
+    attr_accessor :debug
+
+    # Custom logger (optional - defaults to Rails.logger or null logger)
+    attr_writer :logger
+
+    def initialize
+      DEFAULTS.each do |key, default_value|
+        env_value = env_value_for(key)
+        value = env_value.nil? ? default_value : coerce_value(env_value, default_value)
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    # Get the configured logger
+    # @return [Logger] The logger instance
+    def logger
+      @logger || Logging.logger
+    end
+
+    # Check if debug mode is enabled
+    # @return [Boolean]
+    def debug?
+      @debug == true
+    end
+
+    # Convert configuration to a hash
+    # @return [Hash]
+    def to_h
+      DEFAULTS.keys.each_with_object({}) do |key, hash|
+        hash[key] = instance_variable_get("@#{key}")
+      end
+    end
+
+    # Reset configuration to defaults
+    def reset!
+      DEFAULTS.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+      @logger = nil
+    end
+
+    private
+
+    def env_value_for(key)
+      ENV["MYCHRON_#{key.to_s.upcase}"]
+    end
+
+    def coerce_value(env_value, default_value)
+      case default_value
+      when Float
+        env_value.to_f
+      when Integer
+        env_value.to_i
+      when TrueClass, FalseClass
+        %w[true 1 yes].include?(env_value.to_s.downcase)
+      when Array
+        env_value.split(",").map(&:strip)
+      else
+        env_value
+      end
+    end
+  end
+end

data/lib/mychron/device.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module MyChron
+  # High-level interface for interacting with a MyChron device
+  # Provides a clean API for device operations: discovery, session listing, downloads
+  #
+  # @example Basic usage
+  #   device = MyChron::Device.new("192.168.1.29")
+  #   sessions = device.sessions
+  #   data = device.download("a_0077.xrz")
+  #
+  # @example With progress callback
+  #   device.download("a_0077.xrz") do |received, total|
+  #     puts "Progress: #{(received.to_f / total * 100).round(1)}%"
+  #   end
+  #
+  class Device
+    include Logging
+
+    attr_reader :ip
+
+    # Create a new Device instance
+    # @param ip [String] IP address of the MyChron device
+    def initialize(ip)
+      @ip = ip
+      @client = nil
+    end
+
+    # Get device information via UDP probe
+    # @param timeout [Float] Timeout in seconds (default: 2.0)
+    # @return [DeviceInfo, nil] Device information or nil if not found
+    def info(timeout: 2.0)
+      discovery = Protocol::Discovery.new(timeout: timeout)
+      discovery.probe(@ip)
+    end
+
+    # Check if the device is reachable
+    # @param timeout [Float] Timeout in seconds (default: 2.0)
+    # @return [Boolean]
+    def reachable?(timeout: 2.0)
+      !info(timeout: timeout).nil?
+    rescue StandardError
+      false
+    end
+
+    # List all sessions on the device
+    # @return [Array<Session>] Array of Session objects
+    # @raise [ConnectionError] If unable to connect
+    # @raise [ProtocolError] If protocol communication fails
+    def sessions
+      with_client do |client|
+        raw_sessions = client.list_sessions
+        raw_sessions.map { |s| Session.new(s) }
+      end
+    end
+
+    # Find a specific session by filename
+    # @param filename [String] The session filename (e.g., "a_0077.xrz")
+    # @return [Session, nil] The session or nil if not found
+    def find_session(filename)
+      sessions.find { |s| s.filename == filename }
+    end
+
+    # Get the latest (most recent) session
+    # @return [Session, nil] The most recent session or nil if none
+    def latest_session
+      all_sessions = sessions
+      return nil if all_sessions.empty?
+
+      all_sessions.max_by do |session|
+        session.recorded_at || DateTime.new(1970, 1, 1)
+      end
+    end
+
+    # Download a specific session file
+    #
+    # @note Download uses a dedicated connection. The session listing protocol
+    #       leaves the device in a different state, so downloads always use
+    #       a fresh connection (handled internally by Client#download_session).
+    #
+    # @param filename [String] The session filename (e.g., "a_0077.xrz")
+    # @yield [bytes_received, total_bytes] Progress callback
+    # @return [String] Binary file data
+    # @raise [ConnectionError] If unable to connect
+    # @raise [DownloadError] If download fails
+    def download(filename, &progress_block)
+      log_info("Downloading #{filename} from #{@ip}")
+
+      # download_session handles its own connection lifecycle
+      # (always reconnects for clean state)
+      client = Protocol::Client.new(@ip)
+      begin
+        client.download_session(filename, &progress_block)
+      ensure
+        client.disconnect
+      end
+    rescue Protocol::ConnectionError => e
+      raise ConnectionError, e.message
+    rescue Protocol::ProtocolError => e
+      raise DownloadError, "Download failed: #{e.message}"
+    end
+
+    # Download a session file to a specific directory
+    # @param filename [String] The session filename
+    # @param destination_dir [String] Directory to save the file
+    # @yield [bytes_received, total_bytes] Progress callback
+    # @return [String] Full path to the saved file
+    def download_to(filename, destination_dir, &progress_block)
+      data = download(filename, &progress_block)
+
+      FileUtils.mkdir_p(destination_dir)
+      path = File.join(destination_dir, filename)
+      File.binwrite(path, data)
+
+      log_info("Saved #{filename} to #{path} (#{data.bytesize} bytes)")
+      path
+    end
+
+    # Download the latest session
+    # @param destination_dir [String, nil] Directory to save (returns data if nil)
+    # @yield [bytes_received, total_bytes] Progress callback
+    # @return [String] Binary data or path to saved file
+    # @raise [NoSessionsError] If no sessions found
+    def download_latest(destination_dir = nil, &progress_block)
+      session = latest_session
+      raise NoSessionsError, "No sessions found on device #{@ip}" unless session
+
+      if destination_dir
+        download_to(session.filename, destination_dir, &progress_block)
+      else
+        download(session.filename, &progress_block)
+      end
+    end
+
+    # Download multiple sessions
+    # @param filenames [Array<String>] List of filenames to download
+    # @param destination_dir [String] Directory to save files
+    # @yield [filename, bytes_received, total_bytes] Progress callback
+    # @return [Array<String>] Paths to saved files
+    def download_all(filenames, destination_dir, &progress_block)
+      filenames.map do |filename|
+        wrapped_block = if progress_block
+                          ->(received, total) { progress_block.call(filename, received, total) }
+                        end
+        download_to(filename, destination_dir, &wrapped_block)
+      end
+    end
+
+    # Download all sessions that haven't been downloaded yet
+    # @param destination_dir [String] Directory to save files
+    # @param skip_existing [Boolean] Skip files that already exist locally
+    # @yield [filename, bytes_received, total_bytes] Progress callback
+    # @return [Array<String>] Paths to newly downloaded files
+    def download_new(destination_dir, skip_existing: true, &progress_block)
+      downloaded = []
+
+      sessions.each do |session|
+        local_path = File.join(destination_dir, session.filename)
+
+        if skip_existing && File.exist?(local_path)
+          log_debug("Skipping #{session.filename} - already exists")
+          next
+        end
+
+        wrapped_block = if progress_block
+                          ->(received, total) { progress_block.call(session.filename, received, total) }
+                        end
+
+        path = download_to(session.filename, destination_dir, &wrapped_block)
+        downloaded << path
+      end
+
+      downloaded
+    end
+
+    def inspect
+      "#<MyChron::Device ip=#{@ip.inspect}>"
+    end
+
+    def to_s
+      "MyChron Device at #{@ip}"
+    end
+
+    private
+
+    def with_client
+      client = Protocol::Client.new(@ip)
+      client.connect
+      yield client
+    ensure
+      client&.disconnect
+    end
+  end
+end