ruby-blinkstick 0.2.0 → 0.3.0

data/lib/blinkstick/stick.rb

@@ -8,18 +8,35 @@ module Blinkstick
   # stick (nothing is cached). 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.
+  #
+  # A stick that is unplugged and plugged back in is found again by its
+  # serial on the next call, which repaints the last frame written before
+  # carrying on. Only when that fails does a call raise {DisconnectedError}.
   class Stick
+    include Eeprom
+    include Effects
+    include Handover
+    include Lighting
+    include Reconnect
+
     # @return [Info] the identity of this stick
     attr_reader :info
 
     # @api private
     # @param handle [#write_feature, #read_feature, #close] an open backend handle
     # @param info [Info]
-    def initialize(handle, info)
+    # @param reopen [#call, nil] returns a fresh handle for this stick or
+    #   raises an {Error}; nil means the stick never reconnects
+    def initialize(handle, info, reopen: nil)
       @handle = handle
       @info = info
+      @reopen = reopen
+      @reconnected = false
       @mutex = Mutex.new
       @closed = false
+      @limit = 255
+      @inverse = false
+      @last = nil
       ObjectSpace.define_finalizer(self, self.class.releaser(handle))
     end
 
@@ -44,9 +61,9 @@ module Blinkstick
     # @raise [ClosedError] after {#close}
     # @raise [BusyError] when another program holds the stick mid-transfer
     # @raise [PermissionError] when the system refuses access mid-transfer
-    # @raise [DisconnectedError] when the stick stops responding
+    # @raise [DisconnectedError] when the stick stops responding and reconnecting to it fails
     def colour=(colour)
-      write(Report.frame([Colour.parse(colour)] * info.model.leds))
+      write_frame([Colour.parse(colour)] * info.model.leds)
     end
 
     # Sets one LED, leaving the others as they are.
@@ -59,11 +76,10 @@ module Blinkstick
     # @raise [ClosedError] after {#close}
     # @raise [BusyError] when another program holds the stick mid-transfer
     # @raise [PermissionError] when the system refuses access mid-transfer
-    # @raise [DisconnectedError] when the stick stops responding
+    # @raise [DisconnectedError] when the stick stops responding and reconnecting to it fails
     def []=(index, colour)
-      parsed = Colour.parse(colour)
       check_index(index)
-      write(Report.led(index, parsed))
+      write_led(index, Colour.parse(colour))
       colour
     end
 
@@ -76,7 +92,7 @@ module Blinkstick
     # @raise [ClosedError] after {#close}
     # @raise [BusyError] when another program holds the stick mid-transfer
     # @raise [PermissionError] when the system refuses access mid-transfer
-    # @raise [DisconnectedError] when the stick stops responding
+    # @raise [DisconnectedError] when the stick stops responding and reconnecting to it fails
     def frame=(colours)
       list = Array.try_convert(colours)
       raise TypeError, "frame must be an Array of colours, got #{colours.class}" if list.nil?
@@ -86,33 +102,7 @@ module Blinkstick
         raise ArgumentError, "a #{model.name} has #{model.leds} LEDs, got #{list.size} colours"
       end
 
-      write(Report.frame(list.map { |colour| Colour.parse(colour) }))
-    end
-
-    # Reads every LED back from the stick. Nothing is cached: each call asks
-    # the stick.
-    #
-    # @return [Array<Colour>] frozen, one per LED of the model
-    # @raise [ClosedError] after {#close}
-    # @raise [BusyError] when another program holds the stick mid-transfer
-    # @raise [PermissionError] when the system refuses access mid-transfer
-    # @raise [DisconnectedError] when the stick stops responding
-    def frame
-      Report.decode_frame(read(Report::FRAME_ID, Report::FRAME_SIZE), info.model.leds)
-    end
-
-    # Reads one LED back from the stick, by reading the whole frame.
-    #
-    # @param index [Integer] LED index, 0 to one less than the model's LED count (a Nano takes 0 or 1, a Square 0 to 7)
-    # @return [Colour]
-    # @raise [IndexError] before anything is sent, when index is not an Integer within the model's LEDs
-    # @raise [ClosedError] after {#close}
-    # @raise [BusyError] when another program holds the stick mid-transfer
-    # @raise [PermissionError] when the system refuses access mid-transfer
-    # @raise [DisconnectedError] when the stick stops responding
-    def [](index)
-      check_index(index)
-      frame.fetch(index)
+      write_frame(list.map { |colour| Colour.parse(colour) })
     end
 
     # Reads the LED mode from the stick.
@@ -122,7 +112,7 @@ module Blinkstick
     # @raise [ClosedError] after {#close}
     # @raise [BusyError] when another program holds the stick mid-transfer
     # @raise [PermissionError] when the system refuses access mid-transfer
-    # @raise [DisconnectedError] when the stick stops responding
+    # @raise [DisconnectedError] when the stick stops responding and reconnecting to it fails
     def mode
       Report.decode_mode(read(Report::MODE_ID, Report::MODE_SIZE))
     end
@@ -135,7 +125,7 @@ module Blinkstick
     # @raise [ClosedError] after {#close}
     # @raise [BusyError] when another program holds the stick mid-transfer
     # @raise [PermissionError] when the system refuses access mid-transfer
-    # @raise [DisconnectedError] when the stick stops responding
+    # @raise [DisconnectedError] when the stick stops responding and reconnecting to it fails
     def info_block(number)
       Report.decode_info_block(read(Report.info_block_id(number), Report::INFO_BLOCK_SIZE))
     end
@@ -146,13 +136,14 @@ module Blinkstick
     # @raise [ClosedError] after {#close}
     # @raise [BusyError] when another program holds the stick mid-transfer
     # @raise [PermissionError] when the system refuses access mid-transfer
-    # @raise [DisconnectedError] when the stick stops responding
+    # @raise [DisconnectedError] when the stick stops responding and reconnecting to it fails
     def off
       self.colour = Colour::OFF
       nil
     end
 
-    # Releases the stick. Calling it again does nothing.
+    # Releases the stick. Calling it again does nothing, and it succeeds on a
+    # stick that was unplugged and not found again.
     #
     # @return [void]
     def close
@@ -161,7 +152,7 @@ module Blinkstick
 
         @closed = true
         ObjectSpace.undefine_finalizer(self)
-        @handle.close
+        @handle&.close
       end
       nil
     end
@@ -191,39 +182,18 @@ module Blinkstick
     #
     # @return [String] at least size bytes, the first being report_id
     def read(report_id, size)
-      transfer("reads") do
-        reply = @handle.read_feature(report_id, size)
-        unless reply.bytesize >= size && reply.getbyte(0) == report_id
-          raise Backend::TransferFailed,
-                "report #{report_id}: got #{reply.bytesize} of #{size} bytes, ID #{reply.getbyte(0).inspect}"
-        end
-
-        reply
-      end
+      transfer("reads") { fetch(report_id, size) }
     end
 
-    # Holds the lock across every attempt, so transfers from other threads
-    # cannot land in between.
-    def transfer(what, &)
-      @mutex.synchronize do
-        raise ClosedError, "#{info.serial} is closed" if @closed
-
-        with_retries(what, &)
+    # One read attempt, checked. The caller holds the lock.
+    def fetch(report_id, size)
+      reply = @handle.read_feature(report_id, size)
+      unless reply.bytesize >= size && reply.getbyte(0) == report_id
+        raise Backend::TransferFailed,
+              "report #{report_id}: got #{reply.bytesize} of #{size} bytes, ID #{reply.getbyte(0).inspect}"
       end
-    end
 
-    # Runs the block up to Backend::ATTEMPTS times while it raises
-    # TransferFailed. The caller must hold the lock.
-    def with_retries(what)
-      attempt = 0
-      begin
-        attempt += 1
-        yield
-      rescue Backend::TransferFailed
-        retry if attempt < Backend::ATTEMPTS
-
-        raise DisconnectedError, "#{info.serial} stopped responding: #{attempt} #{what} failed in a row"
-      end
+      reply
     end
   end
 end

data/lib/blinkstick/version.rb

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

data/lib/blinkstick.rb

@@ -5,7 +5,14 @@ require_relative "blinkstick/errors"
 require_relative "blinkstick/colour"
 require_relative "blinkstick/model"
 require_relative "blinkstick/report"
+require_relative "blinkstick/stick/eeprom"
+require_relative "blinkstick/stick/effects"
+require_relative "blinkstick/stick/handover"
+require_relative "blinkstick/stick/lighting"
+require_relative "blinkstick/stick/reconnect"
 require_relative "blinkstick/stick"
+require_relative "blinkstick/names"
+require_relative "blinkstick/cancellation"
 
 # Finds and drives BlinkStick Nano and Square USB LED sticks on macOS and Linux.
 #
@@ -21,29 +28,47 @@ module Blinkstick
   # Lists every attached BlinkStick, including models this gem cannot open
   # (their {Info#model} is {Model::UNKNOWN}).
   #
-  # @return [Array<Info>]
+  # With +names: true+ each stick is opened briefly to read its name and then
+  # closed, so a stick another program holds shows as busy with an empty name.
+  # Unknown models are opened too.
+  #
+  # @param names [Boolean] read each stick's name
+  # @return [Array<Info>, Array<NamedInfo>] NamedInfo when +names+ is true
   # @raise [Error] when the OS cannot list devices
-  def self.list
+  def self.list(names: false)
+    return list_named if names
+
     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.
+  # Opens a BlinkStick: the one with the given serial, the one with the given
+  # name, 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.
   #
+  # By name, every stick is opened in turn and its name compared byte for
+  # byte; sticks that cannot be opened or read are skipped, and the ones that
+  # do not match are closed.
+  #
   # @param serial [String, nil] for example "BS072777-3.0"
+  # @param name [String, nil] a name stored on the stick, see {Stick#name=}
   # @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 [ArgumentError] when both +serial+ and +name+ are given, or +name+ is empty
+  # @raise [TypeError] when +name+ is not a String
+  # @raise [NotFoundError] when no stick (or none with that serial or name) is attached;
+  #   for a name the message says why each skipped stick was skipped
+  # @raise [DuplicateNameError] when more than one stick has that name
   # @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)
+  def self.open(serial: nil, name: nil)
+    check_selectors(serial, name)
+    stick = name.nil? ? open_stick(serial) : open_named(name)
     return stick unless block_given?
 
     begin
@@ -56,17 +81,55 @@ module Blinkstick
   # 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?
+    build_stick(backend, find(backend.list, serial))
+  end
+
+  # The one place a Stick for a user is built, however it was found. Checks
+  # the model first, then takes the handle from the block (when the caller
+  # already holds one open) or opens the device, and gives the Stick a way
+  # to find the device again after an unplug.
+  def self.build_stick(backend, device)
+    info = supported_info(device)
+    handle = block_given? ? yield : backend.open(device)
+    Stick.new(handle, info, reopen: reopener(device.serial))
+  end
+
+  # A callable that relists through the current backend and opens the one
+  # stick with this serial, after the same model check {Blinkstick.open} makes. An
+  # empty serial, or one more than one stick shares, could reopen the wrong
+  # stick, so those never reconnect.
+  def self.reopener(serial)
+    return -> { raise DisconnectedError, "this stick has no serial, so it cannot be found again" } if serial.empty?
 
-    Stick.new(backend.open(device), info)
+    lambda do
+      backend = Backend.current
+      device = only_device(backend.list, serial)
+      supported_info(device)
+      backend.open(device)
+    end
+  end
+
+  # The one device with this serial, for {reopener}.
+  def self.only_device(devices, serial)
+    matches = devices.select { |device| device.serial == serial }
+    raise NotFoundError, "no BlinkStick with serial #{serial.inspect}" if matches.empty?
+    raise DisconnectedError, "serial #{serial.inspect} is ambiguous: #{matches.size} sticks have it" if matches.size > 1
+
+    matches.first
+  end
+
+  # The model check, made before anything is opened.
+  def self.supported_info(device)
+    info_for(device).tap do |info|
+      raise UnsupportedModelError, "#{info.serial} is a model this gem does not support" unless info.model.supported?
+    end
   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}")
+    devices.find { |device| device.serial == serial } ||
+      raise(NotFoundError, "no BlinkStick with serial #{serial.inspect}")
   end
 
   def self.info_for(device)
@@ -74,5 +137,5 @@ module Blinkstick
               release: device.release)
   end
 
-  private_class_method :open_stick, :find, :info_for
+  private_class_method :open_stick, :build_stick, :reopener, :only_device, :supported_info, :find, :info_for
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-blinkstick
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Keith Bawden
@@ -29,10 +29,12 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.17.3
-description: Find, open and set the colour of BlinkStick Nano and Square USB LEDs
-  from Ruby, on macOS and Linux. Lists attached sticks, opens one by serial, sets
-  every LED from hex, r,g,b or CSS colour names, and turns them off. Nothing to install
-  but the gem. Unofficial, and not affiliated with Agile Innovative.
+description: Find, open and drive BlinkStick Nano and Square USB LEDs from Ruby, on
+  macOS and Linux. Sets every LED or one LED from hex, r,g,b or CSS colour names,
+  reads them back, names a stick and opens it by name, writes the info blocks and
+  mode, limits brightness, runs cancellable blink, pulse and morph effects, and reconnects
+  after an unplug. Nothing to install but the gem. Unofficial, and not affiliated
+  with Agile Innovative.
 email:
 - keith@arrix.com.au
 executables: []
@@ -47,12 +49,19 @@ files:
 - lib/blinkstick/backend.rb
 - lib/blinkstick/backend/hidraw.rb
 - lib/blinkstick/backend/iokit.rb
+- lib/blinkstick/cancellation.rb
 - lib/blinkstick/colour.rb
 - lib/blinkstick/colour_names.rb
 - lib/blinkstick/errors.rb
 - lib/blinkstick/model.rb
+- lib/blinkstick/names.rb
 - lib/blinkstick/report.rb
 - lib/blinkstick/stick.rb
+- lib/blinkstick/stick/eeprom.rb
+- lib/blinkstick/stick/effects.rb
+- lib/blinkstick/stick/handover.rb
+- lib/blinkstick/stick/lighting.rb
+- lib/blinkstick/stick/reconnect.rb
 - lib/blinkstick/version.rb
 - udev/60-blinkstick.rules
 homepage: https://github.com/bawdo/ruby-blinkstick
@@ -79,6 +88,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Find and light BlinkStick Nano and Square USB LEDs from Ruby, on macOS and
-  Linux.
+summary: 'Drive BlinkStick Nano and Square USB LEDs from Ruby: names, effects and
+  reconnect.'
 test_files: []