ruby-blinkstick 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 538eb17c6e17b2bdaff6ca9b2f39d1c34196d0c72ce7dffee3b57d47a04131b7
-  data.tar.gz: e3f10dcdf64efcd8913052ce3f0b0afe7493a1bae9d705ccdb0b5cb7bea788f2
+  metadata.gz: dbeec7298582de4220e66562a9fadfd994fc540c920b6af2da8ea0b91cbc7cee
+  data.tar.gz: d016a0be08f195f84e43a1e663a7b70c49d8174d4a1fba2b1332cc70c6159c7b
 SHA512:
-  metadata.gz: 17438f01d70babc376163f338220a536daaf11e3704efb69b3748d19b460f58e565f613e4c2d81ad457fa47d2a9c4ed66eaa64cefa0d794397d1443905e19281
-  data.tar.gz: 56c068d7cbcfc9094988b69abd46c95b9ba60414e253549a2aed7a720793dbced76e8b87247aee7c2c7ba865890696c469aab0979ad40f88d57b4eea58159d3b
+  metadata.gz: c66054616d8981e5c256a19a27f88c0e4bf6ee4046f86e3a554eea7b34cda60f9546a93cf19a9ba8e43723f888d4b6af88dd3948cf7bd9ded0e549d14d29f027
+  data.tar.gz: a1d96c324d7793c6c4cf4a1193f97e07de2a2f162bd0aaff4a6589b95649fc76234b2d0c535b3467874a2fe0347b9198669194d5c3b92fd635bdc5fb0e08dd74

data/CAPABILITIES.md

@@ -21,12 +21,12 @@ Features built into the BlinkStick firmware.
 | 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 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 |
+| 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 |

data/CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to this project are recorded here. The format follows
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-28
+
+### Added
+
+- `Stick#[]=` sets one LED and leaves the others as they are, using one report. A bad index raises `IndexError`.
+- `Stick#frame=` sets every LED at once, one colour each. It needs exactly one colour per LED of the model, and nothing is sent if any colour is invalid.
+- `Stick#frame` and `Stick#[]` read the LEDs back as `Colour` values. Reads always ask the stick, and a failing read raises `DisconnectedError` after three attempts.
+- `Stick#mode` reads the device mode as `:rgb`, `:rgb_inverse`, `:ws2812` or `:ws2812_mirror`, or the raw byte for a mode the gem does not know.
+- `Stick#info_block` reads info block 1 or 2, read only. The bytes are whatever any tool last wrote, so treat them as untrusted.
+
 ## [0.1.0] - 2026-10-28
 
 ### Added

data/README.md

@@ -12,10 +12,11 @@ of BlinkStick.
 
 ## Status
 
-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.
+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.
 
 ## Install
 
@@ -55,6 +56,8 @@ Blinkstick.open do |stick|         # the first stick; the block form closes it,
   stick.colour = :cornflowerblue   # set every LED
   stick.colour = "#ff8800"
   stick.colour = [255, 136, 0]
+  stick[0] = :red                  # set one LED, the others stay as they are
+  stick.frame = Array.new(stick.info.model.leds) { |i| i.even? ? :red : :green }  # every LED at once, one colour each
   stick.off                        # every LED off
 end
 
@@ -70,10 +73,42 @@ Blinkstick::Colour.names.first(3)           # => ["aliceblue", "antiquewhite", "
 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.
 
+`stick[i] = colour` sends one report and leaves the other LEDs alone. The index runs from 0
+to one less than the model's LED count (a Nano takes 0 or 1, a Square 0 to 7), and a bad index raises
+`IndexError`; negative indexes are refused, not counted from the end. `stick.frame = colours`
+needs exactly one colour per LED, so a Nano takes 2 and a Square 8. A wrong count raises
+`ArgumentError`, and something that is not an array raises `TypeError`. Every colour is checked
+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`.
 
+### Reading a stick
+
+```ruby
+Blinkstick.open do |stick|
+  stick.frame            # => [#<data Blinkstick::Colour red=255, green=0, blue=0>, ...]
+  stick[0]               # => #<data Blinkstick::Colour red=255, green=0, blue=0>
+  stick.mode             # => :ws2812
+  stick.info_block(1)    # => "" or up to 32 bytes, a binary String
+end
+```
+
+- `stick.frame` returns a frozen Array with one `Colour` per LED of the model (2 for a Nano,
+  8 for a Square), and `stick[i]` returns one of them.
+- Reads always ask the stick. Nothing is cached, so you see what the stick shows now, even if
+  another program changed it.
+- `stick.mode` is `:rgb`, `:rgb_inverse`, `:ws2812` or `:ws2812_mirror`. A byte the gem does
+  not know comes back as an Integer.
+- `stick.info_block(1)` and `stick.info_block(2)` return the 32 byte user data blocks with
+  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.
+
 ### Sharing a stick
 
 Sticks are shared on both platforms, so several programs (and several Ruby processes) can

data/lib/blinkstick/backend/hidraw.rb

@@ -20,6 +20,15 @@ module Blinkstick
         (3 << 30) | (length << 16) | (0x48 << 8) | 0x06
       end
 
+      # The ioctl request number for HIDIOCGFEATURE of the given length:
+      # direction read/write (3), size, type 'H' (0x48) and number 7.
+      #
+      # @param length [Integer] report size in bytes, including the ID byte
+      # @return [Integer]
+      def self.get_feature_request(length)
+        (3 << 30) | (length << 16) | (0x48 << 8) | 0x07
+      end
+
       # An open hidraw node.
       class Handle
         # @param io [#ioctl, #close] the open device node
@@ -37,15 +46,26 @@ module Blinkstick
         # @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
+          transfer { @io.ioctl(Hidraw.set_feature_request(report.bytesize), report.dup) }
+        end
 
-          @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}"
+        # Reads a feature report from the stick.
+        #
+        # @param report_id [Integer] the report to ask for
+        # @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 [ClosedError] after {#close}
+        # @raise [DisconnectedError] when the stick is unplugged
+        # @raise [TransferFailed] for any other failed transfer
+        def read_feature(report_id, size)
+          transfer do
+            buffer = ("\x00".b * size)
+            buffer.setbyte(0, report_id)
+            count = @io.ioctl(Hidraw.get_feature_request(size), buffer)
+            # IO#ioctl may grow the buffer, so trust its return value, not the length.
+            count.positive? ? buffer.byteslice(0, count) : "".b
+          end
         end
 
         # Releases the node. Calling it again does nothing, and it never raises.
@@ -64,6 +84,19 @@ module Blinkstick
 
         private
 
+        # Runs one transfer, mapping the OS's errors onto ours.
+        def transfer
+          raise ClosedError, "#{name} is closed" if @closed
+
+          yield
+        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
+
         def name
           @serial || "the stick"
         end

data/lib/blinkstick/backend/iokit.rb

@@ -5,9 +5,10 @@ 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.
+    # The macOS backend. It finds sticks with an IOHIDManager and moves
+    # feature reports with IOHIDDeviceSetReport and IOHIDDeviceGetReport,
+    # 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
@@ -57,6 +58,7 @@ module Blinkstick
         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
+        attach_function :hid_device_get_report, :IOHIDDeviceGetReport, %i[pointer int long buffer_inout pointer], :int
 
         UTF8 = 0x08000100 # kCFStringEncodingUTF8
         SINT32 = 3 # kCFNumberSInt32Type
@@ -149,7 +151,8 @@ module Blinkstick
       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.
+      # Maps a failed IOHIDDeviceSetReport or IOHIDDeviceGetReport to the
+      # error a handle raises.
       #
       # @param code [Integer] the IOReturn, signed or unsigned
       # @return [Class] a {Blinkstick::Error} subclass
@@ -201,13 +204,30 @@ module Blinkstick
         # @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?
+          ensure_open
+          check(Native.hid_device_set_report(@device, REPORT_TYPE_FEATURE, report.getbyte(0), report,
+                                             report.bytesize), "writing")
+        end
 
-          raise IOKit.error_for(code), "#{name}: writing a report failed (#{IOKit.describe(code)})"
+        # Reads a feature report. The report ID stays as the buffer's first
+        # byte and the length cell starts at size, so the length IOKit hands
+        # back counts the ID (as hidapi's macOS get_report does for a non-zero
+        # ID). Only a run against real hardware confirms this.
+        #
+        # @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 [ClosedError] after {#close}
+        # @raise [DisconnectedError] when the stick is unplugged
+        # @raise [TransferFailed] for any other failed transfer
+        def read_feature(report_id, size)
+          ensure_open
+          buffer = FFI::MemoryPointer.new(:uint8, size)
+          buffer.put_uint8(0, report_id)
+          length = FFI::MemoryPointer.new(:long) # CFIndex
+          length.write_long(size)
+          check(Native.hid_device_get_report(@device, REPORT_TYPE_FEATURE, report_id, buffer, length), "reading")
+          buffer.read_bytes(length.read_long.clamp(0, size))
         end
 
         # Closes the device, then releases the reference the handle owns.
@@ -231,6 +251,16 @@ module Blinkstick
         def name
           @serial || "the stick"
         end
+
+        def ensure_open
+          raise ClosedError, "#{name} is closed" if @closed
+        end
+
+        def check(code, action)
+          return if code.zero?
+
+          raise IOKit.error_for(code), "#{name}: #{action} a report failed (#{IOKit.describe(code)})"
+        end
       end
 
       # @return [Array<Device>] every BlinkStick attached

data/lib/blinkstick/backend.rb

@@ -10,9 +10,12 @@ module 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.
+  # byte is the report ID; to `#read_feature(report_id, size)`, returning a
+  # binary String whose first byte is the report ID and whose length is the
+  # number of bytes the OS returned (size includes the ID byte); and to
+  # `#close`, which may be called more than once. Handles raise
+  # {Blinkstick::Error} subclasses, or {TransferFailed} for a failure worth
+  # trying again, from either transfer.
   #
   # @api private
   module Backend

data/lib/blinkstick/report.rb

@@ -26,5 +26,74 @@ module Blinkstick
       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
+
+    # Report ID of a single LED write.
+    LED_ID = 5
+
+    # Single LED report size in bytes: ID, channel, index, then R, G, B.
+    LED_SIZE = 6
+
+    # Builds report 5 for channel 0. Unlike the frame, the colour is R, G, B.
+    #
+    # @param index [Integer] LED index, 0 to 255
+    # @param colour [Colour]
+    # @return [String] frozen binary String of {LED_SIZE} bytes
+    # @raise [ArgumentError] unless index is an Integer from 0 to 255
+    def self.led(index, colour)
+      raise ArgumentError, "LED index must be an Integer from 0 to 255, got #{index.inspect}" unless
+        index.is_a?(Integer) && index.between?(0, 255)
+
+      [LED_ID, 0, index, colour.red, colour.green, colour.blue].pack("C*").freeze
+    end
+
+    # Reads the first LEDs of a report 6 (G, R, B per slot).
+    #
+    # @param bytes [Array<Integer>, String] the {FRAME_SIZE} byte report
+    # @param count [Integer] LEDs to decode, at most {FRAME_LEDS}
+    # @return [Array<Colour>] frozen
+    def self.decode_frame(bytes, count)
+      bytes = bytes.bytes if bytes.is_a?(String)
+      Array.new(count) do |i|
+        green, red, blue = bytes[2 + (i * 3), 3]
+        Colour.new(red:, green:, blue:)
+      end.freeze
+    end
+
+    # Report ID of the LED mode.
+    MODE_ID = 4
+
+    # Mode report size in bytes: ID, then the mode.
+    MODE_SIZE = 2
+
+    # Device mode bytes and their names.
+    MODES = { 0 => :rgb, 1 => :rgb_inverse, 2 => :ws2812, 3 => :ws2812_mirror }.freeze
+
+    # @param bytes [Array<Integer>, String] the {MODE_SIZE} byte report
+    # @return [Symbol, Integer] the mode name, or the raw byte when unknown
+    def self.decode_mode(bytes)
+      byte = bytes.is_a?(String) ? bytes.getbyte(1) : bytes[1]
+      MODES.fetch(byte, byte)
+    end
+
+    # Info block report size in bytes: ID, then 32 data bytes.
+    INFO_BLOCK_SIZE = 33
+
+    # @param number [Integer] info block 1 or 2
+    # @return [Integer] the report ID to read (2 or 3)
+    # @raise [ArgumentError] unless number is 1 or 2
+    def self.info_block_id(number)
+      case number
+      when 1 then 2
+      when 2 then 3
+      else raise ArgumentError, "info block must be 1 or 2, got #{number.inspect}"
+      end
+    end
+
+    # @param bytes [Array<Integer>, String] the {INFO_BLOCK_SIZE} byte report
+    # @return [String] frozen ASCII-8BIT text with trailing NULs removed
+    def self.decode_info_block(bytes)
+      bytes = bytes.bytes if bytes.is_a?(String)
+      bytes[1, INFO_BLOCK_SIZE - 1].pack("C*").sub(/\0+\z/n, "").freeze
+    end
   end
 end

data/lib/blinkstick/stick.rb

@@ -4,7 +4,8 @@ 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
+  # report written to or read from the device, and reads always ask the
+  # 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.
   class Stick
@@ -12,7 +13,7 @@ module Blinkstick
     attr_reader :info
 
     # @api private
-    # @param handle [#write_feature, #close] an open backend handle
+    # @param handle [#write_feature, #read_feature, #close] an open backend handle
     # @param info [Info]
     def initialize(handle, info)
       @handle = handle
@@ -41,15 +42,110 @@ module Blinkstick
     # @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 [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 colour=(colour)
       write(Report.frame([Colour.parse(colour)] * info.model.leds))
     end
 
+    # Sets one LED, leaving the others as they are.
+    #
+    # @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)
+    # @param colour [Colour, String, Symbol, Array<Integer>] anything {Colour.parse} takes
+    # @return [Colour, String, Symbol, Array<Integer>] colour, as Ruby assignment does
+    # @raise [IndexError] when index is not an Integer within the model's LEDs
+    # @raise [InvalidColourError] when colour is not a colour (both checked before anything is sent)
+    # @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, colour)
+      parsed = Colour.parse(colour)
+      check_index(index)
+      write(Report.led(index, parsed))
+      colour
+    end
+
+    # Sets every LED at once, one colour each, in a single report.
+    #
+    # @param colours [Array<Colour, String, Symbol, Array<Integer>>] exactly one per LED of the model
+    # @raise [TypeError] when colours is not array like
+    # @raise [ArgumentError] when colours has the wrong length
+    # @raise [InvalidColourError] when any entry is not a colour
+    # @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=(colours)
+      list = Array.try_convert(colours)
+      raise TypeError, "frame must be an Array of colours, got #{colours.class}" if list.nil?
+
+      model = info.model
+      unless list.size == model.leds
+        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)
+    end
+
+    # Reads the LED mode from the stick.
+    #
+    # @return [Symbol, Integer] :rgb, :rgb_inverse, :ws2812 or :ws2812_mirror,
+    #   or the raw byte for a mode the gem does not know
+    # @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 mode
+      Report.decode_mode(read(Report::MODE_ID, Report::MODE_SIZE))
+    end
+
+    # Reads a user data block from the stick.
+    #
+    # @param number [Integer] 1 or 2
+    # @return [String] frozen binary String, up to 32 bytes, trailing NULs removed
+    # @raise [ArgumentError] before anything is sent, when number is not 1 or 2
+    # @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 info_block(number)
+      Report.decode_info_block(read(Report.info_block_id(number), Report::INFO_BLOCK_SIZE))
+    end
+
     # Turns every LED off.
     #
     # @return [void]
     # @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 off
       self.colour = Colour::OFF
@@ -77,27 +173,56 @@ module Blinkstick
 
     private
 
-    # Holds the lock across every attempt, so reports from other threads
-    # cannot land in between.
+    # @raise [IndexError] unless index is an Integer from 0 to the model's LEDs
+    def check_index(index)
+      model = info.model
+      return if index.is_a?(Integer) && index >= 0 && index < model.leds
+
+      raise IndexError, "LED #{index.inspect} is out of range: a #{model.name} has #{model.leds} LEDs"
+    end
+
+    # Sends a report.
     def write(report)
+      transfer("writes") { @handle.write_feature(report) }
+    end
+
+    # Reads a report. A reply that is short or carries another report's ID
+    # counts as a failed attempt, so it is retried and never decoded.
+    #
+    # @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
+    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
 
-        transfer(report)
+        with_retries(what, &)
       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)
+    # 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
-        @handle.write_feature(report)
+        yield
       rescue Backend::TransferFailed
         retry if attempt < Backend::ATTEMPTS
 
-        raise DisconnectedError, "#{info.serial} stopped responding: #{attempt} writes failed in a row"
+        raise DisconnectedError, "#{info.serial} stopped responding: #{attempt} #{what} failed in a row"
       end
     end
   end

data/lib/blinkstick/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-blinkstick
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Keith Bawden