ruby-blinkstick 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6585fad55a10b4656175afc2f1e41675bf19cd58efbfe1776c74f13fb7817b9
-  data.tar.gz: e1d8dc9095f6d482544f4d06096a0623be521a6e685a2a0714f3e3b38644ad93
+  metadata.gz: 538eb17c6e17b2bdaff6ca9b2f39d1c34196d0c72ce7dffee3b57d47a04131b7
+  data.tar.gz: e3f10dcdf64efcd8913052ce3f0b0afe7493a1bae9d705ccdb0b5cb7bea788f2
 SHA512:
-  metadata.gz: 5bddb3dd5ffe701b5b8a088cd2b99b6fe532950d14ec63346ac34ea202cc6029d3fe7acb9f82c704c561c6e2586a59ef86f9f9f4f4e029229d3caa2ce4d831d4
-  data.tar.gz: c30d066e7288a8ac7f244602114f7b08f2c30d5a0b601f5d9c84bad22471971cc3a53092c367011be4f757585a176cb8b865a431a2c08d97758338f0fde67e23
+  metadata.gz: 17438f01d70babc376163f338220a536daaf11e3704efb69b3748d19b460f58e565f613e4c2d81ad457fa47d2a9c4ed66eaa64cefa0d794397d1443905e19281
+  data.tar.gz: 56c068d7cbcfc9094988b69abd46c95b9ba60414e253549a2aed7a720793dbced76e8b87247aee7c2c7ba865890696c469aab0979ad40f88d57b4eea58159d3b

data/CAPABILITIES.md

@@ -1,9 +1,7 @@
 # Capabilities
 
-The gem is a placeholder and supports nothing yet. This table is the checklist for the implementation.
-
-What the BlinkStick Nano and Square can do, and what this gem supports so far. Back to the
-[README](README.md).
+What the BlinkStick Nano and Square can do, and what this gem supports so far. The Ruby column
+names the method or class that covers a row. Back to the [README](README.md).
 
 This file is updated whenever a feature lands.
 
@@ -14,51 +12,51 @@ device may have it but it has not been confirmed on hardware.
 
 Features built into the BlinkStick firmware.
 
-| Feature | Nano | Square | Supported since | Notes |
-|---|---|---|---|---|
-| List attached sticks | no | no | not yet | Enumerate every attached stick |
-| Open the first stick or one by serial | no | no | not yet | 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 |
-| Several sticks open at once | no | no | not yet | |
-| Serial and firmware version | no | no | not yet | Read from the device info |
-| Manufacturer and product strings | no | no | not yet | Read from the device info |
-| Set all LEDs | no | no | not yet | Set every LED to one colour, or turn them off |
-| Set one LED | no | no | not yet | Set a single LED by index, using report 5 |
-| Set every LED at once | no | no | not yet | Write a whole frame in one report |
-| Read LED values back | no | no | not yet | Read the whole frame or a single LED |
-| Info blocks 1 and 2 | no | no | not yet | Read and write the info blocks. 32 bytes each, stored in EEPROM |
-| Set one LED directly (report 5) | no | no | not yet | `[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) | no | no | not yet | `[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 |
-| 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 |
+| Feature | Nano | Square | Ruby | Supported since | Notes |
+|---|---|---|---|---|---|
+| 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 |
+| 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 |
+| 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 | no | no |  | not yet | Set a single LED by index, using report 5 |
+| Set every LED at once | no | no |  | not yet | Write a whole frame in one report |
+| Read LED values back | no | no |  | not yet | Read the whole frame or a single LED |
+| Info blocks 1 and 2 | no | no |  | not yet | Read and write the info blocks. 32 bytes each, stored in EEPROM |
+| Set one LED directly (report 5) | no | no |  | not yet | `[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) | no | no |  | not yet | `[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 |
+| 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 |
 
 ## Host features
 
 Features this gem adds in software. They work the same on every supported device.
 
-| Feature | Supported since | Notes |
-|---|---|---|
-| Model detection | not yet | From the serial and USB release number |
-| Colour from hex or `r,g,b` | not yet | 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 |
-| CSS colour names | not yet | All 148 from CSS Color Level 4 |
-| List CSS colour names | not yet | Sorted, for shell completion |
-| Colour as hex | not yet | 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 |
+| Feature | Ruby | Supported since | Notes |
+|---|---|---|---|
+| 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 |
+| 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 |
 
 ## Platforms
 
 | Platform | Supported since |
 |---|---|
-| macOS | not yet |
-| Linux | not yet |
+| macOS | 0.1.0 |
+| Linux | 0.1.0 |
 | Windows | no |

data/CHANGELOG.md

@@ -6,6 +6,23 @@ All notable changes to this project are recorded here. The format follows
 
 ## [Unreleased]
 
+## [0.1.0] - 2026-10-28
+
+### Added
+
+- `Blinkstick.list` lists every attached BlinkStick as an `Info` value with its serial, firmware version, manufacturer, product and model.
+- `Blinkstick.open` opens the first stick or one by serial, with or without a block. Several sticks can be open at once.
+- `Stick#colour=` sets every LED to one colour and `Stick#off` turns them off. A stick is safe to share between threads, and `close` and `closed?` manage its lifetime.
+- `Colour.parse` accepts hex, `r,g,b`, an array of three integers and the 148 CSS colour names (strings or symbols, any case). `Colour#hex` and `Colour#to_s` give lower case `#rrggbb`, and `Colour.names` lists the names.
+- Model detection for the BlinkStick Nano (2 LEDs) and Square (8 LEDs). Other models are listed as `Model::UNKNOWN` and refused by `open`.
+- Errors under `Blinkstick::Error` for a missing stick, a stick seized by another program, a refused permission, an unsupported model, a closed stick and a disconnected stick. `InvalidColourError` is an `ArgumentError`.
+- macOS support through IOKit (via `ffi`, loaded only on macOS) and Linux support through `hidraw`, with nothing to install but the gem. Sticks are opened shared, so other programs can use them too.
+
+### Changed
+
+- The documented `gh attestation verify` command checks the release workflow, not just the repository.
+- The release workflow also checks that the attestation names the tagged commit, and a re-run refuses to go on if rubygems.org has a different gem for the version.
+
 ## [0.0.2] - 2026-10-28
 
 ### Added

data/README.md

@@ -12,9 +12,10 @@ of BlinkStick.
 
 ## Status
 
-This gem is a placeholder that reserves the name and does nothing else yet. The implementation
-will port [go-blinkstick](https://github.com/bawdo/go-blinkstick). See
-[CAPABILITIES.md](CAPABILITIES.md) for the features it will cover.
+Version 0.1.0 finds a BlinkStick Nano or Square, opens it, sets every LED to a colour and
+turns them off, on macOS and Linux. Single LEDs, frames, effects and the rest are still to
+come. [CAPABILITIES.md](CAPABILITIES.md) lists what is supported now and the Ruby method for
+each feature.
 
 ## Install
 
@@ -34,6 +35,51 @@ you `require "blinkstick"` and use the `Blinkstick` module.
 ## Requirements
 
 - Ruby 3.4 or later.
+- macOS or Linux (Windows is not supported).
+- Nothing else to install. The gem needs no system library and no compiler: its one
+  dependency, `ffi`, installs as a prebuilt gem, and it is only loaded on macOS. Linux talks
+  to the stick through `hidraw` using Ruby's standard library alone. Linux also needs the
+  udev rule described below.
+
+## Quick start
+
+```ruby
+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>>]
+
+Blinkstick.open do |stick|         # the first stick; the block form closes it, like File.open
+  stick.colour = :cornflowerblue   # set every LED
+  stick.colour = "#ff8800"
+  stick.colour = [255, 136, 0]
+  stick.off                        # every LED off
+end
+
+stick = Blinkstick.open(serial: "BS072777-3.0")  # without a block, you close it
+stick.info                         # => Blinkstick::Info
+stick.close
+stick.closed?                      # => true
+
+Blinkstick::Colour.parse("255,136,0").hex   # => "#ff8800"
+Blinkstick::Colour.names.first(3)           # => ["aliceblue", "antiquewhite", "aqua"]
+```
+
+A colour can be a CSS colour name (a string or symbol, any case), hex (`#rgb` or `#rrggbb`,
+with or without the `#`), `"r,g,b"`, or an array of three integers.
+
+Failures raise subclasses of `Blinkstick::Error`: `NotFoundError`, `BusyError`,
+`PermissionError`, `UnsupportedModelError`, `ClosedError` and `DisconnectedError`. A bad
+colour raises `Blinkstick::InvalidColourError`, which is an `ArgumentError`.
+
+### Sharing a stick
+
+Sticks are shared on both platforms, so several programs (and several Ruby processes) can
+drive the same stick at once, and the last write is what shows. The exception is a program
+that seizes the stick for itself, as ones built on hidapi do on macOS. While that program has
+it, this gem raises `Blinkstick::BusyError`. Close the other program and try again.
 
 ## Linux
 
@@ -65,7 +111,8 @@ came from this repository's workflow, with the [GitHub CLI](https://cli.github.c
 
 ```sh
 gem fetch ruby-blinkstick -v 0.0.2
-gh attestation verify ruby-blinkstick-0.0.2.gem --repo bawdo/ruby-blinkstick
+gh attestation verify ruby-blinkstick-0.0.2.gem --repo bawdo/ruby-blinkstick \
+  --signer-workflow bawdo/ruby-blinkstick/.github/workflows/release.yml
 ```
 
 Swap in the version you are checking. [SECURITY.md](SECURITY.md) has the details.

data/lib/blinkstick/backend/hidraw.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative "../../blinkstick"
+
+module Blinkstick
+  module Backend
+    # The Linux backend. It finds sticks by reading sysfs and talks to them
+    # through their /dev/hidraw node with the HIDIOCSFEATURE ioctl, so it
+    # needs nothing beyond the standard library.
+    #
+    # @api private
+    class Hidraw
+      # The ioctl request number for HIDIOCSFEATURE of the given length:
+      # direction read/write (3), size, type 'H' (0x48) and number 6.
+      #
+      # @param length [Integer] report size in bytes
+      # @return [Integer]
+      def self.set_feature_request(length) # rubocop:disable Naming/AccessorMethodName
+        # The name is the kernel's (HIDIOCSFEATURE), not a Ruby writer.
+        (3 << 30) | (length << 16) | (0x48 << 8) | 0x06
+      end
+
+      # An open hidraw node.
+      class Handle
+        # @param io [#ioctl, #close] the open device node
+        # @param serial [String, nil] named in error messages
+        def initialize(io, serial: nil)
+          @io = io
+          @serial = serial
+          @closed = false
+        end
+
+        # Sends a feature report.
+        #
+        # @param report [String] binary String whose first byte is the report ID
+        # @raise [ClosedError] after {#close}
+        # @raise [DisconnectedError] when the stick is unplugged
+        # @raise [TransferFailed] for any other failed transfer
+        def write_feature(report)
+          raise ClosedError, "#{name} is closed" if @closed
+
+          @io.ioctl(Hidraw.set_feature_request(report.bytesize), report.dup)
+        rescue Errno::ENODEV, Errno::ENOENT, Errno::ESHUTDOWN => e
+          raise DisconnectedError, "#{name} was unplugged (#{e.class})"
+        rescue Errno::EACCES, Errno::EPERM => e
+          raise PermissionError, "#{name}: #{e.message}. #{UDEV_HINT}"
+        rescue SystemCallError => e
+          raise TransferFailed, "#{name}: #{e.message}"
+        end
+
+        # Releases the node. Calling it again does nothing, and it never raises.
+        #
+        # @return [void]
+        def close
+          return if @closed
+
+          @closed = true
+          begin
+            @io.close
+          rescue IOError, SystemCallError
+            nil
+          end
+        end
+
+        private
+
+        def name
+          @serial || "the stick"
+        end
+      end
+
+      UDEV_HINT = 'See the "Linux" section of the README (the udev rule) to grant access.'
+      private_constant :UDEV_HINT
+
+      # @param sysfs [String] where sysfs is mounted
+      # @param dev [String] where the device nodes live
+      def initialize(sysfs: "/sys", dev: "/dev")
+        @sysfs = sysfs
+        @dev = dev
+      end
+
+      # @return [Array<Device>] every BlinkStick attached, in hidraw order
+      #   (hidraw2 before hidraw10)
+      def list
+        Dir.glob(File.join(@sysfs, "class/hidraw/hidraw*"))
+           .sort_by { |entry| File.basename(entry).delete_prefix("hidraw").to_i }
+           .filter_map { |entry| device_for(entry) }
+      end
+
+      # @param device [Device] a device from {#list}
+      # @return [Handle]
+      # @raise [NotFoundError, PermissionError, BusyError] when it cannot be opened
+      # @raise [Error] when opening fails for any other reason
+      def open(device)
+        Handle.new(File.open(device.id, "r+b"), serial: device.serial)
+      rescue SystemCallError => e
+        raise open_error(e, device)
+      end
+
+      private
+
+      def open_error(error, device)
+        where = "#{device.serial} (#{device.id})"
+        case error
+        when Errno::ENOENT, Errno::ENODEV then NotFoundError.new("#{where} is no longer attached")
+        when Errno::EACCES, Errno::EPERM then PermissionError.new("Permission denied opening #{where}. #{UDEV_HINT}")
+        when Errno::EBUSY then BusyError.new("#{where} is in use by another program")
+        else Error.new("Could not open #{where}: #{error.message}")
+        end
+      end
+
+      def device_for(entry)
+        hid = File.realpath(File.join(entry, "device"))
+        uevent = parse_uevent(File.join(hid, "uevent"))
+        return unless blinkstick?(uevent["HID_ID"])
+
+        usb = File.expand_path("../..", hid)
+        Device.new(id: File.join(@dev, File.basename(entry)), serial: text(uevent.fetch("HID_UNIQ", "")),
+                   manufacturer: attribute(usb, "manufacturer"), product: attribute(usb, "product"),
+                   release: attribute(usb, "bcdDevice").to_i(16))
+      rescue SystemCallError
+        nil
+      end
+
+      # Read in binary, so a device name that is not valid in the locale's
+      # encoding (a UTF-8 "®" under LANG=C, say) cannot break parsing.
+      def parse_uevent(path)
+        File.readlines(path, chomp: true, mode: "rb").to_h { |line| line.split("=", 2).then { |k, v| [k, v.to_s] } }
+      end
+
+      # HID_ID is bus:vendor:product in hex.
+      def blinkstick?(hid_id)
+        _bus, vendor, product = hid_id.to_s.split(":")
+        vendor.to_s.hex == VENDOR_ID && product.to_s.hex == PRODUCT_ID
+      end
+
+      def attribute(dir, file)
+        text(File.binread(File.join(dir, file)).strip)
+      rescue SystemCallError
+        ""
+      end
+
+      # sysfs strings are UTF-8 by convention; invalid bytes become U+FFFD.
+      def text(bytes)
+        bytes.dup.force_encoding(Encoding::UTF_8).scrub
+      end
+    end
+  end
+end

data/lib/blinkstick/backend/iokit.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require "ffi"
+require_relative "../../blinkstick"
+
+module Blinkstick
+  module Backend
+    # The macOS backend. It finds sticks with an IOHIDManager and sends
+    # feature reports with IOHIDDeviceSetReport, calling IOKit and
+    # CoreFoundation through ffi. Sticks are opened shared, never seized.
+    #
+    # CoreFoundation ownership follows Apple's Create rule: anything returned
+    # by a Create or Copy call is released here, and anything returned by a
+    # Get call is borrowed. Each listed device reference is retained, and
+    # released by its FFI::AutoPointer once no {Device} refers to it. {#open}
+    # takes a second retain that the {Handle} owns and releases on close, so
+    # an open device outlives the AutoPointer whatever order finalisers run in.
+    #
+    # @api private
+    class IOKit
+      # kIOHIDOptionsTypeNone: open the device shared, never seized.
+      OPEN_OPTIONS = 0
+
+      # The IOKit and CoreFoundation functions this backend calls, and
+      # helpers that make and read CF values.
+      #
+      # @api private
+      module Native
+        extend FFI::Library
+
+        ffi_lib "/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation",
+                "/System/Library/Frameworks/IOKit.framework/IOKit"
+
+        attach_function :cf_retain, :CFRetain, [:pointer], :pointer
+        attach_function :cf_release, :CFRelease, [:pointer], :void
+        attach_function :cf_get_type_id, :CFGetTypeID, [:pointer], :ulong
+        attach_function :cf_string_get_type_id, :CFStringGetTypeID, [], :ulong
+        attach_function :cf_number_get_type_id, :CFNumberGetTypeID, [], :ulong
+        attach_function :cf_string_create_with_c_string, :CFStringCreateWithCString, %i[pointer string uint32], :pointer
+        attach_function :cf_string_get_length, :CFStringGetLength, [:pointer], :long
+        attach_function :cf_string_get_maximum_size_for_encoding, :CFStringGetMaximumSizeForEncoding,
+                        %i[long uint32], :long
+        attach_function :cf_string_get_c_string, :CFStringGetCString, %i[pointer pointer long uint32], :uchar
+        attach_function :cf_number_create, :CFNumberCreate, %i[pointer long pointer], :pointer
+        attach_function :cf_number_get_value, :CFNumberGetValue, %i[pointer long pointer], :uchar
+        attach_function :cf_dictionary_create_mutable, :CFDictionaryCreateMutable,
+                        %i[pointer long pointer pointer], :pointer
+        attach_function :cf_dictionary_set_value, :CFDictionarySetValue, %i[pointer pointer pointer], :void
+        attach_function :cf_set_get_count, :CFSetGetCount, [:pointer], :long
+        attach_function :cf_set_get_values, :CFSetGetValues, %i[pointer pointer], :void
+
+        attach_function :hid_manager_create, :IOHIDManagerCreate, %i[pointer uint32], :pointer
+        attach_function :hid_manager_set_device_matching, :IOHIDManagerSetDeviceMatching, %i[pointer pointer], :void
+        attach_function :hid_manager_copy_devices, :IOHIDManagerCopyDevices, [:pointer], :pointer
+        attach_function :hid_device_get_property, :IOHIDDeviceGetProperty, %i[pointer pointer], :pointer
+        # IOReturn is a signed 32-bit kern_return_t, so failures come back negative.
+        attach_function :hid_device_open, :IOHIDDeviceOpen, %i[pointer uint32], :int
+        attach_function :hid_device_close, :IOHIDDeviceClose, %i[pointer uint32], :int
+        attach_function :hid_device_set_report, :IOHIDDeviceSetReport, %i[pointer int long buffer_in long], :int
+
+        UTF8 = 0x08000100 # kCFStringEncodingUTF8
+        SINT32 = 3 # kCFNumberSInt32Type
+        private_constant :UTF8, :SINT32
+
+        class << self
+          # The address of a CoreFoundation global, such as a callbacks struct.
+          #
+          # @param name [String]
+          # @return [FFI::Pointer]
+          def global(name)
+            ffi_libraries.each do |library|
+              symbol = library.find_variable(name)
+              return symbol if symbol
+            end
+            raise Error, "CoreFoundation has no #{name}"
+          end
+
+          # @param text [String]
+          # @return [FFI::Pointer] a new CFString the caller must {release}
+          def string(text)
+            cf_string_create_with_c_string(nil, text, UTF8)
+          end
+
+          # @param value [Integer]
+          # @return [FFI::Pointer] a new CFNumber the caller must {release}
+          def number(value)
+            buffer = FFI::MemoryPointer.new(:int32)
+            buffer.write_int32(value)
+            cf_number_create(nil, SINT32, buffer)
+          end
+
+          # Reads a borrowed CFString.
+          #
+          # @param ref [FFI::Pointer]
+          # @return [String] "" when ref is not a CFString or cannot be converted
+          def read_string(ref)
+            return "" unless type?(ref, cf_string_get_type_id)
+
+            size = cf_string_get_maximum_size_for_encoding(cf_string_get_length(ref), UTF8) + 1
+            buffer = FFI::MemoryPointer.new(:char, size)
+            return "" if cf_string_get_c_string(ref, buffer, size, UTF8).zero?
+
+            buffer.read_string.force_encoding(Encoding::UTF_8)
+          end
+
+          # Reads a borrowed CFNumber.
+          #
+          # @param ref [FFI::Pointer]
+          # @return [Integer] 0 when ref is not a CFNumber
+          def read_integer(ref)
+            return 0 unless type?(ref, cf_number_get_type_id)
+
+            buffer = FFI::MemoryPointer.new(:int32)
+            cf_number_get_value(ref, SINT32, buffer)
+            buffer.read_int32
+          end
+
+          # Releases a CF object, ignoring nil and NULL.
+          #
+          # @param ref [FFI::Pointer, nil]
+          # @return [void]
+          def release(ref)
+            cf_release(ref) unless ref.nil? || ref.null?
+          end
+
+          private
+
+          def type?(ref, type_id)
+            !ref.null? && cf_get_type_id(ref) == type_id
+          end
+        end
+      end
+
+      # IOReturn values, from IOKit/IOReturn.h.
+      NO_DEVICE = 0xE00002C0
+      NOT_PRIVILEGED = 0xE00002C1
+      EXCLUSIVE_ACCESS = 0xE00002C5
+      NOT_ATTACHED = 0xE00002D9
+      NOT_PERMITTED = 0xE00002E2
+      REPORT_TYPE_FEATURE = 2 # kIOHIDReportTypeFeature
+      private_constant :NO_DEVICE, :NOT_PRIVILEGED, :EXCLUSIVE_ACCESS, :NOT_ATTACHED, :NOT_PERMITTED,
+                       :REPORT_TYPE_FEATURE
+
+      OPEN_REASONS = {
+        BusyError => "it is in use by another program",
+        PermissionError => "permission denied",
+        NotFoundError => "it is no longer attached"
+      }.freeze
+      PROPERTY_KEYS = %w[VendorID ProductID VersionNumber Manufacturer Product SerialNumber].freeze
+      private_constant :OPEN_REASONS, :PROPERTY_KEYS
+
+      # Maps a failed IOHIDDeviceSetReport to the error a handle raises.
+      #
+      # @param code [Integer] the IOReturn, signed or unsigned
+      # @return [Class] a {Blinkstick::Error} subclass
+      def self.error_for(code)
+        case code & 0xFFFF_FFFF
+        when EXCLUSIVE_ACCESS then BusyError
+        when NOT_PRIVILEGED, NOT_PERMITTED then PermissionError
+        when NO_DEVICE, NOT_ATTACHED then DisconnectedError
+        else TransferFailed
+        end
+      end
+
+      # Maps a failed IOHIDDeviceOpen to the error {#open} raises.
+      #
+      # @param code [Integer] the IOReturn, signed or unsigned
+      # @return [Class] a {Blinkstick::Error} subclass
+      def self.open_error_for(code)
+        case code & 0xFFFF_FFFF
+        when EXCLUSIVE_ACCESS then BusyError
+        when NOT_PRIVILEGED, NOT_PERMITTED then PermissionError
+        when NO_DEVICE, NOT_ATTACHED then NotFoundError
+        else Error
+        end
+      end
+
+      # Formats an IOReturn for messages.
+      #
+      # @param code [Integer]
+      # @return [String]
+      def self.describe(code)
+        format("IOReturn 0x%08X", code & 0xFFFF_FFFF)
+      end
+
+      # An open IOHIDDevice.
+      class Handle
+        # @param device [FFI::Pointer] an IOHIDDeviceRef retained for this handle, which
+        #   releases it on {#close}
+        # @param serial [String, nil] named in error messages
+        def initialize(device, serial: nil)
+          @device = device
+          @serial = serial
+          @closed = false
+        end
+
+        # Sends a feature report.
+        #
+        # @param report [String] binary String whose first byte is the report ID
+        # @raise [ClosedError] after {#close}
+        # @raise [DisconnectedError] when the stick is unplugged
+        # @raise [TransferFailed] for any other failed transfer
+        def write_feature(report)
+          raise ClosedError, "#{name} is closed" if @closed
+
+          code = Native.hid_device_set_report(@device, REPORT_TYPE_FEATURE, report.getbyte(0), report,
+                                              report.bytesize)
+          return if code.zero?
+
+          raise IOKit.error_for(code), "#{name}: writing a report failed (#{IOKit.describe(code)})"
+        end
+
+        # Closes the device, then releases the reference the handle owns.
+        # Calling it again does nothing, and it never raises.
+        #
+        # @return [void]
+        def close
+          return if @closed
+
+          @closed = true
+          begin
+            Native.hid_device_close(@device, OPEN_OPTIONS)
+          ensure
+            Native.release(@device)
+          end
+          nil
+        end
+
+        private
+
+        def name
+          @serial || "the stick"
+        end
+      end
+
+      # @return [Array<Device>] every BlinkStick attached
+      def list
+        keys = PROPERTY_KEYS.to_h { |key| [key, Native.string(key)] }
+        manager = Native.hid_manager_create(nil, OPEN_OPTIONS)
+        raise Error, "IOKit could not create an IOHIDManager" if manager.null?
+
+        match(manager, keys)
+        copy_devices(manager).map { |ref| device_for(ref, keys) }
+      ensure
+        Native.release(manager)
+        keys&.each_value { |key| Native.release(key) }
+      end
+
+      # Retains the device reference for the handle, so the handle never
+      # depends on the listed {Device} staying alive. The retain is released
+      # here if the open fails, and by {Handle#close} otherwise.
+      #
+      # @param device [Device] a device from {#list}
+      # @return [Handle]
+      # @raise [NotFoundError, PermissionError, BusyError] when it cannot be opened
+      def open(device)
+        ref = Native.cf_retain(device.id)
+        code = Native.hid_device_open(ref, OPEN_OPTIONS)
+        return handle = Handle.new(ref, serial: device.serial) if code.zero?
+
+        error = IOKit.open_error_for(code)
+        reason = OPEN_REASONS.fetch(error, "the OS refused")
+        raise error, "Could not open #{device.serial}: #{reason} (#{IOKit.describe(code)})"
+      ensure
+        Native.release(ref) unless handle
+      end
+
+      private
+
+      def match(manager, keys)
+        dict = Native.cf_dictionary_create_mutable(nil, 2, Native.global("kCFTypeDictionaryKeyCallBacks"),
+                                                   Native.global("kCFTypeDictionaryValueCallBacks"))
+        { "VendorID" => VENDOR_ID, "ProductID" => PRODUCT_ID }.each do |key, id|
+          Native.cf_dictionary_set_value(dict, keys.fetch(key), number = Native.number(id))
+        ensure
+          Native.release(number)
+        end
+        Native.hid_manager_set_device_matching(manager, dict)
+      ensure
+        Native.release(dict)
+      end
+
+      # Retains each device before the set that holds it is released.
+      def copy_devices(manager)
+        set = Native.hid_manager_copy_devices(manager)
+        return [] if set.null?
+
+        count = Native.cf_set_get_count(set)
+        values = FFI::MemoryPointer.new(:pointer, count)
+        Native.cf_set_get_values(set, values)
+        values.read_array_of_pointer(count).map do |ref|
+          FFI::AutoPointer.new(Native.cf_retain(ref), Native.method(:cf_release))
+        end
+      ensure
+        Native.release(set)
+      end
+
+      # Properties are borrowed (the Get rule), so nothing read here is released.
+      def device_for(ref, keys)
+        property = ->(key) { Native.hid_device_get_property(ref, keys.fetch(key)) }
+        Device.new(id: ref, serial: Native.read_string(property["SerialNumber"]),
+                   manufacturer: Native.read_string(property["Manufacturer"]),
+                   product: Native.read_string(property["Product"]),
+                   release: Native.read_integer(property["VersionNumber"]))
+      end
+    end
+  end
+end