ruby-blinkstick 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbeec7298582de4220e66562a9fadfd994fc540c920b6af2da8ea0b91cbc7cee
-  data.tar.gz: d016a0be08f195f84e43a1e663a7b70c49d8174d4a1fba2b1332cc70c6159c7b
+  metadata.gz: 20e16b5618237efd0d8ce0ba62eeb126ef7e6121ea4266327139373d4d8f30d2
+  data.tar.gz: 0a5d0d90e43cb56aba4c0e49c61ff7092f8626aa9ae6ec278799497d18d3dbde
 SHA512:
-  metadata.gz: c66054616d8981e5c256a19a27f88c0e4bf6ee4046f86e3a554eea7b34cda60f9546a93cf19a9ba8e43723f888d4b6af88dd3948cf7bd9ded0e549d14d29f027
-  data.tar.gz: a1d96c324d7793c6c4cf4a1193f97e07de2a2f162bd0aaff4a6589b95649fc76234b2d0c535b3467874a2fe0347b9198669194d5c3b92fd635bdc5fb0e08dd74
+  metadata.gz: 04b8b8e8a6ceea769d01c8c6bdfc0d6d2e054728c3168396fceeb91b283157adeaaad1a491409a75526d0167634fe8523d33bcb0abe82f5709d9c32b6a9d3fe9
+  data.tar.gz: c4b50c14b36758a465fc7b34884a320634689dc6b63dbb0a07fc4666d14854aff9b6f752c2c83023296bde721ac7a23e77326a5fde25425f6ea7de0e80a1cfbb

data/CAPABILITIES.md

@@ -16,22 +16,22 @@ Features built into the BlinkStick firmware.
 |---|---|---|---|---|---|
 | List attached sticks | yes | yes | `Blinkstick.list` | 0.1.0 | Enumerate every attached stick |
 | Open the first stick or one by serial | yes | yes | `Blinkstick.open`, `Blinkstick.open(serial:)` | 0.1.0 | Open the first stick found, or a stick by its serial |
-| Name a stick and open it by name | no | no |  | not yet | Store a name, read it back, open and list sticks by name. Stored in info block 1 |
+| Name a stick and open it by name | yes | yes | `stick.name`, `stick.name =`, `Blinkstick.open(name:)`, `Blinkstick.list(names: true)` | 0.3.0 | Stored in info block 1. Writes EEPROM. Two sticks with one name raise `DuplicateNameError` |
 | Several sticks open at once | yes | yes | one `Stick` per `Blinkstick.open` | 0.1.0 |  |
-| Serial and firmware version | yes | yes | `info.serial`, `info.version` | 0.1.0 | Read from the device info |
+| Serial and firmware version | yes | yes | `info.serial`, `info.version`, `info.release` | 0.1.0 | Read from the device info. `info.release` (the USB release number) since 0.3.0 |
 | Manufacturer and product strings | yes | yes | `info.manufacturer`, `info.product` | 0.1.0 | Read from the device info |
 | Set all LEDs | yes | yes | `stick.colour =`, `stick.off` | 0.1.0 | Set every LED to one colour, or turn them off |
 | Set one LED | yes | yes | `stick[i] = colour` | 0.2.0 | Set a single LED by index, using report 5 |
 | Set every LED at once | yes | yes | `stick.frame = colours` | 0.2.0 | Write a whole frame in one report |
 | Read LED values back | yes | yes | `stick.frame`, `stick[i]` | 0.2.0 | Read the whole frame or a single LED |
-| Info blocks 1 and 2 | yes | yes | `stick.info_block(n)` | 0.2.0 | 32 bytes each, stored in EEPROM. Read only; writing comes later |
+| Info blocks 1 and 2 | yes | yes | `stick.info_block(n)`, `stick.write_info_block(n, bytes)` | 0.2.0 | 32 bytes each, stored in EEPROM. Reading since 0.2.0, writing (reports 2 and 3) since 0.3.0. Writes checked on a Nano and a Square on macOS and Linux by the manual EEPROM check |
 | Set one LED directly (report 5) | yes | yes | `stick[i] = colour` | 0.2.0 | `[5, channel, index, R, G, B]`, RGB order (the frame is GRB). Works in modes 2 and 3. The channel byte is ignored and the index is not range checked |
 | Read device mode (report 4) | yes | yes | `stick.mode` | 0.2.0 | `[4, mode]`. Both read mode 2 |
-| Set device mode (report 4) | no | no |  | not yet | Stored in EEPROM, blocks about 50 ms, skipped when the mode is unchanged, takes effect without a replug. 2 to 3 to 2 verified on both |
-| Mode 2, WS2812 | no | no |  | not yet | The mode both are in, and the one every LED feature here needs. Probably the factory default |
-| Mode 3, WS2812 mirror | no | no |  | not yet | Changes only report 1, whose colour goes to every LED. Reports 5 and 6 behave as in mode 2 |
-| Modes 0 and 1, normal and inverse | n/a | n/a |  | n/a | For the BlinkStick Pro's RGB outputs. Upstream reports a Nano in mode 1 going dark until replugged. Setting the mode refuses them |
-| Set LED 0, or every LED in mode 3 (report 1) | no | no |  | not yet | `[1, R, G, B]`, RGB order. Used by other BlinkStick software. Setting LED 0 or all LEDs does the same job in either mode |
+| Set device mode (report 4) | yes | yes | `stick.mode =` | 0.3.0 | Stored in EEPROM, waits for the stick to answer again (12 to 15 ms seen, at most 250 ms), skipped when the mode is unchanged, takes effect without a replug. 2 to 3 to 2 checked on a Nano and a Square on macOS and Linux by the manual EEPROM check |
+| Mode 2, WS2812 | yes | yes | `stick.mode = :ws2812` | 0.3.0 | The mode both are in, and the one every LED feature here needs. Probably the factory default |
+| Mode 3, WS2812 mirror | yes | yes | `stick.mode = :ws2812_mirror` | 0.3.0 | Changes only report 1, whose colour goes to every LED. Reports 5 and 6 behave as in mode 2 |
+| Modes 0 and 1, normal and inverse | n/a | n/a |  | n/a | For the BlinkStick Pro's RGB outputs. Upstream reports a Nano in mode 1 going dark until replugged. `stick.mode =` refuses them with `ArgumentError` |
+| Set LED 0, or every LED in mode 3 (report 1) | yes | yes | `stick[0] =`, `stick.colour =` | n/a | `[1, R, G, B]`, RGB order. Used by other BlinkStick software. Report 1 is never sent: here `stick[0] =` and `stick.colour =` do the same job in either mode |
 | Report 10 | n/a | unknown |  | no | Square only, 2 bytes, reads 00 00. Undocumented; waiting on the manufacturer |
 | LED count setting (report 0x81) | n/a | n/a |  | n/a | BlinkStick Flex only |
 | 16, 32 and 64 LED frames (reports 7 to 9) | n/a | n/a |  | n/a | For longer strips |
@@ -44,14 +44,14 @@ Features this gem adds in software. They work the same on every supported device
 |---|---|---|---|
 | Model detection | `info.model` | 0.1.0 | From the serial and USB release number |
 | Colour from hex or `r,g,b` | `Colour.parse` | 0.1.0 | Parse a colour from hex, with or without the `#`, or `r,g,b` |
-| Brightness limit |  | not yet | Cap the brightness of every colour written |
-| Blink, pulse and morph |  | not yet | Cancellable |
+| Brightness limit | `stick.brightness_limit`, `stick.brightness_limit =` | 0.3.0 | Cap the brightness of every colour written from then on. Per `Stick`, not stored on the device |
+| Blink, pulse and morph | `stick.blink`, `stick.pulse`, `stick.morph`, `Blinkstick::Cancellation` | 0.3.0 | Cancellable. Return `true` when finished and `false` when cancelled |
 | CSS colour names | `Colour.parse` | 0.1.0 | All 148 from CSS Color Level 4 |
 | List CSS colour names | `Colour.names` | 0.1.0 | Sorted, for shell completion |
 | Colour as hex | `Colour#hex`, `Colour#to_s` | 0.1.0 | Lower case `#rrggbb` |
-| Random colour |  | not yet | Any colour, or a vivid one |
-| Inverse colours |  | not yet | Invert a colour or the whole frame. Not the firmware inverse mode |
-| Reconnect after unplug |  | not yet | Automatic, repaints the last frame |
+| Random colour | `Colour.random`, `Colour.random(vivid: true)` | 0.3.0 | Any colour, or a vivid one |
+| Inverse colours | `Colour#inverse`, `stick.inverse =`, `stick.inverse?` | 0.3.0 | Invert a colour or the whole frame. Not the firmware inverse mode |
+| Reconnect after unplug | automatic | 0.3.0 | Repaints the last frame. Raises `DisconnectedError` when it fails. Never moves onto a different stick |
 
 ## Platforms
 

data/CHANGELOG.md

@@ -6,6 +6,25 @@ All notable changes to this project are recorded here. The format follows
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-29
+
+### Added
+
+- Names: `Stick#name` and `Stick#name=` (stored in info block 1), `Blinkstick.open(name:)` and `Blinkstick.list(names: true)`, which returns `NamedInfo` values. `DuplicateNameError` is raised when two sticks share a name.
+- `Stick#write_info_block` writes info block 1 or 2 (EEPROM).
+- `Stick#mode=` sets the mode to `:ws2812` or `:ws2812_mirror` (EEPROM), and skips the write when the stick is already in it. After a write it waits until the stick answers with the new mode (it stops answering for 12 to 15 ms after a mode write), raising `DisconnectedError` after 250 ms. The Pro modes are refused.
+- `Stick#brightness_limit` and `Stick#brightness_limit=` cap the brightness of every colour written.
+- `Stick#inverse?`, `Stick#inverse=` and `Colour#inverse` flip colours for LEDs wired so 255 is off.
+- `Colour.random` and `Colour.random(vivid: true)`.
+- `Stick#blink`, `Stick#pulse`, `Stick#morph` and `Blinkstick::Cancellation`. Effects return `true` when they finish and `false` when cancelled.
+- `Info#release`, the USB release number the model is worked out from. It is the last member and defaults to `nil`, so building an `Info` the 0.2.0 way still works.
+- Reconnect after an unplug: a stick that stops answering is found again by its serial and the last frame is repainted. A stick whose serial is shared with another attached stick never reconnects.
+
+### Changed
+
+- `Stick#[]=` checks the index before the colour, so a call with both wrong raises `IndexError`. The first `[]=` on a fresh `Stick` reads the frame once.
+- `DisconnectedError` now means the stick stopped responding and reconnecting to it failed, not just that three attempts failed.
+
 ## [0.2.0] - 2026-10-28
 
 ### Added

data/README.md

@@ -12,11 +12,12 @@ of BlinkStick.
 
 ## Status
 
-This gem finds a BlinkStick Nano or Square, opens it, sets every LED to a colour, sets one
-LED or the whole frame, reads LEDs, the mode and the info blocks back, and turns them off, on
-macOS and Linux. Effects, setting the mode and writing the info blocks are still to come. The
-per LED, frame and reading calls arrive in 0.2.0. [CAPABILITIES.md](CAPABILITIES.md) lists
-what is supported and the Ruby method for each feature.
+This gem finds a BlinkStick Nano or Square, opens it by serial or by name, sets every LED to a
+colour, sets one LED or the whole frame, reads LEDs, the mode and the info blocks back, and
+turns them off, on macOS and Linux. It can also name a stick, write the info blocks, set the
+mode, limit the brightness, invert the output, pick random colours, run cancellable blink,
+pulse and morph effects, and reconnect after an unplug. [CAPABILITIES.md](CAPABILITIES.md)
+lists what is supported and the Ruby method for each feature.
 
 ## Install
 
@@ -50,7 +51,7 @@ require "blinkstick"
 Blinkstick.list
 # => [#<data Blinkstick::Info serial="BS072777-3.0", version="3.0",
 #      manufacturer="Agile Innovative Ltd", product="BlinkStick",
-#      model=#<data Blinkstick::Model name="Nano", leds=2>>]
+#      model=#<data Blinkstick::Model name="Nano", leds=2>, release=514>]
 
 Blinkstick.open do |stick|         # the first stick; the block form closes it, like File.open
   stick.colour = :cornflowerblue   # set every LED
@@ -61,6 +62,12 @@ Blinkstick.open do |stick|         # the first stick; the block form closes it,
   stick.off                        # every LED off
 end
 
+Blinkstick.open(name: "desk") do |stick|  # a stick you have named, see "Writing to the stick's memory"
+  stick.brightness_limit = 128     # every colour written from now on is scaled to half
+  stick.inverse = true             # for LEDs wired so 255 is off; set it before setting LEDs
+  stick.colour = Blinkstick::Colour.random(vivid: true)  # any fully saturated hue
+end
+
 stick = Blinkstick.open(serial: "BS072777-3.0")  # without a block, you close it
 stick.info                         # => Blinkstick::Info
 stick.close
@@ -68,6 +75,8 @@ stick.closed?                      # => true
 
 Blinkstick::Colour.parse("255,136,0").hex   # => "#ff8800"
 Blinkstick::Colour.names.first(3)           # => ["aliceblue", "antiquewhite", "aqua"]
+Blinkstick::Colour.parse("red").inverse     # => #<data Blinkstick::Colour red=0, green=255, blue=255>
+Blinkstick::Colour.random                   # each channel picked from 0 to 255
 ```
 
 A colour can be a CSS colour name (a string or symbol, any case), hex (`#rgb` or `#rrggbb`,
@@ -81,8 +90,9 @@ needs exactly one colour per LED, so a Nano takes 2 and a Square 8. A wrong coun
 before anything is sent.
 
 Failures raise subclasses of `Blinkstick::Error`: `NotFoundError`, `BusyError`,
-`PermissionError`, `UnsupportedModelError`, `ClosedError` and `DisconnectedError`. A bad
-colour raises `Blinkstick::InvalidColourError`, which is an `ArgumentError`.
+`PermissionError`, `UnsupportedModelError`, `ClosedError`, `DisconnectedError` and
+`DuplicateNameError`. A bad colour raises `Blinkstick::InvalidColourError`, which is an
+`ArgumentError`.
 
 ### Reading a stick
 
@@ -105,9 +115,150 @@ end
   trailing NUL bytes removed, as a frozen binary String. Any other number raises
   `ArgumentError`. The bytes are whatever any tool last wrote there, so treat them as
   untrusted input.
-- Nothing in this release writes EEPROM: the mode and info blocks are read only.
-- A read that keeps failing raises `Blinkstick::DisconnectedError`, and a read after `close`
-  raises `ClosedError`, as writes do.
+- A read that keeps failing makes the stick try to reconnect (see "Reconnecting"), and raises
+  `Blinkstick::DisconnectedError` if that fails too. A read after `close` raises `ClosedError`,
+  as writes do.
+
+### Brightness limit and inverse
+
+```ruby
+stick.brightness_limit = 128   # an Integer from 0 to 255; 255, the default, is no limit
+stick.brightness_limit         # => 128
+stick.colour = :white          # sent as 128, 128, 128
+stick.frame.first              # => #<data Blinkstick::Colour red=128, green=128, blue=128>
+
+stick.inverse = true           # sends 255 minus each channel, after the limit
+stick.inverse?                 # => true
+```
+
+- The limit scales every channel of every colour written from then on, as `v * limit / 255`
+  with integer division: `colour=`, `[]=`, `frame=`, `off` and the effects. It does not repaint
+  what is already lit, and reads return what the stick holds, so they show the limited values.
+- `inverse` is for LEDs wired so that 255 is off. Reads flip back, so `frame` and `stick[i]`
+  return the colours you wrote. It does not repaint either, so set it before setting LEDs. It is
+  not the firmware inverse mode (mode 1), which this gem refuses.
+- Both belong to the `Stick` object. They are not stored on the device, and a second `Stick` on
+  the same serial starts with no limit and no inverse.
+
+### Random colours
+
+```ruby
+Blinkstick::Colour.random              # each channel picked from 0 to 255
+Blinkstick::Colour.random(vivid: true) # one of the 1530 fully saturated hues
+```
+
+These use Ruby's `Random`, so they are for pretty lights and nothing security related. Pass
+`random:` (anything with a `rand` method) to make them repeatable in tests.
+
+### Writing to the stick's memory
+
+A stick keeps a name, two 32 byte info blocks and its LED mode in EEPROM. **EEPROM wears out
+with writes**, so set these once and never in a loop. `name=`, `write_info_block` and `mode=`
+write EEPROM; the other calls here only read. An EEPROM call is retried like any transfer, so
+on a flaky connection one call can send the same write up to six times (three attempts, a
+reconnect, three more), as go-blinkstick does. That is one more reason not to call these in a
+loop.
+
+```ruby
+Blinkstick.open do |stick|
+  stick.name = "desk"                    # stored in info block 1
+  stick.name                             # => "desk"
+  stick.write_info_block(2, "my notes")  # padded with zeros to 32 bytes
+  stick.info_block(2)                    # => "my notes"
+  stick.mode = :ws2812_mirror            # reads first, writes only if the mode differs
+end
+
+Blinkstick.open(name: "desk") { |stick| stick.colour = :green }
+
+Blinkstick.list(names: true)
+# => [#<data Blinkstick::NamedInfo info=#<data Blinkstick::Info ...>, name="desk", busy=false>]
+```
+
+- A name is a String of valid UTF-8 with no NUL and at most 32 bytes. `""` clears it. A wrong
+  type raises `TypeError` and a bad value raises `ArgumentError`, before anything is sent.
+  Names are held in info block 1, as the official tools and the Go library do, so writing
+  block 1 changes the name.
+- `Blinkstick.open(name:)` opens each stick in turn, reads its name and keeps the one that
+  matches byte for byte (the others are closed). A stick that cannot be opened or read is
+  skipped. No match raises `NotFoundError` whose message says why each stick was skipped, and
+  two matches raise `DuplicateNameError` naming their serials. `serial:` and `name:` together,
+  or an empty name, raise `ArgumentError`. A match that is a model this gem does not support
+  raises `UnsupportedModelError`.
+- `Blinkstick.list(names: true)` opens every stick briefly to read its name. A stick it cannot
+  open (another program has seized it, say) comes back with `busy?` true and an empty name.
+  `Blinkstick.list` with no argument opens nothing.
+- `write_info_block(number, bytes)` takes block 1 or 2 and a String of at most 32 bytes, written
+  byte for byte whatever its encoding. Trailing NUL bytes read back as nothing, because reads
+  strip them. A bad number or too many bytes raises `ArgumentError`, and a non String raises
+  `TypeError`.
+- `stick.mode =` takes `:ws2812` (or 2) or `:ws2812_mirror` (or 3). In mirror mode `colour=`
+  still lights every LED, and reports 5 and 6 behave as in mode 2. The change needs no replug.
+  The stick stops answering for a moment after a mode write (typically 12 to 15 ms), so
+  `mode=` waits until it answers with the new mode, raising `DisconnectedError` if it has not
+  within 250 ms. Modes 0 and 1 are for the BlinkStick Pro: they raise `ArgumentError`, as
+  they can leave a Nano dark until it is replugged.
+- Names and info block bytes are whatever any tool last wrote, so they may not be valid UTF-8
+  and may hold control characters. They come back as they are. Treat them as untrusted input,
+  and sanitise them before printing them to a terminal.
+
+### Effects
+
+```ruby
+stick.blink(:red, period: 1.0, repeats: 3)   # on for 0.5 s, off for 0.5 s, three times
+stick.pulse(:blue, duration: 2.0)            # off, fade up to blue, fade down to off
+stick.morph(:green, duration: 1.5)           # fade from what the stick shows now to green
+```
+
+All three block the calling thread until they finish. Times are in seconds. Colours are
+anything `Colour.parse` takes, checked before anything is sent. `blink` and `pulse` take
+`repeats:` (an Integer of 1 or more) and end with the LEDs off, and `morph` ends on its colour.
+`morph` fades in 20 ms steps, counted as the Go library counts them (0.58 s is 29 steps), and
+a duration under one step jumps straight to the colour. The brightness limit applies once, so
+a fade to full red with a limit of 128 ends at 128.
+
+To stop an effect from another thread, give it a `Blinkstick::Cancellation`:
+
+```ruby
+cancel = Blinkstick::Cancellation.new
+worker = Thread.new { stick.blink(:red, period: 1.0, repeats: 60, cancel: cancel) }
+
+sleep 3
+cancel.cancel        # wakes the effect straight away; calling it again does nothing
+worker.value         # => false
+cancel.cancelled?    # => true
+```
+
+- An effect returns `true` when it runs to the end and `false` when it was cancelled. A
+  cancelled effect leaves the LEDs as they are, so turn them off yourself if you want that.
+- With no `cancel:` the effect just pauses with plain timed waits.
+- One `Cancellation` can be shared by several effects. Its `wait(seconds)` returns `true` as
+  soon as it is cancelled and `false` after `seconds`.
+- Each write takes the stick's lock on its own, so other calls can run in the middle of an
+  effect. Two effects on one stick at the same time interleave their frames, and the gem does
+  not stop you.
+- Do not call a `Cancellation`'s methods from a `trap` handler: they take a Mutex, and Ruby
+  refuses that inside a trap. Set a flag in the handler and cancel from a normal thread instead.
+
+### Reconnecting
+
+If a stick is unplugged, or stops answering for three attempts, the `Stick` closes its handle,
+lists the attached sticks again and opens the one with its serial. When that works it repaints
+the last frame it wrote, then repeats the call that failed. Plug the stick back in and the next
+call just works, with the LEDs as you left them.
+
+- The remembered frame is what the gem last wrote (after the brightness limit, before inverse).
+  `colour=`, `frame=`, `off` and the effects replace it, and `[]=` updates one entry. Nothing
+  is repainted if nothing has been written yet, or if the call that failed was itself a frame
+  write (it is simply retried).
+- The first `[]=` on a `Stick` that has written nothing reads the frame from the stick once, so
+  the entries it does not touch are kept.
+- It tries once per call. If the stick is missing, cannot be opened or the repaint fails, the
+  call raises `DisconnectedError`, and the next call tries again. `close` on a disconnected
+  stick succeeds.
+- A `Stick` never reconnects onto a different stick. If more than one attached stick has its
+  serial, it raises `DisconnectedError` rather than guess. (A stick with an empty serial, which
+  Linux reports when there is no `HID_UNIQ`, is an unknown model and cannot be opened at all.)
+- `BusyError`, `PermissionError` and `ClosedError` are raised as they are, without reconnecting.
 
 ### Sharing a stick
 

data/lib/blinkstick/backend/hidraw.rb

@@ -55,10 +55,15 @@ module Blinkstick
         # @param size [Integer] bytes to ask for, including the ID byte
         # @return [String] binary String of the bytes the OS returned, the
         #   report ID first (empty when it returned none)
+        # @raise [ArgumentError] unless size is a positive Integer and report_id is 0 to 255
         # @raise [ClosedError] after {#close}
         # @raise [DisconnectedError] when the stick is unplugged
         # @raise [TransferFailed] for any other failed transfer
         def read_feature(report_id, size)
+          unless size.is_a?(Integer) && size.positive? && report_id.is_a?(Integer) && report_id.between?(0, 255)
+            raise ArgumentError, "need report ID 0 to 255 and positive size, got #{report_id.inspect}, #{size.inspect}"
+          end
+
           transfer do
             buffer = ("\x00".b * size)
             buffer.setbyte(0, report_id)

data/lib/blinkstick/backend/iokit.rb

@@ -217,10 +217,12 @@ module Blinkstick
         # @param report_id [Integer] the report to ask for
         # @param size [Integer] the report's length, including the ID byte
         # @return [String] binary, the bytes IOKit returned, report ID first
+        # @raise [ArgumentError] unless size is a positive Integer and report_id is 0 to 255
         # @raise [ClosedError] after {#close}
         # @raise [DisconnectedError] when the stick is unplugged
         # @raise [TransferFailed] for any other failed transfer
         def read_feature(report_id, size)
+          check_read_arguments(report_id, size)
           ensure_open
           buffer = FFI::MemoryPointer.new(:uint8, size)
           buffer.put_uint8(0, report_id)
@@ -252,6 +254,12 @@ module Blinkstick
           @serial || "the stick"
         end
 
+        def check_read_arguments(report_id, size)
+          return if size.is_a?(Integer) && size.positive? && report_id.is_a?(Integer) && report_id.between?(0, 255)
+
+          raise ArgumentError, "need report ID 0 to 255 and positive size, got #{report_id.inspect}, #{size.inspect}"
+        end
+
         def ensure_open
           raise ClosedError, "#{name} is closed" if @closed
         end

data/lib/blinkstick/cancellation.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Blinkstick
+  # A cooperative cancellation token for effects ({Stick#blink} and friends).
+  #
+  # Every pause in an effect is {#wait}, so {#cancel} wakes it at once. It
+  # uses only Mutex and ConditionVariable (no Thread#raise, Thread#kill or
+  # Timeout), so it is safe across threads and works under a fiber scheduler.
+  # One token may be shared by several effects. Do not call any of its
+  # methods from a signal trap handler; see {#cancel}.
+  #
+  #   cancel = Blinkstick::Cancellation.new
+  #   Thread.new { sleep 10; cancel.cancel }
+  class Cancellation
+    # The longest single condition wait, in seconds. ConditionVariable#wait
+    # raises RangeError for very long timeouts, so a longer pause is made of
+    # several waits (the loop works out what remains each time).
+    LONGEST_WAIT = 86_400
+    private_constant :LONGEST_WAIT
+
+    def initialize
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @cancelled = false
+    end
+
+    # Cancels the token and wakes every waiter. Safe to call again.
+    #
+    # Do not call this from a signal trap handler: Mutex#synchronize raises
+    # ThreadError there. Set a flag in the trap and cancel from a thread that
+    # watches it.
+    #
+    # @return [nil]
+    # @raise [ThreadError] when called from a signal trap handler
+    def cancel
+      @mutex.synchronize do
+        @cancelled = true
+        @condition.broadcast
+      end
+      nil
+    end
+
+    # @return [Boolean] true once {#cancel} has been called
+    def cancelled?
+      @mutex.synchronize { @cancelled }
+    end
+
+    # Pauses for +seconds+, or until the token is cancelled, whichever is first.
+    #
+    # @param seconds [Numeric] a finite number, 0 or more
+    # @return [Boolean] true if cancelled (at once if it already was), false
+    #   once +seconds+ have passed
+    # @raise [ArgumentError] when +seconds+ is not a finite Numeric of 0 or more
+    def wait(seconds)
+      check_seconds(seconds)
+      deadline = now + seconds
+      @mutex.synchronize do
+        until @cancelled
+          remaining = deadline - now
+          break if remaining <= 0
+
+          @condition.wait(@mutex, [remaining, LONGEST_WAIT].min)
+        end
+        @cancelled
+      end
+    end
+
+    private
+
+    def check_seconds(seconds)
+      ok = seconds.is_a?(Numeric) && seconds.real? && seconds.to_f.finite? && seconds >= 0
+      raise ArgumentError, "seconds must be a finite number of 0 or more, got #{seconds.inspect}" unless ok
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/blinkstick/colour.rb

@@ -43,6 +43,27 @@ module Blinkstick
       NAMES
     end
 
+    # Picks a random colour.
+    #
+    # Without +vivid+ each channel is uniform from 0 to 255, so many results are
+    # muted. With +vivid+ the colour is one of the 1530 fully saturated hues:
+    # one channel is 255 and another is 0. Not suitable for anything security
+    # related.
+    #
+    # @param vivid [Boolean] pick only fully saturated hues
+    # @param random [#rand] the generator, anything responding to +rand(n)+
+    # @return [Colour]
+    def self.random(vivid: false, random: Random)
+      return hue(random.rand(Colour::HUES)) if vivid
+
+      new(red: random.rand(256), green: random.rand(256), blue: random.rand(256))
+    end
+
+    # @return [Colour] the colour with each channel replaced by 255 minus its value
+    def inverse
+      with(red: 255 - red, green: 255 - green, blue: 255 - blue)
+    end
+
     # @return [String] the colour as lower case "#rrggbb"
     def hex
       format("#%<r>02x%<g>02x%<b>02x", r: red, g: green, b: blue)
@@ -53,6 +74,20 @@ module Blinkstick
     class << self
       private
 
+      # Port of go-blinkstick's hue: step +step+ (0...HUES) of the wheel,
+      # running red, yellow, green, cyan, blue, magenta and back towards red.
+      def hue(step)
+        offset = step % 255
+        case step / 255
+        when 0 then new(red: 255, green: offset, blue: 0)
+        when 1 then new(red: 255 - offset, green: 255, blue: 0)
+        when 2 then new(red: 0, green: 255, blue: offset)
+        when 3 then new(red: 0, green: 255 - offset, blue: 255)
+        when 4 then new(red: offset, green: 0, blue: 255)
+        else new(red: 255, green: 0, blue: 255 - offset)
+        end
+      end
+
       def lookup(name)
         COLOUR_NAMES[name]
       end
@@ -97,6 +132,9 @@ module Blinkstick
     end
   end
 
+  # Number of fully saturated hues: six segments of 255 steps.
+  Colour::HUES = 6 * 255
+
   # Colour with every channel off.
   Colour::OFF = Colour.new(red: 0, green: 0, blue: 0)
 end

data/lib/blinkstick/errors.rb

@@ -4,7 +4,7 @@ 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.
+  # Raised when no BlinkStick is attached, or none matches the requested serial or name.
   class NotFoundError < Error; end
 
   # Raised when another program has seized the stick (macOS only).
@@ -19,9 +19,13 @@ module Blinkstick
   # 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.
+  # Raised when the stick is unplugged or stops responding mid-use and
+  # reconnecting to it (by its serial) fails or cannot be tried.
   class DisconnectedError < Error; end
 
+  # Raised when more than one attached stick has the requested name.
+  class DuplicateNameError < Error; end
+
   # Raised when a value cannot be turned into a {Colour}.
   class InvalidColourError < ArgumentError; end
 end

data/lib/blinkstick/model.rb

@@ -33,7 +33,15 @@ module Blinkstick
   private_constant :MODELS
 
   # Identifies an attached BlinkStick. It holds no OS path or handle.
-  Info = Data.define(:serial, :version, :manufacturer, :product, :model) do
+  # +release+ comes last and defaults to nil, so 0.2.0 code that builds an
+  # Info from its five members, by position or keyword, still works.
+  Info = Data.define(:serial, :version, :manufacturer, :product, :model, :release) do
+    # Data checks the other members (serial, version, manufacturer, product
+    # and model) as usual.
+    #
+    # @param release [Integer, nil] the USB bcdDevice value, nil when not known
+    def initialize(release: nil, **) = super
+
     # @param serial [String] for example "BS072777-3.0"
     # @param manufacturer [String]
     # @param product [String]
@@ -43,7 +51,7 @@ module Blinkstick
       _, _, version = serial.partition("-")
       major, = version.split(".", 2)
       new(serial: serial, version: version, manufacturer: manufacturer, product: product,
-          model: MODELS.fetch([major, release], Model::UNKNOWN))
+          model: MODELS.fetch([major, release], Model::UNKNOWN), release: release)
     end
   end
 end

data/lib/blinkstick/names.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+# Finding sticks by the name stored on them.
+module Blinkstick
+  # A stick's identity and the name stored on it, from {Blinkstick.list}
+  # with +names: true+. A stick that could not be opened or read is +busy+
+  # with an empty +name+.
+  #
+  # @!attribute [r] info
+  #   @return [Info]
+  # @!attribute [r] name
+  #   @return [String] "" when the stick has no name or could not be read
+  # @!attribute [r] busy
+  #   @return [Boolean]
+  NamedInfo = Data.define(:info, :name, :busy) do
+    # @return [Boolean] true when the stick could not be opened or read
+    def busy?
+      busy
+    end
+  end
+
+  # One stick seen while looking for a name: its device, name and open Stick,
+  # or the Error that stopped it being read.
+  Reading = Data.define(:device, :name, :error, :stick)
+  private_constant :Reading
+
+  class << self
+    private
+
+    def check_selectors(serial, name)
+      raise ArgumentError, "pass serial: or name:, not both" unless serial.nil? || name.nil?
+      return if name.nil?
+      raise TypeError, "name must be a String, got #{name.class}" unless name.is_a?(String)
+      raise ArgumentError, "name must not be empty" if name.empty?
+    end
+
+    # Opens without the model check and without reconnecting: for reading a
+    # name, never handed to a caller as it is.
+    def open_any(backend, device)
+      info = info_for(device)
+      Stick.new(backend.open(device), info)
+    end
+
+    # Opens, reads the name and closes again, whatever happens in between.
+    def read_name(backend, device)
+      stick = open_any(backend, device)
+      begin
+        stick.name
+      ensure
+        stick.close
+      end
+    end
+
+    def list_named
+      backend = Backend.current
+      backend.list.map do |device|
+        NamedInfo.new(info: info_for(device), name: read_name(backend, device), busy: false)
+      rescue Error
+        NamedInfo.new(info: info_for(device), name: "", busy: true)
+      end
+    end
+
+    # Keeps every readable stick open until the match is known, then hands
+    # the match's handle to a new Stick and closes the rest.
+    def open_named(name)
+      backend = Backend.current
+      readings = []
+      begin
+        backend.list.each { |device| readings << try_keep(backend, device) }
+        match = single_match(name, readings)
+        build_stick(backend, match.device) { match.stick.detach }
+      ensure
+        readings.each { |reading| reading.stick&.close }
+      end
+    end
+
+    def single_match(name, readings)
+      matches = readings.select { |reading| reading.name&.b == name.b }
+      raise name_error(name, matches.map(&:device), readings) unless matches.size == 1
+
+      matches.first
+    end
+
+    # @return [Reading] with the stick still open, or with the Error when it
+    #   could not be opened or read
+    def try_keep(backend, device)
+      stick = open_any(backend, device)
+      begin
+        Reading.new(device, stick.name, nil, stick).tap { stick = nil }
+      ensure
+        stick&.close
+      end
+    rescue Error => e
+      Reading.new(device, nil, e, nil)
+    end
+
+    def name_error(name, matches, readings)
+      matches.empty? ? not_found_name(name, readings) : duplicate_name(name, matches)
+    end
+
+    def duplicate_name(name, matches)
+      DuplicateNameError.new("#{matches.size} sticks are named #{name.inspect}: " \
+                             "#{matches.map { |device| device.serial.inspect }.join(', ')}")
+    end
+
+    def not_found_name(name, readings)
+      skipped = readings.filter_map do |reading|
+        error = reading.error
+        "#{reading.device.serial.inspect} (#{error.class.name.split('::').last}: #{error.message})" if error
+      end
+      message = "no BlinkStick named #{name.inspect}"
+      message += "; skipped #{skipped.join(', ')}" unless skipped.empty?
+      NotFoundError.new(message)
+    end
+  end
+end