SquishBox Module

class squishbox.squishbox.SquishBox[source]

Bases: object

Interface to SquishBox hardware and UI.

Provides access to the LCD, controls (buttons/encoders), outputs, and a set of menu-driven interaction helpers. All hardware is initialized on first instantiation using values from CONFIG.

close()[source]

Cleanly free the GPIO hardware used by the SquishBox

menu_choose(opts, row=1, align='right', i=0, wrap=True, timeout=3.0, on_change=None, passthrough=None)[source]

Display a scrolling selection menu on the LCD.

The user navigates options via bound input actions (“inc”, “dec”, “select”, “back”). The provided callback is invoked whenever the selection index changes.

Parameters:

  • opts (list) – Sequence of selectable items (displayed via str()).

  • row (int) – LCD row to render the menu.

  • align (str) – “left” or “right” text alignment.

  • i (int) – Initial index.

  • wrap (bool) – If True, selection wraps around at ends.

  • timeout (float) – Seconds to wait for input (0 = wait indefinitely).

  • on_change (callable) – Callback invoked as on_change(index) on selection change.

  • passthrough (tuple) – actions/types to return immediately

Returns:

(index, item) on selection (index, None) if canceled (“back”) (-1, None) if timed out (-1, other) if an allowed action/type is passed

menu_confirm(text='', row=1, timeout=3.0)[source]

Display a yes/no confirmation prompt.

The user toggles between confirm (check) and cancel (cross) using “inc”/”dec”, and confirms with “select”.

Parameters:

  • text (str) – Prompt text.

  • row (int) – LCD row to render the prompt.

  • timeout (float) – Seconds to wait (0 = wait indefinitely).

Returns:

True if confirmed False if explicitly rejected None if canceled (“back”) or timed out

menu_entertext(text='', row=1, i=-1, timeout=0, charset='')[source]

Interactive text entry using buttons/encoder or keyboard input.

Supports two cursor modes:

  • “blink”: move cursor position

  • “line”: modify character at cursor

Input sources:

  • Encoder/buttons (“inc”, “dec”, “select”, “back”)

  • Key events via keys_dispatch()

Parameters:

  • text (str) – Initial text buffer.

  • row (int) – LCD row to render input.

  • i (int) – Initial cursor index (negative values index from end).

  • timeout (float) – Seconds to wait for input (0 = wait indefinitely).

  • charset (str) – Allowed characters; defaults to LCD printable set.

Returns:

Final edited string on completion.

menu_choosefile(topdir, start=None, ext=None, row=0, timeout=0)[source]

Browse directories and select a file.

Displays a simple two-line file browser. Directories are shown with a trailing ‘/’, and navigation includes a parent (“../”) entry where applicable.

Parameters:

  • topdir (Path) – Root directory (user cannot navigate above this).

  • start (Path) – Optional starting file or directory (relative to topdir).

  • ext (list) – List of allowed file extensions (None = show all).

  • row (int) – Starting LCD row (uses two rows).

  • timeout (float) – Seconds to wait (0 = wait indefinitely).

Returns:

selected file, or last directory if canceled

Return type:

Path

menu_lcdsettings(row=0, timeout=3.0)[source]

Adjust LCD contrast and backlight using slider UI.

Presents two sequential sliders. Changes are applied live and written back to the config file on exit.

Parameters:

  • row (int) – Starting LCD row (uses two rows).

  • timeout (float) – Seconds to wait (0 = wait indefinitely).

menu_midisettings(row=0, timeout=0)[source]

Manage MIDI input/output connections.

Lists available MIDI ports and allows toggling connections. Active connections are persisted to the config file and restored automatically on startup.

Parameters:

  • row (int) – Starting LCD row (uses two rows).

  • timeout (float) – Seconds to wait (0 = wait indefinitely).

property wifienabled

Get/set WiFi radio state

menu_wifisettings(row=0, timeout=0)[source]

Manage WiFi connectivity using nmcli.

Features:

  • Enable/disable WiFi radio

  • Scan for networks

  • Connect/disconnect from access points

  • Prompt for passwords when required

Displays connection status and IP address when available.

Parameters:

  • row (int) – Starting LCD row (uses two rows).

  • timeout (float) – Seconds to wait (0 = wait indefinitely).

menu_exit(row=0, timeout=3.0)[source]

System exit menu.

Allows the user to:

  • Shutdown the system

  • Reboot

  • Exit to shell

Parameters:

  • row (int) – Starting LCD row (uses two rows).

  • timeout (float) – Seconds to wait (0 = wait indefinitely).

Returns:

“shell” if shell option is selected None otherwise (system may exit before returning)

menu_systemsettings(row=0, timeout=3.0)[source]

Top-level system settings menu.

Provides access to LCD, MIDI, WiFi, and exit options.

Parameters:

  • row (int) – Starting LCD row (uses two rows).

  • timeout (float) – Seconds to wait (0 = wait indefinitely).

Returns:

“shell” if user selects exit-to-shell, otherwise None

Return type:

str | None

display_error(err, msg='', row=0)[source]

Display an exception on the LCD and print traceback.

Formats the exception into a single-line message for the LCD, with file/line context shown on the second row. Full traceback is printed to stdout for debugging.

KeyboardInterrupt exits immediately.

Parameters:

  • err (Exception) – Exception instance

  • msg (str) – Optional prefix message

  • row (int) – Starting LCD row (uses two rows)

add_action(name)[source]

Queue an input action.

Actions are typically generated by hardware event bindings.

clear_actions()[source]

Remove all pending input actions.

get_action(idle=0.01, timeout=0)[source]

Wait for and return the next input action.

Continuously updates the LCD while polling for actions.

Parameters:

  • idle (float) – Delay in seconds between polling iterations.

  • timeout (float) – Seconds to wait (0 = wait indefinitely).

Returns:

Next action from the queue, None if timed out

Return type:

object

static shell_cmd(cmd, **kwargs)[source]

Run a shell command and return its stdout.

Wrapper around subprocess.run with sensible defaults:

  • check=True (raises on failure)

  • captures stdout

  • ASCII decoding

  • strips trailing newline

Parameters:

  • cmd (str | list) – Command string (or list if shell=False)

  • **kwargs (dict) – Passed through to subprocess.run

Returns:

Command stdout as a stripped string

Return type:

str

Raises:

subprocess.CalledProcessError on failure (unless overridden) –