ruby-blinkstick 0.2.0 → 0.3.0

data/lib/blinkstick/report.rb

@@ -51,8 +51,10 @@ module Blinkstick
     # @param bytes [Array<Integer>, String] the {FRAME_SIZE} byte report
     # @param count [Integer] LEDs to decode, at most {FRAME_LEDS}
     # @return [Array<Colour>] frozen
+    # @raise [ArgumentError] when given fewer than {FRAME_SIZE} bytes
     def self.decode_frame(bytes, count)
       bytes = bytes.bytes if bytes.is_a?(String)
+      require_size(bytes, FRAME_SIZE)
       Array.new(count) do |i|
         green, red, blue = bytes[2 + (i * 3), 3]
         Colour.new(red:, green:, blue:)
@@ -70,7 +72,9 @@ module Blinkstick
 
     # @param bytes [Array<Integer>, String] the {MODE_SIZE} byte report
     # @return [Symbol, Integer] the mode name, or the raw byte when unknown
+    # @raise [ArgumentError] when given fewer than {MODE_SIZE} bytes
     def self.decode_mode(bytes)
+      require_size(bytes, MODE_SIZE)
       byte = bytes.is_a?(String) ? bytes.getbyte(1) : bytes[1]
       MODES.fetch(byte, byte)
     end
@@ -91,9 +95,45 @@ module Blinkstick
 
     # @param bytes [Array<Integer>, String] the {INFO_BLOCK_SIZE} byte report
     # @return [String] frozen ASCII-8BIT text with trailing NULs removed
+    # @raise [ArgumentError] when given fewer than {INFO_BLOCK_SIZE} bytes
     def self.decode_info_block(bytes)
       bytes = bytes.bytes if bytes.is_a?(String)
+      require_size(bytes, INFO_BLOCK_SIZE)
       bytes[1, INFO_BLOCK_SIZE - 1].pack("C*").sub(/\0+\z/n, "").freeze
     end
+
+    # Builds report 2 or 3 to write an info block.
+    #
+    # @param number [Integer] info block 1 or 2
+    # @param bytes [String] at most 32 bytes (its raw bytes are sent)
+    # @return [String] frozen binary String of {INFO_BLOCK_SIZE} bytes
+    # @raise [ArgumentError] unless number is 1 or 2, or when bytes is over 32 bytes
+    def self.info_block(number, bytes)
+      id = info_block_id(number)
+      data = bytes.b
+      raise ArgumentError, "info block holds at most #{INFO_BLOCK_SIZE - 1} bytes, got #{data.bytesize}" if
+        data.bytesize > INFO_BLOCK_SIZE - 1
+
+      ([id].pack("C") + data).ljust(INFO_BLOCK_SIZE, "\0".b).freeze
+    end
+
+    # Builds report 4 to set the LED mode.
+    #
+    # @param byte [Integer] the mode byte, 0 to 255
+    # @return [String] frozen binary String of {MODE_SIZE} bytes
+    # @raise [ArgumentError] unless byte is an Integer from 0 to 255
+    def self.mode(byte)
+      raise ArgumentError, "mode must be an Integer from 0 to 255, got #{byte.inspect}" unless
+        byte.is_a?(Integer) && byte.between?(0, 255)
+
+      [MODE_ID, byte].pack("C*").freeze
+    end
+
+    # @raise [ArgumentError] when bytes is shorter than size
+    def self.require_size(bytes, size)
+      length = bytes.respond_to?(:bytesize) ? bytes.bytesize : bytes.size
+      raise ArgumentError, "report needs #{size} bytes, got #{length}" if length < size
+    end
+    private_class_method :require_size
   end
 end

data/lib/blinkstick/stick/eeprom.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Blinkstick
+  class Stick
+    # The parts of a {Stick} that write the stick's EEPROM: its name, its
+    # user data blocks and its LED mode. EEPROM wears with every write, so
+    # none of these belongs in a loop.
+    module Eeprom
+      # Modes this gem will set, by the byte the stick stores. The BlinkStick
+      # Pro modes (0 and 1) are refused.
+      SETTABLE_MODES = { ws2812: 2, ws2812_mirror: 3 }.freeze
+      private_constant :SETTABLE_MODES
+
+      # Seconds between reads while waiting for the stick to answer after a
+      # mode write.
+      MODE_POLL_INTERVAL = 0.005
+      private_constant :MODE_POLL_INTERVAL
+
+      # Seconds to wait for the stick to answer after a mode write. A real
+      # stick refuses transfers for 12 to 15 ms while it stores the mode.
+      MODE_SETTLE_TIMEOUT = 0.25
+      private_constant :MODE_SETTLE_TIMEOUT
+
+      # Writes a user data block, padded with NULs to 32 bytes. This writes
+      # EEPROM, which wears with use, so do not call it in a loop.
+      #
+      # @param number [Integer] 1 or 2 (block 1 holds the {#name})
+      # @param bytes [String] at most 32 bytes (its raw bytes are stored, whatever its encoding)
+      # @return [nil]
+      # @raise [ArgumentError] before anything is sent, when number is not 1 or 2 or bytes is over 32 bytes
+      # @raise [TypeError] before anything is sent, when bytes is not a String
+      # @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 and reconnecting to it fails
+      def write_info_block(number, bytes)
+        data = String.try_convert(bytes)
+        raise TypeError, "info block data must be a String, got #{bytes.class}" if data.nil?
+
+        write(Report.info_block(number, data))
+        nil
+      end
+
+      # Reads the name stored on the stick (info block 1, as the official
+      # BlinkStick tools do). Another tool may have stored bytes that are not
+      # valid UTF-8 or that are control characters, and they are returned as
+      # they are: sanitise the name before printing it to a terminal.
+      #
+      # @return [String] frozen, tagged UTF-8, "" when no name is set
+      # @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 and reconnecting to it fails
+      def name
+        info_block(1).dup.force_encoding(Encoding::UTF_8).freeze
+      end
+
+      # Stores a name on the stick, replacing any name already there. This
+      # writes EEPROM, which wears with use, so do not call it in a loop.
+      #
+      # @param name [String] UTF-8 of at most 32 bytes with no NUL; "" clears the name
+      # @return [String] name, as Ruby assignment does
+      # @raise [TypeError] before anything is sent, when name is not a String
+      # @raise [ArgumentError] before anything is sent, when name is not valid UTF-8, holds a NUL or is over 32 bytes
+      # @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 and reconnecting to it fails
+      def name=(name)
+        raise TypeError, "name must be a String, got #{name.class}" unless name.is_a?(String)
+
+        check_name(name)
+        write_info_block(1, name)
+        name
+      end
+
+      # Sets the LED mode, unless the stick is already in it. This writes
+      # EEPROM, which wears with use, so call it once and not in a loop. The
+      # read and the write happen under one lock, so no other thread's
+      # transfer lands between them. A stick stops answering for a moment
+      # after storing its mode (typically 12 to 15 ms), so after a write this
+      # waits, still holding the lock, until the stick answers again and
+      # reports the new mode, giving up after 250 ms. No write means no wait.
+      #
+      # @param mode [Symbol, Integer] :ws2812 (or 2) or :ws2812_mirror (or 3).
+      #   The BlinkStick Pro modes (0, 1, :rgb, :rgb_inverse) are refused.
+      # @return [Symbol, Integer] mode, as Ruby assignment does
+      # @raise [ArgumentError] before anything is sent, when mode is not :ws2812, :ws2812_mirror, 2 or 3
+      # @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 and reconnecting to it fails,
+      #   or when it does not answer with the new mode within 250 ms of the write
+      def mode=(mode)
+        byte = settable_mode(mode)
+        locked do
+          current = with_reconnect("reads") { fetch(Report::MODE_ID, Report::MODE_SIZE) }
+          next if current.getbyte(1) == byte
+
+          with_reconnect("writes") { @handle.write_feature(Report.mode(byte)) }
+          await_mode(byte)
+        end
+        mode
+      end
+
+      private
+
+      # @raise [ArgumentError] unless name is UTF-8 without NULs, 32 bytes at most
+      def check_name(name)
+        bytes = name.b
+        unless bytes.dup.force_encoding(Encoding::UTF_8).valid_encoding? && !bytes.include?("\0")
+          raise ArgumentError, "name must be UTF-8 without NUL characters"
+        end
+        return if bytes.bytesize <= Report::INFO_BLOCK_SIZE - 1
+
+        raise ArgumentError, "name is #{bytes.bytesize} bytes, the most a stick holds is #{Report::INFO_BLOCK_SIZE - 1}"
+      end
+
+      # Reads the mode every MODE_POLL_INTERVAL until the stick answers with
+      # byte, without retries or reconnecting. The caller must hold the lock.
+      # BusyError, PermissionError and DisconnectedError from the handle pass
+      # through.
+      #
+      # @raise [DisconnectedError] when no read shows byte within MODE_SETTLE_TIMEOUT
+      def await_mode(byte)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + MODE_SETTLE_TIMEOUT
+        until mode_reads?(byte)
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            raise DisconnectedError, "#{info.serial.inspect} did not answer after the mode write " \
+                                     "(waited #{(MODE_SETTLE_TIMEOUT * 1000).round} ms)"
+          end
+
+          sleep MODE_POLL_INTERVAL
+        end
+      end
+
+      # One raw read of the mode. A failed attempt or a bad reply counts as
+      # not yet.
+      #
+      # @return [Boolean] true when the stick answered with byte
+      def mode_reads?(byte)
+        fetch(Report::MODE_ID, Report::MODE_SIZE).getbyte(1) == byte
+      rescue Backend::TransferFailed
+        false
+      end
+
+      # @return [Integer] the mode byte
+      # @raise [ArgumentError] unless mode is :ws2812, :ws2812_mirror, 2 or 3
+      def settable_mode(mode)
+        byte = mode.is_a?(Integer) ? mode : SETTABLE_MODES[mode]
+        return byte if SETTABLE_MODES.value?(byte)
+
+        raise ArgumentError, "mode must be :ws2812, :ws2812_mirror, 2 or 3, got #{mode.inspect} " \
+                             "(the other modes are for the BlinkStick Pro, which this gem does not support)"
+      end
+    end
+  end
+end

data/lib/blinkstick/stick/effects.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Blinkstick
+  class Stick
+    # Blink, pulse and morph, ported from go-blinkstick's effects.go. Each
+    # blocks the calling thread (no thread is spawned), pauses with
+    # <tt>cancel.wait(seconds)</tt> so a {Cancellation} cuts it short, and
+    # takes the Stick's lock per transfer, not for the whole effect.
+    #
+    # Two effects running on one stick at once interleave their frames; that
+    # is documented, not prevented. A cancelled effect returns false and
+    # leaves the LEDs as they are.
+    module Effects
+      # Seconds between morph steps.
+      STEP = 0.02
+
+      # STEP in integer nanoseconds, for counting steps as Go does.
+      STEP_NS = (STEP * 1_000_000_000).round
+      private_constant :STEP, :STEP_NS
+
+      # Flashes every LED on and off, ending off.
+      #
+      # @param colour [Colour, String, Symbol, Array<Integer>] anything {Colour.parse} takes
+      # @param period [Numeric] seconds per flash, finite and above 0 (half on, half off)
+      # @param repeats [Integer] how many flashes, 1 or more
+      # @param cancel [#cancelled?, #wait, nil] a {Cancellation} (or anything with
+      #   its two methods); nil makes pauses plain timed waits
+      # @return [Boolean] true when it ran to the end, false when cancelled
+      # @raise [InvalidColourError] before anything is sent, when colour is not a colour
+      # @raise [ArgumentError] before anything is sent, when period or repeats is out of range
+      # @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 and reconnecting to it fails
+      def blink(colour, period:, repeats: 1, cancel: nil)
+        target = Colour.parse(colour)
+        check_time(:period, period, positive: true)
+        check_repeats(repeats)
+        cancel ||= Cancellation.new
+        half = period / 2.0
+        repeats.times.all? do
+          beat(cancel, half) { self.colour = target } && beat(cancel, half) { off }
+        end
+      end
+
+      # Fades every LED up to a colour and back down, starting and ending off.
+      #
+      # @param colour [Colour, String, Symbol, Array<Integer>] anything {Colour.parse} takes
+      # @param duration [Numeric] seconds per pulse, finite and above 0 (half up, half down)
+      # @param repeats [Integer] how many pulses, 1 or more
+      # @param cancel [#cancelled?, #wait, nil] a {Cancellation} (or anything with
+      #   its two methods); nil makes pauses plain timed waits
+      # @return [Boolean] true when it ran to the end, false when cancelled
+      # @raise [InvalidColourError] before anything is sent, when colour is not a colour
+      # @raise [ArgumentError] before anything is sent, when duration or repeats is out of range
+      # @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 and reconnecting to it fails
+      def pulse(colour, duration:, repeats: 1, cancel: nil)
+        target = Colour.parse(colour)
+        check_time(:duration, duration, positive: true)
+        check_repeats(repeats)
+        cancel ||= Cancellation.new
+        half = duration / 2.0
+        repeats.times.all? do
+          beat(cancel, 0) { off } && fade(target, half, cancel) && fade(Colour::OFF, half, cancel)
+        end
+      end
+
+      # Fades every LED from what the stick shows now to a colour, in 20 ms
+      # steps. The colour is brightness limited once, so a fade to full red at
+      # a limit of 128 ends at 128, not 64. A duration under one step jumps
+      # straight to the colour.
+      #
+      # @param colour [Colour, String, Symbol, Array<Integer>] anything {Colour.parse} takes
+      # @param duration [Numeric] seconds, finite and 0 or more
+      # @param cancel [#cancelled?, #wait, nil] a {Cancellation} (or anything with
+      #   its two methods); nil makes pauses plain timed waits
+      # @return [Boolean] true when it ran to the end, false when cancelled
+      # @raise [InvalidColourError] before anything is sent, when colour is not a colour
+      # @raise [ArgumentError] before anything is sent, when duration is out of range
+      # @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 and reconnecting to it fails
+      def morph(colour, duration:, cancel: nil)
+        target = Colour.parse(colour)
+        check_time(:duration, duration, positive: false)
+        fade(target, duration, cancel || Cancellation.new)
+      end
+
+      private
+
+      # Fades from the stick's frame to target; see {#morph}.
+      def fade(target, duration, cancel)
+        return false if cancel.cancelled?
+
+        from = frame
+        to = brightness_scaled(target)
+        # Integer nanoseconds as Go does: 0.58 s is 29 steps, where float division gives 28.
+        steps = [(duration * 1_000_000_000).round / STEP_NS, 1].max
+        (1..steps).all? do |step|
+          next false if cancel.cancelled?
+
+          write_frame(from.map { |start| lerp(start, to, step, steps) }, scale: false)
+          step == steps || !cancel.wait(STEP)
+        end
+      end
+
+      # Runs one write then pauses (a pause of 0 is skipped). Returns truthy
+      # to keep going; nil when cancelled before the write, false when the
+      # pause was cancelled.
+      def beat(cancel, seconds)
+        return if cancel.cancelled?
+
+        yield
+        !(seconds.positive? && cancel.wait(seconds))
+      end
+
+      # The colour step/steps of the way from one colour to another.
+      def lerp(from, target, step, steps)
+        Colour.new(red: towards(from.red, target.red, step, steps),
+                   green: towards(from.green, target.green, step, steps),
+                   blue: towards(from.blue, target.blue, step, steps))
+      end
+
+      # One channel: a + (b - a) * step / steps, truncating towards zero as Go
+      # does (Integer#/ would floor).
+      def towards(from, target, step, steps)
+        delta = (target - from) * step
+        from + (delta.negative? ? -(-delta / steps) : delta / steps)
+      end
+
+      def check_time(name, seconds, positive:)
+        ok = seconds.is_a?(Numeric) && seconds.real? && seconds.to_f.finite? &&
+             (positive ? seconds.positive? : seconds >= 0)
+        return if ok
+
+        bound = positive ? "above 0" : "of 0 or more"
+        raise ArgumentError, "#{name} must be a finite number #{bound}, got #{seconds.inspect}"
+      end
+
+      def check_repeats(repeats)
+        return if repeats.is_a?(Integer) && repeats >= 1
+
+        raise ArgumentError, "repeats must be an Integer of 1 or more, got #{repeats.inspect}"
+      end
+    end
+  end
+end

data/lib/blinkstick/stick/handover.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Blinkstick
+  class Stick
+    # Passing an open handle from one {Stick} to another.
+    #
+    # @api private
+    module Handover
+      # Gives up the open handle without closing it, leaving this stick closed
+      # and its finaliser removed, so the handle can go to a new Stick. A
+      # closed stick no longer owns its handle, so it refuses.
+      #
+      # @api private
+      # @return [#write_feature, #read_feature, #close] the handle, still open
+      # @raise [ClosedError] after {Stick#close} or an earlier detach
+      def detach
+        @mutex.synchronize do
+          raise ClosedError, "#{info.serial} is closed" if @closed
+
+          @closed = true
+          ObjectSpace.undefine_finalizer(self)
+          @handle
+        end
+      end
+    end
+  end
+end

data/lib/blinkstick/stick/lighting.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Blinkstick
+  class Stick
+    # The LED write path of a {Stick}: the brightness limit, inverse, and the
+    # last frame written (which a reconnect repaints). All state is guarded by
+    # the Stick's lock.
+    module Lighting
+      # @return [Integer] the brightness limit, 0 to 255 (255 by default)
+      def brightness_limit
+        @mutex.synchronize { @limit }
+      end
+
+      # Caps every channel of every write from now on: a channel v is sent as
+      # <tt>v * limit / 255</tt> (Integer division). Reads return what the stick
+      # holds, so they are never scaled back up. Per Stick, not stored on the
+      # device, and it does not repaint what is already lit.
+      #
+      # @param limit [Integer] 0 to 255
+      # @raise [ArgumentError] unless limit is an Integer from 0 to 255
+      def brightness_limit=(limit)
+        raise ArgumentError, "brightness limit must be an Integer from 0 to 255, got #{limit.inspect}" unless
+          limit.is_a?(Integer) && limit.between?(0, 255)
+
+        @mutex.synchronize { @limit = limit }
+      end
+
+      # @return [Boolean] whether writes are flipped to 255 minus the value
+      def inverse?
+        @mutex.synchronize { @inverse }
+      end
+
+      # Flips every channel written from now on to <tt>255 - v</tt>, after the
+      # brightness limit, for LEDs wired so 255 is off. Reads flip back, so
+      # {Stick#frame} and {Stick#[]} return what was written. It does not
+      # repaint, so set it before setting LEDs. Not the firmware inverse mode.
+      #
+      # @param on [Object] truthiness is stored as true or false
+      def inverse=(on)
+        @mutex.synchronize { @inverse = on ? true : false }
+      end
+
+      # Reads every LED back from the stick. Nothing is cached: each call asks
+      # the stick. Values are what the stick holds (after the brightness limit),
+      # flipped back when {#inverse?} is on.
+      #
+      # @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 and reconnecting to it fails
+      def frame
+        transfer("reads") { flipped_frame }
+      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 (Nano 0 or 1, 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 and reconnecting to it fails
+      def [](index)
+        check_index(index)
+        frame.fetch(index)
+      end
+
+      private
+
+      # Scales, flips and sends a whole frame, then records it (scaled, not
+      # flipped) as the last frame. Takes the lock itself.
+      #
+      # @param colours [Array<Colour>] one per LED of the model
+      # @param scale [Boolean] false to skip the brightness limit
+      def write_frame(colours, scale: true)
+        transfer("writes", frame_write: true) do
+          limited = scale ? colours.map { |colour| scaled(colour) } : colours.dup
+          @handle.write_feature(Report.frame(limited.map { |colour| flipped(colour) }))
+          @last = limited.freeze
+        end
+      end
+
+      # Sends one LED, seeding the last frame from the stick first when
+      # nothing has been written yet. One lock hold covers both.
+      def write_led(index, colour)
+        locked do
+          @last ||= with_reconnect("reads") { flipped_frame }
+          limited = scaled(colour)
+          with_reconnect("writes") { @handle.write_feature(Report.led(index, flipped(limited))) }
+          @last = @last.dup.tap { |frame| frame[index] = limited }.freeze
+        end
+      end
+
+      # One read of the frame, flipped back if inverse. The caller holds the lock.
+      def flipped_frame
+        frame = Report.decode_frame(fetch(Report::FRAME_ID, Report::FRAME_SIZE), info.model.leds)
+        @inverse ? frame.map(&:inverse).freeze : frame
+      end
+
+      # Applies the brightness limit, for a caller that does not hold the lock.
+      def brightness_scaled(colour)
+        @mutex.synchronize { scaled(colour) }
+      end
+
+      # Applies the brightness limit. The caller holds the lock.
+      def scaled(colour)
+        return colour if @limit == 255
+
+        Colour.new(red: colour.red * @limit / 255, green: colour.green * @limit / 255,
+                   blue: colour.blue * @limit / 255)
+      end
+
+      def flipped(colour)
+        @inverse ? colour.inverse : colour
+      end
+    end
+  end
+end

data/lib/blinkstick/stick/reconnect.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Blinkstick
+  class Stick
+    # How a {Stick} talks to its handle: under its lock, with retries, and
+    # finding the stick again after it was unplugged (ported from
+    # go-blinkstick's transferLocked and reconnectLocked). When a transfer
+    # runs out of attempts or the handle says the stick is gone, the handle is
+    # dropped, the stick reopened by serial, the last frame repainted and the
+    # transfer run again. Everything here runs under the Stick's lock.
+    #
+    # @api private
+    module Reconnect
+      private
+
+      # Holds the lock across every attempt and any reconnect, so transfers
+      # from other threads cannot land in between.
+      def transfer(what, frame_write: false, &)
+        locked { with_reconnect(what, frame_write:, &) }
+      end
+
+      # Holds the lock for one call, refusing a closed stick. Each call may
+      # reconnect once, however many transfers it makes.
+      def locked
+        @mutex.synchronize do
+          raise ClosedError, "#{info.serial} is closed" if @closed
+
+          @reconnected = false
+          yield
+        end
+      end
+
+      # Runs the block up to Backend::ATTEMPTS times while it raises
+      # TransferFailed. The caller must hold the lock.
+      def with_retries(what)
+        attempt = 0
+        begin
+          attempt += 1
+          yield
+        rescue Backend::TransferFailed
+          retry if attempt < Backend::ATTEMPTS
+
+          raise DisconnectedError, "#{info.serial.inspect} stopped responding: #{attempt} #{what} failed in a row"
+        end
+      end
+
+      # Runs one transfer, reconnecting once if it fails. A call that makes
+      # several transfers reconnects at most once in all: a later failure in
+      # the same call raises and keeps the new handle. BusyError,
+      # PermissionError and ClosedError pass through untouched.
+      #
+      # @param what [String] "reads" or "writes", for the error message
+      # @param frame_write [Boolean] true when the transfer is a whole frame
+      #   write, which repainting the old frame first would only flash
+      # @raise [DisconnectedError] when the transfer fails and reconnecting
+      #   cannot be tried, fails, or does not help
+      def with_reconnect(what, frame_write: false, &)
+        if @handle
+          begin
+            return with_retries(what, &)
+          rescue DisconnectedError
+            raise if @reopen.nil? || @reconnected
+
+            drop_handle
+          end
+        end
+        reconnect(repaint: !frame_write)
+        with_retries(what, &)
+      end
+
+      # Reopens the stick and repaints the last frame, if asked and there is
+      # one. Leaves no handle when either fails.
+      #
+      # @raise [DisconnectedError] naming the cause when either fails
+      def reconnect(repaint:)
+        @reconnected = true
+        adopt(reopen_handle)
+        repaint_last if repaint && @last
+      end
+
+      # The reopen's own message already names the serial (or says there is
+      # none), so it is not repeated here.
+      #
+      # @return [#write_feature, #read_feature, #close] a fresh handle
+      # @raise [DisconnectedError] wrapping whatever stopped the reopen
+      def reopen_handle
+        @reopen.call
+      rescue Error => e
+        raise DisconnectedError, "could not reconnect: #{e.message}"
+      end
+
+      # Sends the last frame again exactly as it was sent: already limited,
+      # so not limited again, and flipped if inverse is on. The failure's own
+      # message names the stick, so the serial is not repeated here.
+      #
+      # @raise [DisconnectedError] wrapping the failure, with the handle dropped
+      def repaint_last
+        report = Report.frame(@last.map { |colour| flipped(colour) })
+        with_retries("writes") { @handle.write_feature(report) }
+      rescue Error => e
+        drop_handle
+        raise DisconnectedError, "reconnected, but repainting the last frame failed: #{e.message}"
+      end
+
+      # Takes a new handle, moving the finaliser onto it.
+      def adopt(handle)
+        @handle = handle
+        ObjectSpace.undefine_finalizer(self)
+        ObjectSpace.define_finalizer(self, self.class.releaser(handle))
+      end
+
+      # Closes the handle, ignoring any error doing so, and forgets it along
+      # with its finaliser.
+      def drop_handle
+        handle = @handle
+        @handle = nil
+        ObjectSpace.undefine_finalizer(self)
+        begin
+          handle.close
+        rescue Error
+          nil
+        end
+      end
+    end
+  end
+end