display

OLED status dashboard and live camera preview.

omgrab.display.screen_manager

Screen manager for rendering device status and notifications to the OLED.

This module owns the ScreenWriter and a background thread that periodically queries DeviceStatusManager to render a status dashboard. It also accepts pushed notifications from other components for time-critical messages.

When camera preview is active, the manager takes ownership of the capture device's preview context (via contextlib.ExitStack) and renders live dithered camera frames at the maximum rate the I2C bus allows.

Notification(message, duration_s=3.0, priority=0, warning=False, created_at=time.monotonic()) dataclass

A transient notification to display on screen.

Attributes:

Name	Type	Description
message	str	Text to display. For warnings, use a newline to separate into two lines.
duration_s	float	How long to show the notification.
priority	int	Higher values are shown first.
warning	bool	If True, render with a triangle alert symbol.
created_at	float	Monotonic timestamp when the notification was created.

ScreenManager(writer=None, refresh_interval_s=_DEFAULT_REFRESH_INTERVAL_S, screen_timeout_s=_DEFAULT_SCREEN_TIMEOUT_S)

Manages the OLED display with periodic status updates and push notifications.

The manager runs a background thread that: 1. Checks for pending notifications (highest priority first). 2. If no notification is active, renders the current device status. 3. Pushes the rendered image to the ScreenWriter.

Other components can call show_notification() from any thread to display a transient message immediately.

Initialize the screen manager.

Parameters:

Name	Type	Description	Default
writer	Optional[ScreenWriter]	ScreenWriter instance. If None, a default one is created.	None
refresh_interval_s	float	How often to refresh the display (seconds).	_DEFAULT_REFRESH_INTERVAL_S
screen_timeout_s	float	Seconds of inactivity before blanking the screen.	_DEFAULT_SCREEN_TIMEOUT_S

display_available property

Whether the OLED display hardware is currently available.

set_preview_source(capture_device, preview_camera)

Set the capture device and preview camera for camera preview mode.

Parameters:

Name	Type	Description	Default
capture_device	CaptureDevice	The capture device that provides the preview context manager.	required
preview_camera	Camera	The camera to read preview frames from.	required

set_device_status_manager(device_status_manager)

Set the device status manager reference.

Parameters:

Name	Type	Description	Default
device_status_manager	DeviceStatusManager	The DeviceStatusManager to query for status.	required

start()

Start the background display refresh thread.

shutdown()

Stop the background thread and clean up the display.

start_preview()

Start live camera preview on the display.

Enters the capture device's preview context (starting the lightweight RGB-only pipeline) and switches the render loop to display dithered camera frames at the maximum rate the I2C bus allows.

Raises:

Type	Description
RuntimeError	If the preview source has not been set, the device cannot start preview, or the display is unavailable.

stop_preview()

Stop live camera preview and return to normal status display.

wake()

Reset the screen timeout and wake the display immediately.

Call from any thread (e.g. on button press) to turn the screen back on if it has timed out.

show_notification(message, duration_s=3.0, priority=0, warning=False)

Push a transient notification to the display.

Can be called from any thread. The notification will be shown immediately (waking the display thread) and auto-dismissed after duration_s seconds.

Parameters:

Name	Type	Description	Default
message	str	Text to display. For warnings, use a newline to separate into two lines.	required
duration_s	float	How long to show the notification (seconds).	3.0
priority	int	Higher values are shown first when multiple are queued.	0
warning	bool	If True, render with a triangle alert symbol.	False

omgrab.display.screen_writer

Low-level OLED screen writer for SSD1306 displays over I2C.

This module provides a hardware abstraction for writing PIL images to an SSD1306 OLED display. It handles initialization, reconnection on failure, and graceful degradation when the hardware is absent.

Modeled after the battery_monitor module's retry/reconnect pattern.

ScreenWriter(i2c_bus=1, i2c_address=60, width=128, height=64)

Hardware abstraction for SSD1306 OLED display over I2C.

Handles initialization, display writes, and automatic reconnection. This class is not thread-safe on its own; callers should ensure that display() and clear() are called from a single thread.

Initialize the screen writer.

Parameters:

Name	Type	Description	Default
i2c_bus	int	I2C bus number (default: 1).	1
i2c_address	int	I2C address of the SSD1306 (default: 0x3C).	60
width	int	Display width in pixels (default: 128).	128
height	int	Display height in pixels (default: 64).	64

available property

True if the screen hardware is available.

width property

Display width in pixels.

height property

Display height in pixels.

display(image)

Write an image to the OLED display.

The image should be mode '1' (1-bit) with dimensions matching the display (default 128x64). If the hardware is unavailable, this method attempts periodic reconnection.

Parameters:

Name	Type	Description	Default
image	Image	PIL Image to display.	required

clear()

Clear the display (set all pixels to black).

Safe to call even if the hardware is unavailable.

cleanup()

Clean up hardware resources.

Should be called during shutdown.