rgpio 0.1.0 → 0.1.1

data/examples/rotary_encoder.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+
+# Count the turns of a rotary encoder with Rgpio::RotaryEncoder, and reset the
+# count with the push switch on its shaft through Rgpio::Button.
+#
+# Module: a KY-040 — CLK / DT / SW / + / GND, with 10 kΩ pull-ups on CLK and DT
+# on the board. Power it from 3.3 V, never 5 V: the pull-ups go to "+", so 5 V
+# there puts 5 V on the GPIO lines. SW has no pull-up on most boards, hence the
+# pull_up: true on the Button below.
+#
+# Wiring:
+#   CLK -- GPIO17 (pin 11)   phase A
+#   DT  -- GPIO18 (pin 12)   phase B
+#   SW  -- GPIO27 (pin 13)
+#   +   -- 3.3 V  (pin 1)
+#   GND -- GND    (pin 6)
+#
+# Run:
+#   ruby examples/rotary_encoder.rb
+#
+# A bare encoder (three pins A / C / B, as verified on a Pi 5) needs no board:
+# A to GPIO17, C (the middle pin) to GND, B to GPIO18 — the internal pull-ups
+# do the rest. Without a shaft switch, leave GPIO27 unconnected.
+#
+# Turn the knob; the count stops at ±16. Press the knob to reset it to 0. Stop
+# with Ctrl-C. If clockwise counts down, swap a: and b: (or CLK and DT).
+
+require_relative "../lib/rgpio"
+
+chip = Rgpio::Chip.new
+encoder = Rgpio::RotaryEncoder.new(a: 17, b: 18, max_steps: 16, chip: chip)
+button = Rgpio::Button.new(27, pull_up: true, chip: chip)
+
+begin
+  encoder.when_rotated_clockwise         { puts format("CW  %3d  value %+.2f", encoder.steps, encoder.value) }
+  encoder.when_rotated_counter_clockwise { puts format("CCW %3d  value %+.2f", encoder.steps, encoder.value) }
+  button.when_pressed do
+    encoder.steps = 0
+    puts "Reset"
+  end
+
+  puts "Turn the encoder on GPIO17/18. Press Ctrl-C to stop."
+  Rgpio.pause
+ensure
+  button.close
+  encoder.close
+  chip.close
+end

data/examples/ruby_stack.rb

@@ -0,0 +1,169 @@
+#!/usr/bin/env ruby
+
+# Tap the screen to drop a ruby: it falls from where you touched and piles up
+# on the ones already there. A game of nothing, on a 2.8" ILI9341 + XPT2046.
+#
+# Wiring: as in examples/touch_paint.rb.
+#
+# Run:
+#   ruby examples/ruby_stack.rb
+#   ruby examples/ruby_stack.rb <six calibration numbers>   # skip calibrating
+#
+# The screen is used in landscape, turned 90 degrees to the left (ROTATION; 90
+# turns it the other way). The calibration follows the rotation, so numbers
+# printed by examples/touch_paint.rb, which runs upright, do not carry over.
+#
+# Touching the grey "Hello, rgpio!" strip at the top clears the pile, and so
+# does a pile that reaches the strip. Ctrl-C to stop.
+#
+# The gem is drawn here from flat facets — it is not the Ruby logo artwork.
+
+require_relative "../lib/rgpio"
+require_relative "touch_calibration"
+
+$stdout.sync = true
+
+ROTATION = 270
+BAR = 24
+TITLE = "Hello, rgpio!".freeze
+GRAVITY = 900.0 # px/s²
+FRAME = 1.0 / 60
+
+# One cut gem, 32x28 at scale 1: a crown of five facets over a pavilion of
+# three, each a triangle in its own shade of red.
+module Jewel
+  TOP = [[8, 0], [16, 0], [24, 0]].freeze
+  GIRDLE = [[0, 8], [11, 8], [21, 8], [32, 8]].freeze
+  TIP = [16, 28].freeze
+  FACETS = [
+    [[TOP[0], GIRDLE[0], GIRDLE[1]], [220, 50, 60]],
+    [[TOP[0], TOP[1], GIRDLE[1]], [245, 90, 95]],
+    [[TOP[1], GIRDLE[1], GIRDLE[2]], [255, 150, 150]], # the table catches the light
+    [[TOP[1], TOP[2], GIRDLE[2]], [235, 70, 80]],
+    [[TOP[2], GIRDLE[2], GIRDLE[3]], [190, 20, 35]],
+    [[GIRDLE[0], GIRDLE[1], TIP], [170, 10, 30]],
+    [[GIRDLE[1], GIRDLE[2], TIP], [215, 30, 45]],
+    [[GIRDLE[2], GIRDLE[3], TIP], [130, 0, 20]],
+  ].freeze
+  WIDTH = 32
+  HEIGHT = 28
+
+  # @return [Array(Integer, Integer, String)] width, height and RGB565 pixels
+  #   on black, ready for ILI9341#blit
+  def self.sprite(scale)
+    w = (WIDTH * scale).round
+    h = (HEIGHT * scale).round
+    facets = FACETS.map { |points, rgb| [points.map { |x, y| [x * scale, y * scale] }, Rgpio::RGB565.from(rgb)] }
+    pixels = Array.new(w * h, 0)
+    h.times do |y|
+      w.times do |x|
+        px = x + 0.5
+        py = y + 0.5
+        hit = facets.find { |points, _| inside?(points, px, py) }
+        pixels[(y * w) + x] = hit[1] if hit
+      end
+    end
+    [w, h, pixels.pack("n*")]
+  end
+
+  def self.inside?((a, b, c), x, y)
+    d1 = cross(a, b, x, y)
+    d2 = cross(b, c, x, y)
+    d3 = cross(c, a, x, y)
+    !((d1.negative? || d2.negative? || d3.negative?) && (d1.positive? || d2.positive? || d3.positive?))
+  end
+
+  def self.cross((ax, ay), (bx, by), x, y)
+    ((bx - ax) * (y - ay)) - ((by - ay) * (x - ax))
+  end
+end
+
+# A gem on its way down. It lands on the highest thing under any of its columns.
+Falling = Struct.new(:x, :y, :speed, :sprite) do
+  def width = sprite[0]
+  def height = sprite[1]
+end
+
+def clear(lcd, floor)
+  floor.fill(lcd.height)
+  lcd.fill(:black)
+  lcd.fill_rect(0, 0, lcd.width, BAR, :gray)
+  title_width, = lcd.text_size(TITLE, scale: 2)
+  lcd.text((lcd.width - title_width) / 2, 4, TITLE, color: :red, bg: :gray, scale: 2)
+end
+
+chip = Rgpio::Chip.new
+lcd = Rgpio::ILI9341.new(dc: 24, reset: 25, backlight: 18, chip: chip)
+touch = Rgpio::XPT2046.new(irq: 17, chip: chip)
+
+begin
+  lcd.rotation = ROTATION
+  touch.calibration = TouchCalibration.load_or_run(lcd, touch)
+
+  sprites = [0.75, 1.0, 1.25, 1.5, 2.0].map { |scale| Jewel.sprite(scale) }
+  floor = Array.new(lcd.width) # the top of the pile, per column
+  clear(lcd, floor)
+  puts "2) tap to drop rubies (the strip at the top clears; Ctrl-C to stop)"
+
+  falling = []
+  was_down = false
+  dropped = 0
+  last = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  loop do
+    now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    dt = now - last
+    last = now
+
+    # A new press, not a held finger, drops one gem.
+    x, y = touch.position
+    down = !x.nil?
+    if down && !was_down
+      if y < BAR
+        falling.clear
+        clear(lcd, floor)
+      else
+        sprite = sprites.sample
+        left = (x - (sprite[0] / 2)).clamp(0, lcd.width - sprite[0])
+        top = [y - (sprite[1] / 2), BAR].max
+        falling << Falling.new(left, top.to_f, 0.0, sprite)
+        dropped += 1
+        puts "   ruby #{dropped} at #{x}, #{y}"
+      end
+    end
+    was_down = down
+
+    falling.each do |jewel|
+      old_y = jewel.y.round
+      jewel.speed += GRAVITY * dt
+      jewel.y += jewel.speed * dt
+      landing = floor[jewel.x, jewel.width].min - jewel.height
+      landed = jewel.y >= landing
+      jewel.y = landing.to_f if landed
+      new_y = jewel.y.round
+
+      # Black out only the rows the jewel has left, then draw it lower down.
+      lcd.fill_rect(jewel.x, old_y, jewel.width, new_y - old_y, :black) if new_y > old_y
+      lcd.blit(jewel.x, new_y, jewel.width, jewel.height, jewel.sprite[2])
+      next unless landed
+
+      floor.fill(new_y, jewel.x, jewel.width)
+      jewel.speed = nil
+    end
+    falling.reject! { |jewel| jewel.speed.nil? }
+
+    if floor.min < BAR + 40
+      puts "   the pile reached the top — clearing"
+      sleep 1
+      falling.clear
+      clear(lcd, floor)
+    end
+
+    sleep FRAME
+  end
+rescue Interrupt
+  nil
+ensure
+  touch.close
+  lcd.close
+  chip.close
+end

data/examples/tft.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+
+# Draw on a 2.8" ILI9341 TFT with Rgpio::ILI9341: full-screen fills (timed),
+# rectangles, text at several sizes, and the four rotations.
+#
+# Module: the common red-board 240x320 SPI TFT with an XPT2046 touch
+# controller (pins VCC GND CS RESET DC SDI SCK LED SDO T_CLK T_CS T_DIN T_DO
+# T_IRQ). This example uses the display half only; examples/touch_paint.rb
+# adds the touch panel on the same bus.
+#
+# Wiring (SPI0 must be enabled: sudo raspi-config nonint do_spi 0):
+#   VCC   -- 3.3 V  (pin 1)
+#   GND   -- GND    (pin 6)
+#   CS    -- GPIO8  (pin 24, CE0)
+#   RESET -- GPIO25 (pin 22)
+#   DC    -- GPIO24 (pin 18)
+#   SDI   -- GPIO10 (pin 19, MOSI)
+#   SCK   -- GPIO11 (pin 23, SCLK)
+#   LED   -- GPIO18 (pin 12)
+#   SDO   -- leave unconnected: nothing is read from the display, and on some
+#            boards it does not let go of MISO, which corrupts touch readings
+#
+# Run:
+#   ruby examples/tft.rb
+
+require_relative "../lib/rgpio"
+
+$stdout.sync = true
+
+puts "0) init (reset + init sequence)"
+lcd = Rgpio::ILI9341.new(dc: 24, reset: 25, backlight: 18)
+
+begin
+  puts "1) full-screen fills, each held for 2 s"
+  %i[red green blue white black].each do |color|
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    lcd.fill(color)
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+    puts format("   fill %-5s %6.1f ms", color, elapsed * 1000)
+    sleep 2
+  end
+
+  puts "2) rectangles and text, held for 3 s"
+
+  lcd.fill_rect(10, 10, 100, 50, :red)
+  lcd.fill_rect(130, 10, 100, 50, [0, 128, 255])
+  lcd.text(10, 80, "Hello", color: :white, scale: 2)
+  lcd.text(10, 110, "rgpio", color: :yellow, bg: :navy, scale: 3)
+  lcd.text(0, 150, (32..126).map(&:chr).join.scan(/.{1,40}/).join("\n"), color: :cyan)
+  sleep 3
+
+  puts "3) rotations, each held for 2 s (red square = top-left)"
+  [90, 180, 270, 0].each do |rotation|
+    puts "   rotation #{rotation}"
+    lcd.rotation = rotation
+    lcd.fill(:black)
+    lcd.fill_rect(0, 0, 40, 40, :red) # always the top-left corner
+    lcd.text(50, 10, "rotation #{rotation}", scale: 2)
+    lcd.text(50, 40, "#{lcd.width} x #{lcd.height}", color: :green, scale: 2)
+    sleep 2
+  end
+  puts "4) done; closing"
+ensure
+  lcd.close
+end

data/examples/touch_calibration.rb

@@ -0,0 +1,61 @@
+# Touch calibration shared by examples/touch_paint.rb and examples/ruby_stack.rb.
+#
+# Six numbers on the command line are used as the calibration as they are;
+# otherwise a cross is shown at each corner and the centre in turn, and the
+# fitted calibration is printed together with the command line that reuses it.
+module TouchCalibration
+  MARGIN = 20
+
+  module_function
+
+  # @return [Array<Float>] the calibration to give XPT2046#calibration=
+  def load_or_run(lcd, touch, args = ARGV)
+    unless args.empty?
+      raise ArgumentError, "a calibration is six numbers, got #{args.size}" unless args.size == 6
+
+      return args.map { Float(_1) }
+    end
+
+    puts "1) calibration: touch the centre of each cross"
+    calibration = run(lcd, touch)
+    numbers = calibration.map { |c| c.round(5) }
+    puts "calibration: #{numbers.inspect}"
+    puts "   skip this next time: ruby #{$PROGRAM_NAME} #{numbers.join(" ")}"
+    calibration
+  end
+
+  def run(lcd, touch)
+    w = lcd.width
+    h = lcd.height
+    targets = [[MARGIN, MARGIN], [w - MARGIN, MARGIN], [w - MARGIN, h - MARGIN], [MARGIN, h - MARGIN], [w / 2, h / 2]]
+    raw = targets.each_with_index.map do |(x, y), i|
+      puts "   cross #{i + 1}/#{targets.size} at #{x}, #{y}"
+      lcd.fill(:black)
+      lcd.text(30, (h / 2) + 30, "Touch the cross", scale: 2)
+      cross(lcd, x, y, :white)
+      raw_touch(touch)
+    end
+    Rgpio::XPT2046.calibration_from(targets, raw)
+  end
+
+  def cross(lcd, x, y, color)
+    lcd.fill_rect(x - 10, y, 21, 1, color)
+    lcd.fill_rect(x, y - 10, 1, 21, color)
+  end
+
+  # Wait for a press, average the raw readings while it is held, then wait for
+  # the release.
+  def raw_touch(touch)
+    sleep 0.01 until touch.touched?
+    samples = []
+    while (sample = touch.raw)[2] >= touch.threshold
+      samples << sample
+      sleep 0.01
+    end
+    sleep 0.2
+    return raw_touch(touch) if samples.empty? # a tap too brief to read
+
+    samples = samples.drop(2) if samples.size > 4 # the first readings are still landing
+    [samples.sum { |s| s[0] } / samples.size, samples.sum { |s| s[1] } / samples.size]
+  end
+end

data/examples/touch_paint.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+
+# Calibrate the XPT2046 touch panel of a 2.8" ILI9341 module, then draw with a
+# finger or stylus.
+#
+# Wiring: the display as in examples/tft.rb, plus the touch controller on the
+# same SPI bus with chip select CE1:
+#   T_CLK -- GPIO11 (pin 23, SCLK)  shared with SCK
+#   T_DIN -- GPIO10 (pin 19, MOSI)  shared with SDI
+#   T_DO  -- GPIO9  (pin 21, MISO)
+#   T_CS  -- GPIO7  (pin 26, CE1)
+#   T_IRQ -- GPIO17 (pin 11)
+#
+# Run:
+#   ruby examples/touch_paint.rb
+#   ruby examples/touch_paint.rb <six calibration numbers>   # skip calibrating
+#
+# Touch the centre of each cross as it appears. The calibration is printed so
+# it can be passed on the command line next time, or as `calibration: [...]`
+# in a script of your own. Then draw; touching the grey strip at the top clears
+# the screen. Ctrl-C to stop.
+
+require_relative "../lib/rgpio"
+require_relative "touch_calibration"
+
+$stdout.sync = true
+
+BAR = 24
+
+def clear(lcd)
+  lcd.fill(:black)
+  lcd.fill_rect(0, 0, lcd.width, BAR, :gray)
+  lcd.text(4, 4, "clear", color: :black, bg: :gray, scale: 2)
+end
+
+chip = Rgpio::Chip.new
+lcd = Rgpio::ILI9341.new(dc: 24, reset: 25, backlight: 18, chip: chip)
+touch = Rgpio::XPT2046.new(irq: 17, chip: chip)
+
+begin
+  touch.calibration = TouchCalibration.load_or_run(lcd, touch)
+  clear(lcd)
+  puts "2) draw (grey strip at the top clears; Ctrl-C to stop)"
+
+  # The callbacks run on the touch watcher thread; the loop below polls
+  # #position on the main thread. Both can draw: the display serialises them.
+  touch.when_touched  { |x, y| puts "touched at #{x}, #{y}" }
+  touch.when_released { puts "released" }
+
+  loop do
+    x, y = touch.position
+    if x.nil?
+      sleep 0.01
+    elsif y < BAR
+      clear(lcd)
+      sleep 0.3
+    else
+      lcd.fill_rect(x - 2, y - 2, 5, 5, :yellow)
+    end
+  end
+rescue Interrupt
+  nil
+ensure
+  touch.close
+  lcd.close
+  chip.close
+end

data/lib/rgpio/devices/adt7410.rb

@@ -97,7 +97,7 @@ module Rgpio
       raw = ((msb << 8) | lsb)
       raw >>= 3 if resolution == 13
       sign_bit = resolution == 13 ? 0x1000 : 0x8000
-      raw -= sign_bit * 2 if raw & sign_bit != 0
+      raw -= sign_bit * 2 if raw.anybits?(sign_bit)
       raw / counts
     end
 

data/lib/rgpio/devices/font5x7.rb

@@ -0,0 +1,209 @@
+module Rgpio
+  # The classic 5x7 column font, printable ASCII only (0x20..0x7e).
+  #
+  # Each glyph is five column bytes, left to right; bit 0 is the top row and
+  # bit 6 the bottom, bit 7 unused. A character cell is one column and one row
+  # wider than the glyph, so text set at the cell pitch has its own spacing.
+  module Font5x7
+    WIDTH = 5
+    HEIGHT = 7
+    CELL_WIDTH = WIDTH + 1
+    CELL_HEIGHT = HEIGHT + 1
+
+    FIRST = 0x20
+
+    GLYPHS = [
+      [0x00, 0x00, 0x00, 0x00, 0x00], # ' '
+      [0x00, 0x00, 0x5f, 0x00, 0x00], # !
+      [0x00, 0x07, 0x00, 0x07, 0x00], # "
+      [0x14, 0x7f, 0x14, 0x7f, 0x14], # #
+      [0x24, 0x2a, 0x7f, 0x2a, 0x12], # $
+      [0x23, 0x13, 0x08, 0x64, 0x62], # %
+      [0x36, 0x49, 0x55, 0x22, 0x50], # &
+      [0x00, 0x05, 0x03, 0x00, 0x00], # '
+      [0x00, 0x1c, 0x22, 0x41, 0x00], # (
+      [0x00, 0x41, 0x22, 0x1c, 0x00], # )
+      [0x08, 0x2a, 0x1c, 0x2a, 0x08], # *
+      [0x08, 0x08, 0x3e, 0x08, 0x08], # +
+      [0x00, 0x50, 0x30, 0x00, 0x00], # ,
+      [0x08, 0x08, 0x08, 0x08, 0x08], # -
+      [0x00, 0x60, 0x60, 0x00, 0x00], # .
+      [0x20, 0x10, 0x08, 0x04, 0x02], # /
+      [0x3e, 0x51, 0x49, 0x45, 0x3e], # 0
+      [0x00, 0x42, 0x7f, 0x40, 0x00], # 1
+      [0x42, 0x61, 0x51, 0x49, 0x46], # 2
+      [0x21, 0x41, 0x45, 0x4b, 0x31], # 3
+      [0x18, 0x14, 0x12, 0x7f, 0x10], # 4
+      [0x27, 0x45, 0x45, 0x45, 0x39], # 5
+      [0x3c, 0x4a, 0x49, 0x49, 0x30], # 6
+      [0x01, 0x71, 0x09, 0x05, 0x03], # 7
+      [0x36, 0x49, 0x49, 0x49, 0x36], # 8
+      [0x06, 0x49, 0x49, 0x29, 0x1e], # 9
+      [0x00, 0x36, 0x36, 0x00, 0x00], # :
+      [0x00, 0x56, 0x36, 0x00, 0x00], # ;
+      [0x08, 0x14, 0x22, 0x41, 0x00], # <
+      [0x14, 0x14, 0x14, 0x14, 0x14], # =
+      [0x00, 0x41, 0x22, 0x14, 0x08], # >
+      [0x02, 0x01, 0x51, 0x09, 0x06], # ?
+      [0x32, 0x49, 0x79, 0x41, 0x3e], # @
+      [0x7e, 0x11, 0x11, 0x11, 0x7e], # A
+      [0x7f, 0x49, 0x49, 0x49, 0x36], # B
+      [0x3e, 0x41, 0x41, 0x41, 0x22], # C
+      [0x7f, 0x41, 0x41, 0x22, 0x1c], # D
+      [0x7f, 0x49, 0x49, 0x49, 0x41], # E
+      [0x7f, 0x09, 0x09, 0x09, 0x01], # F
+      [0x3e, 0x41, 0x49, 0x49, 0x7a], # G
+      [0x7f, 0x08, 0x08, 0x08, 0x7f], # H
+      [0x00, 0x41, 0x7f, 0x41, 0x00], # I
+      [0x20, 0x40, 0x41, 0x3f, 0x01], # J
+      [0x7f, 0x08, 0x14, 0x22, 0x41], # K
+      [0x7f, 0x40, 0x40, 0x40, 0x40], # L
+      [0x7f, 0x02, 0x0c, 0x02, 0x7f], # M
+      [0x7f, 0x04, 0x08, 0x10, 0x7f], # N
+      [0x3e, 0x41, 0x41, 0x41, 0x3e], # O
+      [0x7f, 0x09, 0x09, 0x09, 0x06], # P
+      [0x3e, 0x41, 0x51, 0x21, 0x5e], # Q
+      [0x7f, 0x09, 0x19, 0x29, 0x46], # R
+      [0x46, 0x49, 0x49, 0x49, 0x31], # S
+      [0x01, 0x01, 0x7f, 0x01, 0x01], # T
+      [0x3f, 0x40, 0x40, 0x40, 0x3f], # U
+      [0x1f, 0x20, 0x40, 0x20, 0x1f], # V
+      [0x3f, 0x40, 0x38, 0x40, 0x3f], # W
+      [0x63, 0x14, 0x08, 0x14, 0x63], # X
+      [0x07, 0x08, 0x70, 0x08, 0x07], # Y
+      [0x61, 0x51, 0x49, 0x45, 0x43], # Z
+      [0x00, 0x7f, 0x41, 0x41, 0x00], # [
+      [0x02, 0x04, 0x08, 0x10, 0x20], # \
+      [0x00, 0x41, 0x41, 0x7f, 0x00], # ]
+      [0x04, 0x02, 0x01, 0x02, 0x04], # ^
+      [0x40, 0x40, 0x40, 0x40, 0x40], # _
+      [0x00, 0x01, 0x02, 0x04, 0x00], # `
+      [0x20, 0x54, 0x54, 0x54, 0x78], # a
+      [0x7f, 0x48, 0x44, 0x44, 0x38], # b
+      [0x38, 0x44, 0x44, 0x44, 0x20], # c
+      [0x38, 0x44, 0x44, 0x48, 0x7f], # d
+      [0x38, 0x54, 0x54, 0x54, 0x18], # e
+      [0x08, 0x7e, 0x09, 0x01, 0x02], # f
+      [0x0c, 0x52, 0x52, 0x52, 0x3e], # g
+      [0x7f, 0x08, 0x04, 0x04, 0x78], # h
+      [0x00, 0x44, 0x7d, 0x40, 0x00], # i
+      [0x20, 0x40, 0x44, 0x3d, 0x00], # j
+      [0x7f, 0x10, 0x28, 0x44, 0x00], # k
+      [0x00, 0x41, 0x7f, 0x40, 0x00], # l
+      [0x7c, 0x04, 0x18, 0x04, 0x78], # m
+      [0x7c, 0x08, 0x04, 0x04, 0x78], # n
+      [0x38, 0x44, 0x44, 0x44, 0x38], # o
+      [0x7c, 0x14, 0x14, 0x14, 0x08], # p
+      [0x08, 0x14, 0x14, 0x18, 0x7c], # q
+      [0x7c, 0x08, 0x04, 0x04, 0x08], # r
+      [0x48, 0x54, 0x54, 0x54, 0x20], # s
+      [0x04, 0x3f, 0x44, 0x40, 0x20], # t
+      [0x3c, 0x40, 0x40, 0x20, 0x7c], # u
+      [0x1c, 0x20, 0x40, 0x20, 0x1c], # v
+      [0x3c, 0x40, 0x30, 0x40, 0x3c], # w
+      [0x44, 0x28, 0x10, 0x28, 0x44], # x
+      [0x0c, 0x50, 0x50, 0x50, 0x3c], # y
+      [0x44, 0x64, 0x54, 0x4c, 0x44], # z
+      [0x00, 0x08, 0x36, 0x41, 0x00], # {
+      [0x00, 0x00, 0x7f, 0x00, 0x00], # |
+      [0x00, 0x41, 0x36, 0x08, 0x00], # }
+      [0x02, 0x01, 0x02, 0x04, 0x02], # ~
+    ].map(&:freeze).freeze
+
+    # Shown for anything outside printable ASCII: a hollow box.
+    MISSING = [0x7f, 0x41, 0x41, 0x41, 0x7f].freeze
+
+    # @return [Array<Integer>] the five column bytes for +char+
+    def self.glyph(char)
+      code = char.ord
+      return MISSING unless code.between?(FIRST, FIRST + GLYPHS.size - 1)
+
+      GLYPHS[code - FIRST]
+    end
+
+    # @return [Boolean] whether the pixel at column +x+, row +y+ of +char+ is set
+    def self.set?(char, x, y)
+      return false if x >= WIDTH || y >= HEIGHT
+
+      glyph(char)[x][y] == 1
+    end
+
+    # Text in this font for any display with #fill_rect and #blit (and a
+    # private #synchronize that holds its drawing lock).
+    module Drawing
+      # Draw text in the built-in 5x7 font (printable ASCII; anything else shows
+      # as a box). "\n" starts a new line. With bg: nil only the strokes are drawn,
+      # leaving what was underneath; with a background colour each character
+      # cell is painted in full, which overwrites old text cleanly and is faster.
+      # @return [Array(Integer, Integer)] width and height of what was drawn
+      def text(x, y, str, color: :white, bg: nil, scale: 1)
+        unless scale.is_a?(Integer) && scale.positive?
+          raise ArgumentError,
+                "scale must be a positive Integer, got #{scale.inspect}"
+        end
+
+        fg = RGB565.from(color)
+        bg &&= RGB565.from(bg)
+        lines = str.to_s.split("\n", -1)
+        synchronize do
+          lines.each_with_index do |line, i|
+            line_y = y + (i * Font5x7::CELL_HEIGHT * scale)
+            bg ? text_line_opaque(x, line_y, line, [fg, bg], scale) : text_line_transparent(x, line_y, line, fg, scale)
+          end
+        end
+        text_size(str, scale: scale)
+      end
+
+      # @return [Array(Integer, Integer)] width and height #text would draw
+      def text_size(str, scale: 1)
+        lines = str.to_s.split("\n", -1)
+        [lines.map(&:length).max.to_i * Font5x7::CELL_WIDTH * scale, lines.size * Font5x7::CELL_HEIGHT * scale]
+      end
+
+      private
+
+      # One line in full: render every cell to a buffer, then send it at once.
+      def text_line_opaque(x, y, line, colors, scale)
+        return if line.empty?
+
+        fg, bg = colors
+        on = [fg].pack("n") * scale
+        off = [bg].pack("n") * scale
+        rows = Array.new(Font5x7::CELL_HEIGHT) do |row|
+          line.each_char.map do |char|
+            Array.new(Font5x7::CELL_WIDTH) { |col| Font5x7.set?(char, col, row) ? on : off }.join
+          end.join * scale
+        end
+        w = line.length * Font5x7::CELL_WIDTH * scale
+        blit(x, y, w, Font5x7::CELL_HEIGHT * scale, rows.join)
+      end
+
+      # Strokes only: one rectangle per horizontal run of set pixels.
+      def text_line_transparent(x, y, line, fg, scale)
+        line.each_char.with_index do |char, i|
+          cell_x = x + (i * Font5x7::CELL_WIDTH * scale)
+          Font5x7::HEIGHT.times do |row|
+            runs(char, row).each do |start, length|
+              fill_rect(cell_x + (start * scale), y + (row * scale), length * scale, scale, fg)
+            end
+          end
+        end
+      end
+
+      # @return [Array<Array(Integer, Integer)>] [start column, length] of each run
+      def runs(char, row)
+        result = []
+        Font5x7::WIDTH.times do |col|
+          next unless Font5x7.set?(char, col, row)
+
+          if result.last && result.last.sum == col
+            result.last[1] += 1
+          else
+            result << [col, 1]
+          end
+        end
+        result
+      end
+    end
+  end
+end