Pisugar Whisplay Whisplay

Creating a Whisplay App

Architecture Overview

Whisplay daemon manages app lifecycle on a 240×280 RGB565 LCD with a single button and an RGB LED. Apps communicate with the daemon over a Unix domain socket at /tmp/whisplay-daemon.sock using newline-delimited JSON.

The runtime SDK (runtime/whisplay_client.py) provides WhisplayDaemonProxy which handles socket communication, framebuffer rendering, and event subscription automatically.

Quick Start

1. Create the app script

import os
import sys
import time
import threading

# Add runtime to path
current_dir = os.path.dirname(os.path.abspath(__file__))
runtime_dir = os.path.abspath(os.path.join(current_dir, "..", "runtime"))
if runtime_dir not in sys.path:
    sys.path.append(runtime_dir)

from whisplay_client import create_whisplay_hardware

SCREEN_WIDTH = 240
SCREEN_HEIGHT = 280


class MyApp:
    def __init__(self):
        self.board = create_whisplay_hardware(
            app_id="my-app-id",
            display_name="My App",
            icon="M",
            exit_gesture="quad_click",
            priority=10,
            use_daemon_default_log=True,
        )
        self.running = True
        self.board.on_button_press(self._on_press)
        self.board.on_button_release(self._on_release)
        if hasattr(self.board, "on_exit_request"):
            self.board.on_exit_request(self._on_exit)
        if hasattr(self.board, "on_focus_revoked"):
            self.board.on_focus_revoked(self._on_revoked)

    def _on_press(self):
        pass

    def _on_release(self):
        pass

    def _on_exit(self):
        self.running = False

    def _on_revoked(self, _payload=None):
        self.running = False

    def run(self):
        try:
            while self.running:
                self._render()
                time.sleep(1.0 / 20)
        finally:
            self.board.cleanup()

    def _render(self):
        # Write RGB565 pixels to framebuffer
        self.board.fill_screen(0x0000)  # black


if __name__ == "__main__":
    MyApp().run()

2. Create the app config JSON

Place in ~/.whisplay-daemon/app/<app-id>.json:

{
  "app_id": "my-app-id",
  "display_name": "My App",
  "icon": "M",
  "launch_command": "python3 /path/to/my_app.py",
  "cwd": "/path/to/app/dir",
  "env": {
    "WHISPLAY_APP_ID": "my-app-id"
  },
  "exit_gesture": "quad_click",
  "priority": 10,
  "use_daemon_default_log": true,
  "persist": true
}

Or use persist=True in create_whisplay_hardware() to auto-register on first launch.

App Config Fields

create_whisplay_hardware() API

Returns a WhisplayDaemonProxy if daemon is running, otherwise falls back to direct WhisplayBoard hardware access.

board = create_whisplay_hardware(
    app_id="my-app",
    display_name="My App",
    icon="M",
    launch_command="python3 my_app.py",  # optional, for re-launch
    launch_cwd="/path/to/dir",           # optional
    persist=True,
    exit_gesture="quad_click",
    priority=10,
    use_daemon_default_log=True,
)

WhisplayDaemonProxy Methods

Screen & Pixel Format

• Resolution: 240×280
• Format: RGB565 big-endian (2 bytes per pixel)
• Framebuffer size: 240 × 280 × 2 = 134,400 bytes
• Stride: 480 bytes per row

RGB565 conversion:

def to_rgb565(r, g, b):
    return ((r & 0xF8) << 8) | ((g & 0xFC) << 3) | (b >> 3)

For PIL Image rendering:

from PIL import Image, ImageDraw
from daemon_shared import image_to_rgb565_bytes

img = Image.new("RGB", (240, 280), (0, 0, 0))
draw = ImageDraw.Draw(img)
draw.text((10, 10), "Hello", fill=(255, 255, 255))
frame = image_to_rgb565_bytes(img)
board.draw_image(0, 0, 240, 280, frame)

Daemon IPC Protocol

All communication is newline-delimited JSON over Unix socket /tmp/whisplay-daemon.sock.

Request format

{"version": 1, "cmd": "<command>", "payload": {}}

Key commands

Event stream

After events.subscribe, daemon pushes events as JSON lines:

App Lifecycle

1. Daemon starts → loads JSON configs from ~/.whisplay-daemon/app/
2. User selects app on desktop (button cycle + long press, or keyboard)
3. Daemon runs launch_command as subprocess
4. App calls app.focus.acquire → gets session_token
5. App calls framebuffer.acquire → gets shared memory file path
6. App writes RGB565 frames to shared memory; daemon renders at 20 FPS
7. Exit gesture triggers app_exit_requested event
8. App calls app.focus.release or exits → desktop resumes

Best Practices

• Always register on_exit_request and on_focus_revoked callbacks
• Call board.cleanup() in a finally block
• Use use_daemon_default_log=True for easier debugging
• Keep render loop at ≤20 FPS to match daemon refresh rate
• Use PIL for complex graphics, convert to RGB565 before writing
• Set priority to control desktop ordering (higher = appears first)
• Use env.WHISPLAY_APP_ID so the app can read its own ID from environment

Source: PiSugar/Whisplay — distributed by TomeVault.