usb_pd_match 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b7167afe91626fc02879ea3e6f61539af7d39687a8bb1abc6ea8cd476708544
+  data.tar.gz: bcc4a26fa40519418d03da3dabc0ea8d875ba915e221f24c70f11f696ef41595
+SHA512:
+  metadata.gz: 90c5cfa3e4cacec01ced3bc651c38e7385b91ee51f526307fe91f109e318218d92d27e42d2fc88261de9dac381561e79f4205f92afea3350d0653f2be16a6746
+  data.tar.gz: e183fe86d65e18c4238792e812dc94edefa3e69598bfde5ea5b8a40d22f7bc3b1a621c4a1a294838dcc3ca69a2a3bbc90f92ec164afeaefbd5c19c4fd0af59c4

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CairoVolt Engineering
+
+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.

data/README.md

@@ -0,0 +1,106 @@
+# usb_pd_match
+
+A small, dependency-free Ruby toolkit for reasoning about **USB-C Power Delivery (USB-PD)**
+compatibility between chargers and devices. Model a charger and a device, negotiate the
+optimal voltage/current contract, rank chargers for a given device, and check whether a
+device will actually reach its full rated power.
+
+USB Power Delivery negotiates the highest *fixed Power Data Object (PDO)* both sides support;
+the full handshake is defined in the [USB-IF Power Delivery specification](https://www.usb.org/usb-charger-pd)
+and summarised on the [USB-C Wikipedia page](https://en.wikipedia.org/wiki/USB-C). This gem
+implements the practical fixed-PDO selection logic so you can answer "will this charger fast-charge
+this device?" without wiring up real hardware.
+
+## Why
+
+Anyone building an electronics catalog, an e-commerce spec table, or an IoT charging fleet keeps
+re-deriving the same question: *given a charger's wattage and a device's limits, what power actually
+flows?* `usb_pd_match` encodes that once, with tests. It models the same fixed-PDO ladder that modern
+[GaN (gallium nitride)](https://en.wikipedia.org/wiki/Gallium_nitride) chargers expose, including the
+5 A USB-C cable ceiling and Extended Power Range (EPR) voltages for 100 W+ bricks.
+
+## Installation
+
+```bash
+gem install usb_pd_match
+```
+
+Or in a Gemfile:
+
+```ruby
+gem "usb_pd_match"
+```
+
+## Usage
+
+```ruby
+require "usb_pd_match"
+
+charger = UsbPdMatch.charger(name: "65W GaN", max_watts: 65)
+laptop  = UsbPdMatch.device(name: "Ultrabook", max_watts: 60, max_voltage: 20)
+
+result = UsbPdMatch.negotiate(charger, laptop)
+result.summary       # => "65W GaN → Ultrabook: 20.0V @ 3.00A = 60.0W (100% of device rating)"
+result.full_power?   # => true
+result.watts         # => 60.0
+```
+
+### Rank chargers for a device
+
+```ruby
+device   = UsbPdMatch.device(name: "Tablet", max_watts: 45, max_voltage: 20)
+chargers = [
+  UsbPdMatch.charger(name: "20W brick", max_watts: 20),
+  UsbPdMatch.charger(name: "30W GaN",   max_watts: 30),
+  UsbPdMatch.charger(name: "65W GaN",   max_watts: 65)
+]
+
+UsbPdMatch.best_charger_for(device, chargers).each do |r|
+  puts r.summary
+end
+# 65W GaN → Tablet: 20.0V @ 2.25A = 45.0W (100% of device rating)
+# 30W GaN → Tablet: 20.0V @ 1.50A = 30.0W (67% of device rating)
+# 20W brick → Tablet: 9.0V @ 2.22A = 20.0W (44% of device rating)
+```
+
+### Custom PDOs
+
+If you know a charger's exact advertised PDOs (e.g. from a spec sheet), pass them directly
+instead of letting the gem derive them:
+
+```ruby
+charger = UsbPdMatch.charger(
+  name: "Anker 735",
+  max_watts: 65,
+  pdos: [[5, 3.0], [9, 3.0], [15, 3.0], [20, 3.25]],
+  ports: 3
+)
+```
+
+When you need the real-world numbers behind a specific model, manufacturer spec pages such as
+[Anker's official charger lineup](https://www.anker.com/) list the exact PDO tables; for buyers in
+Egypt, a localized breakdown of wattages and port layouts is kept in this
+[USB-C charging guide](https://cairovolt.com/en/chargers), and the matching
+[Anker GaN wall chargers](https://cairovolt.com/en/anker/wall-chargers) catalog maps models to the
+device classes they fast-charge.
+
+## API
+
+| Method | Returns |
+|--------|---------|
+| `UsbPdMatch.charger(name:, max_watts:, pdos: nil, ports: 1)` | `Charger` |
+| `UsbPdMatch.device(name:, max_watts:, max_voltage: 20)` | `Device` |
+| `UsbPdMatch.negotiate(charger, device)` | `Result` or `nil` |
+| `UsbPdMatch.best_charger_for(device, chargers)` | `[Result]` sorted best-first |
+| `Result#watts / #voltage / #current` | negotiated contract |
+| `Result#full_power? / #efficiency / #summary` | helpers |
+
+## Development
+
+```bash
+ruby -Ilib test/test_usb_pd_match.rb
+```
+
+## License
+
+Released under the [MIT License](LICENSE).

data/lib/usb_pd_match/charger.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module UsbPdMatch
+  # A USB-C Power Delivery source (charger). It advertises a set of fixed
+  # Power Data Objects (PDOs) — the (voltage, max_current) pairs it can supply.
+  #
+  # USB Power Delivery negotiates the highest mutually-supported fixed PDO,
+  # so a charger is modeled as the list of PDOs it exposes plus the number of
+  # physical USB-C ports (shared power budget across ports is left to the caller).
+  class Charger
+    # Common USB-PD fixed-supply voltages (Standard Power Range).
+    STANDARD_VOLTAGES = [5, 9, 15, 20].freeze
+    # Extended Power Range (EPR) adds these for 100W+ chargers.
+    EPR_VOLTAGES = [28, 36, 48].freeze
+
+    attr_reader :name, :max_watts, :pdos, :ports
+
+    # pdos: array of [voltage, max_current_amps]. If omitted, a sane fixed-PDO
+    # set is derived from max_watts using the standard voltage ladder.
+    def initialize(name:, max_watts:, pdos: nil, ports: 1)
+      @name = name
+      @max_watts = max_watts.to_f
+      @ports = Integer(ports)
+      @pdos = (pdos || derive_pdos(@max_watts)).map { |v, a| [Integer(v), a.to_f] }
+      freeze
+    end
+
+    # Highest voltage this charger can output.
+    def max_voltage
+      pdos.map(&:first).max
+    end
+
+    # Max current available at a given voltage (0.0 if the voltage isn't offered).
+    def current_at(voltage)
+      match = pdos.find { |v, _a| v == voltage }
+      match ? match[1] : 0.0
+    end
+
+    def supports?(voltage)
+      current_at(voltage).positive?
+    end
+
+    def to_h
+      { name: name, max_watts: max_watts, ports: ports, pdos: pdos }
+    end
+
+    private
+
+    # Build a realistic fixed-PDO ladder bounded by max_watts. A voltage is
+    # offered only once the charger has the budget to make it useful; each PDO's
+    # current is capped so voltage * current never exceeds the wattage budget,
+    # and clamped to the 5 A USB-C cable limit.
+    def derive_pdos(watts)
+      thresholds = { 5 => 0, 9 => 18, 15 => 27, 20 => 30,
+                     28 => 100, 36 => 140, 48 => 200 }
+      thresholds.each_with_object([]) do |(v, min_watts), acc|
+        next if watts < min_watts
+        current = [(watts / v).round(2), 5.0].min
+        acc << [v, current] if current >= 0.5
+      end
+    end
+  end
+end

data/lib/usb_pd_match/device.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module UsbPdMatch
+  # A USB-C Power Delivery sink (the device being charged: phone, laptop,
+  # power bank, earbuds case, etc.). It accepts up to a maximum voltage and
+  # draws up to a maximum power.
+  class Device
+    attr_reader :name, :max_watts, :max_voltage
+
+    def initialize(name:, max_watts:, max_voltage: 20)
+      @name = name
+      @max_watts = max_watts.to_f
+      @max_voltage = Integer(max_voltage)
+      freeze
+    end
+
+    # Max current this device will pull at a given voltage, bounded by its
+    # power ceiling and the 5 A cable limit.
+    def current_ceiling_at(voltage)
+      return 0.0 if voltage > max_voltage
+
+      [(max_watts / voltage).round(2), 5.0].min
+    end
+
+    def to_h
+      { name: name, max_watts: max_watts, max_voltage: max_voltage }
+    end
+  end
+end

data/lib/usb_pd_match/negotiator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module UsbPdMatch
+  # Result of a USB-PD negotiation between a Charger (source) and Device (sink).
+  Result = Struct.new(:voltage, :current, :watts, :charger, :device, keyword_init: true) do
+    # Fraction of the device's requested power actually delivered (0.0–1.0).
+    def efficiency
+      return 1.0 if device.max_watts.zero?
+
+      [(watts / device.max_watts).round(4), 1.0].min
+    end
+
+    # True when the device receives its full rated power.
+    def full_power?
+      watts >= device.max_watts - 0.01
+    end
+
+    def summary
+      format("%s → %s: %.1fV @ %.2fA = %.1fW (%d%% of device rating)",
+             charger.name, device.name, voltage, current, watts, (efficiency * 100).round)
+    end
+
+    def to_h
+      { voltage: voltage, current: current, watts: watts,
+        efficiency: efficiency, full_power: full_power? }
+    end
+  end
+
+  # Negotiates the optimal fixed-PDO contract between a charger and a device,
+  # mirroring how a real USB-C PD sink picks the highest mutually-supported
+  # voltage and the current both sides can sustain.
+  module Negotiator
+    module_function
+
+    # Returns a Result, or nil if there is no mutually supported voltage.
+    def negotiate(charger, device)
+      candidates = charger.pdos.select do |voltage, _charger_current|
+        voltage <= device.max_voltage
+      end
+      return nil if candidates.empty?
+
+      best = candidates.map do |voltage, charger_current|
+        current = [charger_current, device.current_ceiling_at(voltage)].min
+        [voltage, current, (voltage * current).round(2)]
+      end.max_by { |voltage, _current, watts| [watts, voltage] } # tie → higher voltage (lower loss)
+
+      Result.new(voltage: best[0], current: best[1], watts: best[2],
+                 charger: charger, device: device)
+    end
+
+    # Convenience: just the delivered wattage (0.0 if incompatible).
+    def watts(charger, device)
+      result = negotiate(charger, device)
+      result ? result.watts : 0.0
+    end
+
+    # True when the device will charge at its full rated power on this charger.
+    def full_power?(charger, device)
+      result = negotiate(charger, device)
+      result ? result.full_power? : false
+    end
+  end
+end

data/lib/usb_pd_match/version.rb

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

data/lib/usb_pd_match.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "usb_pd_match/version"
+require_relative "usb_pd_match/charger"
+require_relative "usb_pd_match/device"
+require_relative "usb_pd_match/negotiator"
+
+# UsbPdMatch — a small, dependency-free toolkit for reasoning about USB-C
+# Power Delivery (USB-PD) compatibility between chargers and devices.
+#
+# Quick start:
+#   charger = UsbPdMatch.charger(name: "65W GaN", max_watts: 65)
+#   device  = UsbPdMatch.device(name: "Laptop", max_watts: 60, max_voltage: 20)
+#   UsbPdMatch.negotiate(charger, device).summary
+#   # => "65W GaN → Laptop: 20.0V @ 3.00A = 60.0W (100% of device rating)"
+module UsbPdMatch
+  class Error < StandardError; end
+
+  module_function
+
+  def charger(**kwargs)
+    Charger.new(**kwargs)
+  end
+
+  def device(**kwargs)
+    Device.new(**kwargs)
+  end
+
+  def negotiate(charger, device)
+    Negotiator.negotiate(charger, device)
+  end
+
+  # Rank a list of chargers by how well each charges the given device,
+  # best first. Each entry is the negotiation Result.
+  def best_charger_for(device, chargers)
+    chargers
+      .map { |c| Negotiator.negotiate(c, device) }
+      .compact
+      .sort_by { |r| -r.watts }
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: usb_pd_match
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- CairoVolt Engineering
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-13 00:00:00.000000000 Z
+dependencies: []
+description: |
+  A small, dependency-free Ruby toolkit for reasoning about USB-C Power Delivery (USB-PD).
+  Model chargers and devices by their fixed PDOs, negotiate the optimal voltage/current
+  contract, rank chargers for a given device, and check whether a device will reach full
+  rated power — useful for e-commerce spec tooling, IoT fleets, and electronics catalogs.
+email:
+- hello@cairovolt.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/usb_pd_match.rb
+- lib/usb_pd_match/charger.rb
+- lib/usb_pd_match/device.rb
+- lib/usb_pd_match/negotiator.rb
+- lib/usb_pd_match/version.rb
+homepage: https://rubydoc.info/gems/usb_pd_match
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://rubydoc.info/gems/usb_pd_match
+  changelog_uri: https://rubydoc.info/gems/usb_pd_match
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: USB-C Power Delivery compatibility calculator for chargers and devices.
+test_files: []