Hardware Module

SquishBox Raspberry Pi hardware interface.

Provides low-level access to GPIO-backed hardware components used by SquishBox, including buttons, rotary encoders, LCD display, and outputs.

Also implements event-driven input handling and a buffered LCD rendering system with support for scrolling, blinking, and custom glyphs.

Requires:

• gpiod

class squishbox.hardware.Control

Bases: object

Base class for input controls with event binding.

Provides a simple event → callback mapping. Subclasses trigger events (e.g. “tap”, “left”) which invoke the bound functions.

release()

bind(event, func)

Bind a callback function to an event.

Parameters:

• event (hashable) – Event identifier

• func (callable) – function to invoke, or None to remove binding.

clear_binds()

Remove all event bindings.

class squishbox.hardware.Button(pin, pull_up=True)

Bases: Control

GPIO button with tap/hold detection.

Monitors a GPIO input line and emits events based on press duration.

Events:

• “down”: button pressed

• “up”: button released

• “in”/”out”: toggles on button press

• “tap”: short press

• “hold”: long press (duration >= CONFIG[“hold_time”])

UP = 0

DOWN = 1

HELD = 2

class squishbox.hardware.Encoder(pin1, pin2, pull_up=True)

Bases: Control

Quadrature rotary encoder.

Detects rotation direction using two GPIO inputs.

Events:

• “left”: counterclockwise rotation

• “right”: clockwise rotation

class squishbox.hardware.Output(pin, on=False)

Bases: object

Digital (on/off) GPIO output.

release()

on()

Set output to active (HIGH).

off()

Set output to inactive (LOW).

class squishbox.hardware.PWMOutput(pin, freq=2000, level=0)

Bases: object

Software PWM output using a background thread.

Generates a PWM signal by toggling a GPIO line at a fixed frequency. Duty cycle is controlled via the level attribute (0–100).

level

Duty cycle percentage (0-100)

Type:

float

release()

on()

Set output to maximum.

off()

Set output to minimum.

class squishbox.hardware.LCD_HD44780(regsel, enable, data)

Bases: object

HD44780-compatible character LCD driver.

Provides buffered text rendering with support for:

• Static text

• Scrolling text (for long lines)

• Timed/blinking overlays

• Custom glyphs (up to 8 hardware slots)

Rendering is layered and only updates changed characters to minimize GPIO traffic.

glyph2char = (('backslash', '\\'), ('tilde', '~'))

release()

printable()

Provide full set of printable characters supported by the LCD.

fnchars()

Provide reduced character set suitable for filenames.

clear()

Clear the display and reset all rendering layers.

Also resets scrolling state, blinking timers, and cursor position.

write(text, row, col=0, align='', timeout=0, force=True)

Write text to the LCD using layered rendering.

Behavior depends on text length and parameters:

• Long text is placed in scroll buffer

• timeout > 0 creates temporary (blinking) overlay

• Otherwise writes to static layer

Parameters:

• text (str) – String to display.

• row (int) – Target row.

• col (int) – Starting column.

• align (str) – “left”, “right”, or default (no alignment).

• timeout (float) – Duration for temporary text (seconds).

• force (bool) – Overwrite existing timed text if True.

update()

Render buffered content to the LCD.

Handles:

• Scrolling updates

• Expiring timed/blinking text

• Layer compositing

Does nothing if activity spinner is active.

property cursor_pos

Cursor position as (row, col)

property cursor_mode

Cursor display mode.

Modes:

• “hide” – no cursor

• “blink” – blinking block cursor

• “line” - underline cursor

activity(msg=None)

Shows an animation while another process runs

Runs in a with statement. Displays a spinning character in the lower right corner of the LCD to give feedback while a long-running process completes.

Parameters:

msg (str) – text to display