ruby-blinkstick 0.0.2 → 0.1.0

data/lib/blinkstick/backend.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Blinkstick
+  # Finds and opens sticks through the operating system. One backend exists
+  # per OS; it is chosen and loaded on the first {Blinkstick.list} or
+  # {Blinkstick.open}, never by `require "blinkstick"`.
+  #
+  # A backend responds to `#list`, returning an Array of {Device}, and
+  # `#open(device)`, returning a handle. A handle responds to
+  # `#write_feature(report)`, where report is a binary String whose first
+  # byte is the report ID, and to `#close`, which may be called more than
+  # once. Handles raise {Blinkstick::Error} subclasses, or {TransferFailed}
+  # for a failure worth trying again.
+  #
+  # @api private
+  module Backend
+    # How many times a transfer is tried before the stick counts as gone.
+    ATTEMPTS = 3
+
+    # Raised by a handle when a transfer failed but may work if tried again.
+    class TransferFailed < Error; end
+
+    # A stick as the OS reports it. The id is opaque outside the backend
+    # that listed it (a path on Linux, an IOKit reference on macOS) and the
+    # serial is always a String.
+    Device = Data.define(:id, :serial, :manufacturer, :product, :release)
+
+    class << self
+      # Replaces the backend, for tests.
+      attr_writer :current
+
+      # @return [#list, #open] the backend for the running OS, loaded once
+      # @raise [Blinkstick::Error] when the OS has no backend
+      def current
+        @current ||= for_host(RbConfig::CONFIG["host_os"])
+      end
+
+      private
+
+      def for_host(host_os)
+        case host_os
+        when /darwin/
+          require_relative "backend/iokit"
+          IOKit.new
+        when /linux/
+          require_relative "backend/hidraw"
+          Hidraw.new
+        else
+          raise Error, "unsupported platform: #{host_os}"
+        end
+      end
+    end
+  end
+end

data/lib/blinkstick/colour.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Blinkstick
+  # An immutable colour with 8 bits per channel.
+  #
+  #   Blinkstick::Colour.parse("#ff8800")
+  #   Blinkstick::Colour.parse("255,136,0")
+  #   Blinkstick::Colour.parse(:cornflowerblue)
+  Colour = Data.define(:red, :green, :blue) do
+    # @raise [InvalidColourError] unless each channel is an Integer from 0 to 255
+    def initialize(red:, green:, blue:)
+      [red, green, blue].each do |channel|
+        next if channel.is_a?(Integer) && channel.between?(0, 255)
+
+        raise InvalidColourError, "invalid colour channel #{channel.inspect}"
+      end
+      super
+    end
+
+    # Converts a value to a Colour.
+    #
+    # Accepts a Colour (returned as is), a Symbol or String CSS colour name in
+    # any case, hex ("#rgb" or "#rrggbb", with or without the "#"), a decimal
+    # "r,g,b" String, or an Array of three Integers.
+    #
+    # @param input [Colour, String, Symbol, Array<Integer>]
+    # @return [Colour]
+    # @raise [InvalidColourError] when the input is not a colour
+    def self.parse(input)
+      case input
+      when Colour then input
+      when Symbol then lookup(input.name.downcase) || invalid(input)
+      when Array then from_array(input)
+      when String then from_string(input)
+      else invalid(input)
+      end
+    end
+
+    # @return [Array<String>] every CSS colour name {parse} accepts, lower case and sorted
+    def self.names
+      NAMES
+    end
+
+    # @return [String] the colour as lower case "#rrggbb"
+    def hex
+      format("#%<r>02x%<g>02x%<b>02x", r: red, g: green, b: blue)
+    end
+
+    alias_method :to_s, :hex
+
+    class << self
+      private
+
+      def lookup(name)
+        COLOUR_NAMES[name]
+      end
+
+      def from_array(array)
+        invalid(array) unless array.size == 3 && array.all?(Integer)
+        new(red: array[0], green: array[1], blue: array[2])
+      rescue InvalidColourError
+        invalid(array)
+      end
+
+      # Bytes that are invalid in the String's encoding are not a colour, and
+      # would otherwise raise from strip or the regexps below.
+      def from_string(input)
+        return invalid(input) unless input.valid_encoding?
+
+        text = input.strip
+        return from_hex(input, text.delete_prefix("#")) if text.start_with?("#")
+
+        lookup(text.downcase) || (text.include?(",") ? from_decimals(input, text) : from_hex(input, text))
+      end
+
+      def from_hex(input, digits)
+        digits = digits.chars.map { |digit| digit * 2 }.join if digits.size == 3
+        invalid(input) unless digits.match?(/\A\h{6}\z/)
+        value = digits.to_i(16)
+        new(red: value >> 16, green: (value >> 8) & 0xff, blue: value & 0xff)
+      end
+
+      def from_decimals(input, text)
+        parts = text.split(",", -1).map(&:strip)
+        invalid(input) unless parts.size == 3 && parts.all?(/\A\d{1,3}\z/)
+        red, green, blue = parts.map(&:to_i)
+        new(red:, green:, blue:)
+      rescue InvalidColourError
+        invalid(input)
+      end
+
+      def invalid(input)
+        raise InvalidColourError, "invalid colour #{input.is_a?(Symbol) ? input.name.inspect : input.inspect}"
+      end
+    end
+  end
+
+  # Colour with every channel off.
+  Colour::OFF = Colour.new(red: 0, green: 0, blue: 0)
+end
+
+require_relative "colour_names"

data/lib/blinkstick/colour_names.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Blinkstick
+  # The 148 named colours from CSS Color Module Level 4, keyed in lower case.
+  # transparent and currentcolor are left out because they have no fixed RGB
+  # value.
+  COLOUR_NAMES = {
+    "aliceblue" => Colour.new(red: 240, green: 248, blue: 255),
+    "antiquewhite" => Colour.new(red: 250, green: 235, blue: 215),
+    "aqua" => Colour.new(red: 0, green: 255, blue: 255),
+    "aquamarine" => Colour.new(red: 127, green: 255, blue: 212),
+    "azure" => Colour.new(red: 240, green: 255, blue: 255),
+    "beige" => Colour.new(red: 245, green: 245, blue: 220),
+    "bisque" => Colour.new(red: 255, green: 228, blue: 196),
+    "black" => Colour.new(red: 0, green: 0, blue: 0),
+    "blanchedalmond" => Colour.new(red: 255, green: 235, blue: 205),
+    "blue" => Colour.new(red: 0, green: 0, blue: 255),
+    "blueviolet" => Colour.new(red: 138, green: 43, blue: 226),
+    "brown" => Colour.new(red: 165, green: 42, blue: 42),
+    "burlywood" => Colour.new(red: 222, green: 184, blue: 135),
+    "cadetblue" => Colour.new(red: 95, green: 158, blue: 160),
+    "chartreuse" => Colour.new(red: 127, green: 255, blue: 0),
+    "chocolate" => Colour.new(red: 210, green: 105, blue: 30),
+    "coral" => Colour.new(red: 255, green: 127, blue: 80),
+    "cornflowerblue" => Colour.new(red: 100, green: 149, blue: 237),
+    "cornsilk" => Colour.new(red: 255, green: 248, blue: 220),
+    "crimson" => Colour.new(red: 220, green: 20, blue: 60),
+    "cyan" => Colour.new(red: 0, green: 255, blue: 255),
+    "darkblue" => Colour.new(red: 0, green: 0, blue: 139),
+    "darkcyan" => Colour.new(red: 0, green: 139, blue: 139),
+    "darkgoldenrod" => Colour.new(red: 184, green: 134, blue: 11),
+    "darkgray" => Colour.new(red: 169, green: 169, blue: 169),
+    "darkgreen" => Colour.new(red: 0, green: 100, blue: 0),
+    "darkgrey" => Colour.new(red: 169, green: 169, blue: 169),
+    "darkkhaki" => Colour.new(red: 189, green: 183, blue: 107),
+    "darkmagenta" => Colour.new(red: 139, green: 0, blue: 139),
+    "darkolivegreen" => Colour.new(red: 85, green: 107, blue: 47),
+    "darkorange" => Colour.new(red: 255, green: 140, blue: 0),
+    "darkorchid" => Colour.new(red: 153, green: 50, blue: 204),
+    "darkred" => Colour.new(red: 139, green: 0, blue: 0),
+    "darksalmon" => Colour.new(red: 233, green: 150, blue: 122),
+    "darkseagreen" => Colour.new(red: 143, green: 188, blue: 143),
+    "darkslateblue" => Colour.new(red: 72, green: 61, blue: 139),
+    "darkslategray" => Colour.new(red: 47, green: 79, blue: 79),
+    "darkslategrey" => Colour.new(red: 47, green: 79, blue: 79),
+    "darkturquoise" => Colour.new(red: 0, green: 206, blue: 209),
+    "darkviolet" => Colour.new(red: 148, green: 0, blue: 211),
+    "deeppink" => Colour.new(red: 255, green: 20, blue: 147),
+    "deepskyblue" => Colour.new(red: 0, green: 191, blue: 255),
+    "dimgray" => Colour.new(red: 105, green: 105, blue: 105),
+    "dimgrey" => Colour.new(red: 105, green: 105, blue: 105),
+    "dodgerblue" => Colour.new(red: 30, green: 144, blue: 255),
+    "firebrick" => Colour.new(red: 178, green: 34, blue: 34),
+    "floralwhite" => Colour.new(red: 255, green: 250, blue: 240),
+    "forestgreen" => Colour.new(red: 34, green: 139, blue: 34),
+    "fuchsia" => Colour.new(red: 255, green: 0, blue: 255),
+    "gainsboro" => Colour.new(red: 220, green: 220, blue: 220),
+    "ghostwhite" => Colour.new(red: 248, green: 248, blue: 255),
+    "gold" => Colour.new(red: 255, green: 215, blue: 0),
+    "goldenrod" => Colour.new(red: 218, green: 165, blue: 32),
+    "gray" => Colour.new(red: 128, green: 128, blue: 128),
+    "green" => Colour.new(red: 0, green: 128, blue: 0),
+    "greenyellow" => Colour.new(red: 173, green: 255, blue: 47),
+    "grey" => Colour.new(red: 128, green: 128, blue: 128),
+    "honeydew" => Colour.new(red: 240, green: 255, blue: 240),
+    "hotpink" => Colour.new(red: 255, green: 105, blue: 180),
+    "indianred" => Colour.new(red: 205, green: 92, blue: 92),
+    "indigo" => Colour.new(red: 75, green: 0, blue: 130),
+    "ivory" => Colour.new(red: 255, green: 255, blue: 240),
+    "khaki" => Colour.new(red: 240, green: 230, blue: 140),
+    "lavender" => Colour.new(red: 230, green: 230, blue: 250),
+    "lavenderblush" => Colour.new(red: 255, green: 240, blue: 245),
+    "lawngreen" => Colour.new(red: 124, green: 252, blue: 0),
+    "lemonchiffon" => Colour.new(red: 255, green: 250, blue: 205),
+    "lightblue" => Colour.new(red: 173, green: 216, blue: 230),
+    "lightcoral" => Colour.new(red: 240, green: 128, blue: 128),
+    "lightcyan" => Colour.new(red: 224, green: 255, blue: 255),
+    "lightgoldenrodyellow" => Colour.new(red: 250, green: 250, blue: 210),
+    "lightgray" => Colour.new(red: 211, green: 211, blue: 211),
+    "lightgreen" => Colour.new(red: 144, green: 238, blue: 144),
+    "lightgrey" => Colour.new(red: 211, green: 211, blue: 211),
+    "lightpink" => Colour.new(red: 255, green: 182, blue: 193),
+    "lightsalmon" => Colour.new(red: 255, green: 160, blue: 122),
+    "lightseagreen" => Colour.new(red: 32, green: 178, blue: 170),
+    "lightskyblue" => Colour.new(red: 135, green: 206, blue: 250),
+    "lightslategray" => Colour.new(red: 119, green: 136, blue: 153),
+    "lightslategrey" => Colour.new(red: 119, green: 136, blue: 153),
+    "lightsteelblue" => Colour.new(red: 176, green: 196, blue: 222),
+    "lightyellow" => Colour.new(red: 255, green: 255, blue: 224),
+    "lime" => Colour.new(red: 0, green: 255, blue: 0),
+    "limegreen" => Colour.new(red: 50, green: 205, blue: 50),
+    "linen" => Colour.new(red: 250, green: 240, blue: 230),
+    "magenta" => Colour.new(red: 255, green: 0, blue: 255),
+    "maroon" => Colour.new(red: 128, green: 0, blue: 0),
+    "mediumaquamarine" => Colour.new(red: 102, green: 205, blue: 170),
+    "mediumblue" => Colour.new(red: 0, green: 0, blue: 205),
+    "mediumorchid" => Colour.new(red: 186, green: 85, blue: 211),
+    "mediumpurple" => Colour.new(red: 147, green: 112, blue: 219),
+    "mediumseagreen" => Colour.new(red: 60, green: 179, blue: 113),
+    "mediumslateblue" => Colour.new(red: 123, green: 104, blue: 238),
+    "mediumspringgreen" => Colour.new(red: 0, green: 250, blue: 154),
+    "mediumturquoise" => Colour.new(red: 72, green: 209, blue: 204),
+    "mediumvioletred" => Colour.new(red: 199, green: 21, blue: 133),
+    "midnightblue" => Colour.new(red: 25, green: 25, blue: 112),
+    "mintcream" => Colour.new(red: 245, green: 255, blue: 250),
+    "mistyrose" => Colour.new(red: 255, green: 228, blue: 225),
+    "moccasin" => Colour.new(red: 255, green: 228, blue: 181),
+    "navajowhite" => Colour.new(red: 255, green: 222, blue: 173),
+    "navy" => Colour.new(red: 0, green: 0, blue: 128),
+    "oldlace" => Colour.new(red: 253, green: 245, blue: 230),
+    "olive" => Colour.new(red: 128, green: 128, blue: 0),
+    "olivedrab" => Colour.new(red: 107, green: 142, blue: 35),
+    "orange" => Colour.new(red: 255, green: 165, blue: 0),
+    "orangered" => Colour.new(red: 255, green: 69, blue: 0),
+    "orchid" => Colour.new(red: 218, green: 112, blue: 214),
+    "palegoldenrod" => Colour.new(red: 238, green: 232, blue: 170),
+    "palegreen" => Colour.new(red: 152, green: 251, blue: 152),
+    "paleturquoise" => Colour.new(red: 175, green: 238, blue: 238),
+    "palevioletred" => Colour.new(red: 219, green: 112, blue: 147),
+    "papayawhip" => Colour.new(red: 255, green: 239, blue: 213),
+    "peachpuff" => Colour.new(red: 255, green: 218, blue: 185),
+    "peru" => Colour.new(red: 205, green: 133, blue: 63),
+    "pink" => Colour.new(red: 255, green: 192, blue: 203),
+    "plum" => Colour.new(red: 221, green: 160, blue: 221),
+    "powderblue" => Colour.new(red: 176, green: 224, blue: 230),
+    "purple" => Colour.new(red: 128, green: 0, blue: 128),
+    "rebeccapurple" => Colour.new(red: 102, green: 51, blue: 153),
+    "red" => Colour.new(red: 255, green: 0, blue: 0),
+    "rosybrown" => Colour.new(red: 188, green: 143, blue: 143),
+    "royalblue" => Colour.new(red: 65, green: 105, blue: 225),
+    "saddlebrown" => Colour.new(red: 139, green: 69, blue: 19),
+    "salmon" => Colour.new(red: 250, green: 128, blue: 114),
+    "sandybrown" => Colour.new(red: 244, green: 164, blue: 96),
+    "seagreen" => Colour.new(red: 46, green: 139, blue: 87),
+    "seashell" => Colour.new(red: 255, green: 245, blue: 238),
+    "sienna" => Colour.new(red: 160, green: 82, blue: 45),
+    "silver" => Colour.new(red: 192, green: 192, blue: 192),
+    "skyblue" => Colour.new(red: 135, green: 206, blue: 235),
+    "slateblue" => Colour.new(red: 106, green: 90, blue: 205),
+    "slategray" => Colour.new(red: 112, green: 128, blue: 144),
+    "slategrey" => Colour.new(red: 112, green: 128, blue: 144),
+    "snow" => Colour.new(red: 255, green: 250, blue: 250),
+    "springgreen" => Colour.new(red: 0, green: 255, blue: 127),
+    "steelblue" => Colour.new(red: 70, green: 130, blue: 180),
+    "tan" => Colour.new(red: 210, green: 180, blue: 140),
+    "teal" => Colour.new(red: 0, green: 128, blue: 128),
+    "thistle" => Colour.new(red: 216, green: 191, blue: 216),
+    "tomato" => Colour.new(red: 255, green: 99, blue: 71),
+    "turquoise" => Colour.new(red: 64, green: 224, blue: 208),
+    "violet" => Colour.new(red: 238, green: 130, blue: 238),
+    "wheat" => Colour.new(red: 245, green: 222, blue: 179),
+    "white" => Colour.new(red: 255, green: 255, blue: 255),
+    "whitesmoke" => Colour.new(red: 245, green: 245, blue: 245),
+    "yellow" => Colour.new(red: 255, green: 255, blue: 0),
+    "yellowgreen" => Colour.new(red: 154, green: 205, blue: 50)
+  }.freeze
+  private_constant :COLOUR_NAMES
+
+  NAMES = COLOUR_NAMES.keys.sort.freeze
+  private_constant :NAMES
+end

data/lib/blinkstick/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Blinkstick
+  # Base class for every error this gem raises on purpose.
+  class Error < StandardError; end
+
+  # Raised when no BlinkStick matches the requested serial or index.
+  class NotFoundError < Error; end
+
+  # Raised when another program has seized the stick (macOS only).
+  class BusyError < Error; end
+
+  # Raised when the operating system refuses access to the device.
+  class PermissionError < Error; end
+
+  # Raised when opening a stick whose model is not recognised.
+  class UnsupportedModelError < Error; end
+
+  # Raised when using a device after it has been closed.
+  class ClosedError < Error; end
+
+  # Raised when the stick is unplugged or stops responding mid-use.
+  class DisconnectedError < Error; end
+
+  # Raised when a value cannot be turned into a {Colour}.
+  class InvalidColourError < ArgumentError; end
+end

data/lib/blinkstick/model.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Blinkstick
+  # USB vendor ID shared by every BlinkStick model.
+  VENDOR_ID = 0x20A0
+
+  # USB product ID shared by every BlinkStick model.
+  PRODUCT_ID = 0x41E5
+
+  # A BlinkStick product, described by its name and addressable LED count.
+  Model = Data.define(:name, :leds) do
+    # @return [Boolean] false only for {UNKNOWN}, which can be listed but not opened
+    def supported?
+      self != Model::UNKNOWN
+    end
+  end
+
+  # The BlinkStick Nano: two LEDs.
+  Model::NANO = Model.new(name: "Nano", leds: 2)
+
+  # The BlinkStick Square: eight LEDs.
+  Model::SQUARE = Model.new(name: "Square", leds: 8)
+
+  # Any other stick: listed, but refused by {Blinkstick.open}. It has no LEDs here.
+  Model::UNKNOWN = Model.new(name: "unknown", leds: 0)
+
+  # Maps [serial major version, USB bcdDevice] to a {Model}. A Square
+  # (BS073788-3.1) reports 0x0201, so that value is not a Strip here.
+  MODELS = {
+    ["3", 0x0202] => Model::NANO,
+    ["3", 0x0201] => Model::SQUARE
+  }.freeze
+  private_constant :MODELS
+
+  # Identifies an attached BlinkStick. It holds no OS path or handle.
+  Info = Data.define(:serial, :version, :manufacturer, :product, :model) do
+    # @param serial [String] for example "BS072777-3.0"
+    # @param manufacturer [String]
+    # @param product [String]
+    # @param release [Integer] the USB bcdDevice value
+    # @return [Info]
+    def self.from(serial:, manufacturer:, product:, release:)
+      _, _, version = serial.partition("-")
+      major, = version.split(".", 2)
+      new(serial: serial, version: version, manufacturer: manufacturer, product: product,
+          model: MODELS.fetch([major, release], Model::UNKNOWN))
+    end
+  end
+end

data/lib/blinkstick/report.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Blinkstick
+  # Builds the HID feature report bytes the device understands.
+  #
+  # @api private
+  module Report
+    # Report ID of the LED frame.
+    FRAME_ID = 6
+
+    # Frame size in bytes: ID, channel, then 8 x (G, R, B).
+    FRAME_SIZE = 26
+
+    # LEDs addressable in one frame.
+    FRAME_LEDS = 8
+
+    # Builds report 6 for channel 0. The device wants each LED as G, R, B and
+    # slots beyond the given colours are zero.
+    #
+    # @param colours [Array<Colour>] at most {FRAME_LEDS}
+    # @return [String] frozen binary String of {FRAME_SIZE} bytes
+    # @raise [ArgumentError] when given more than {FRAME_LEDS} colours
+    def self.frame(colours)
+      raise ArgumentError, "at most #{FRAME_LEDS} colours, got #{colours.size}" if colours.size > FRAME_LEDS
+
+      bytes = [FRAME_ID, 0] + colours.flat_map { |c| [c.green, c.red, c.blue] }
+      bytes.fill(0, bytes.size...FRAME_SIZE).pack("C*").freeze
+    end
+  end
+end

data/lib/blinkstick/stick.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Blinkstick
+  # An open BlinkStick. Get one from {Blinkstick.open}.
+  #
+  # A Stick is safe to share between threads: a Mutex serialises every
+  # report sent to the device. A stick that is garbage collected without
+  # {#close} still releases its OS handle, but call {#close} (or use the
+  # block form of {Blinkstick.open}) rather than relying on that.
+  class Stick
+    # @return [Info] the identity of this stick
+    attr_reader :info
+
+    # @api private
+    # @param handle [#write_feature, #close] an open backend handle
+    # @param info [Info]
+    def initialize(handle, info)
+      @handle = handle
+      @info = info
+      @mutex = Mutex.new
+      @closed = false
+      ObjectSpace.define_finalizer(self, self.class.releaser(handle))
+    end
+
+    # Builds the finaliser here, not in an instance method, so it holds the
+    # handle only and the Stick itself can still be collected.
+    #
+    # @api private
+    # @param handle [#close]
+    # @return [Proc]
+    def self.releaser(handle)
+      proc do
+        handle.close
+      rescue Error
+        nil
+      end
+    end
+
+    # Sets every LED to one colour.
+    #
+    # @param colour [Colour, String, Symbol, Array<Integer>] anything {Colour.parse} takes
+    # @raise [InvalidColourError] before anything is sent, when colour is not a colour
+    # @raise [ClosedError] after {#close}
+    # @raise [DisconnectedError] when the stick stops responding
+    def colour=(colour)
+      write(Report.frame([Colour.parse(colour)] * info.model.leds))
+    end
+
+    # Turns every LED off.
+    #
+    # @return [void]
+    # @raise [ClosedError] after {#close}
+    # @raise [DisconnectedError] when the stick stops responding
+    def off
+      self.colour = Colour::OFF
+      nil
+    end
+
+    # Releases the stick. Calling it again does nothing.
+    #
+    # @return [void]
+    def close
+      @mutex.synchronize do
+        next if @closed
+
+        @closed = true
+        ObjectSpace.undefine_finalizer(self)
+        @handle.close
+      end
+      nil
+    end
+
+    # @return [Boolean] true once {#close} has been called
+    def closed?
+      @closed
+    end
+
+    private
+
+    # Holds the lock across every attempt, so reports from other threads
+    # cannot land in between.
+    def write(report)
+      @mutex.synchronize do
+        raise ClosedError, "#{info.serial} is closed" if @closed
+
+        transfer(report)
+      end
+    end
+
+    # Tries up to Backend::ATTEMPTS times while the handle says the failure
+    # is transient. The caller must hold the lock.
+    def transfer(report)
+      attempt = 0
+      begin
+        attempt += 1
+        @handle.write_feature(report)
+      rescue Backend::TransferFailed
+        retry if attempt < Backend::ATTEMPTS
+
+        raise DisconnectedError, "#{info.serial} stopped responding: #{attempt} writes failed in a row"
+      end
+    end
+  end
+end

data/lib/blinkstick/version.rb

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

data/lib/blinkstick.rb

@@ -1,7 +1,78 @@
 # frozen_string_literal: true
 
 require_relative "blinkstick/version"
+require_relative "blinkstick/errors"
+require_relative "blinkstick/colour"
+require_relative "blinkstick/model"
+require_relative "blinkstick/report"
+require_relative "blinkstick/stick"
 
-# A placeholder that reserves the gem name and does nothing yet.
+# Finds and drives BlinkStick Nano and Square USB LED sticks on macOS and Linux.
+#
+# Requiring the gem touches no device; the OS backend loads on first use.
+#
+#   Blinkstick.open do |stick|
+#     stick.colour = :cornflowerblue
+#   end
 module Blinkstick
+  # Loaded on first use, so requiring the gem touches no device or backend.
+  autoload :Backend, "blinkstick/backend"
+
+  # Lists every attached BlinkStick, including models this gem cannot open
+  # (their {Info#model} is {Model::UNKNOWN}).
+  #
+  # @return [Array<Info>]
+  # @raise [Error] when the OS cannot list devices
+  def self.list
+    Backend.current.list.map { |device| info_for(device) }
+  end
+
+  # Opens a BlinkStick: the one with the given serial, or else the first one
+  # found. If the first one found is an unknown model this raises, even when
+  # a supported stick is also attached; pass a serial from {list} to choose.
+  #
+  # Without a block the caller must {Stick#close} the stick. With a block,
+  # like File.open, the stick is yielded, closed afterwards even if the
+  # block raises, and the block's value is returned.
+  #
+  # @param serial [String, nil] for example "BS072777-3.0"
+  # @yieldparam stick [Stick]
+  # @return [Stick, Object] the stick, or the block's value
+  # @raise [NotFoundError] when no stick (or none with that serial) is attached
+  # @raise [UnsupportedModelError] when the stick's model is unknown
+  # @raise [BusyError] when another program has seized the stick
+  # @raise [PermissionError] when the OS refuses access
+  def self.open(serial: nil)
+    stick = open_stick(serial)
+    return stick unless block_given?
+
+    begin
+      yield stick
+    ensure
+      stick.close
+    end
+  end
+
+  # Checks the model before opening, so an unknown stick is never opened.
+  def self.open_stick(serial)
+    backend = Backend.current
+    device = find(backend.list, serial)
+    info = info_for(device)
+    raise UnsupportedModelError, "#{info.serial} is a model this gem does not support" unless info.model.supported?
+
+    Stick.new(backend.open(device), info)
+  end
+
+  def self.find(devices, serial)
+    return devices.first || raise(NotFoundError, "no BlinkStick attached") if serial.nil?
+
+    devices.find { |device| device.serial == serial } || raise(NotFoundError, "no BlinkStick with serial #{serial}")
+  end
+
+  def self.info_for(device)
+    Info.from(serial: device.serial, manufacturer: device.manufacturer, product: device.product,
+              release: device.release)
+  end
+
+  private_class_method :open_stick, :find, :info_for
 end