Skip to content

Web Display

Jump to bottom
Jdaie Lin edited this page Mar 3, 2026 · 1 revision

Whisplay AI Chatbot includes an optional Web Display that simulates the physical Whisplay HAT screen, RGB LED, and button in a web browser. This is useful for:

  • Development & testing without a physical Whisplay HAT connected
  • Remote monitoring — view what's on the chatbot screen from another device on the same network
  • Headless setups — interact with the chatbot even when no physical display is available

The web display mirrors everything the physical HAT shows in real time: status text, emoji, scrolling LLM responses, generated/captured images, camera live feed, battery level, network status, and RAG/image-generation indicators. You can also press the virtual button to start/stop recording, just like the physical button.

Enable the Web Display

Add the following to your .env file:

# Enable the web-based display simulator (default: disabled)
WHISPLAY_WEB_ENABLED=true

# Port to serve the web display on (default: 17880)
# WHISPLAY_WEB_PORT=17880

# Host/IP to bind (default: 0.0.0.0 — accessible from all network interfaces)
# WHISPLAY_WEB_HOST=0.0.0.0

Restart the chatbot after updating the .env file.

Access the Web Display

Once enabled, open a browser and navigate to:

http://<device-ip>:17880

For example, if your Raspberry Pi's IP is 192.168.1.100:

http://192.168.1.100:17880

If you're accessing from the device itself:

http://localhost:17880

Features

Screen Simulation

The web display faithfully reproduces the Whisplay HAT OLED/LCD screen:

  • Status bar — shows the current state (idle, listening, thinking, speaking, etc.), battery level, network connectivity icon, RAG icon, and image-generation icon
  • Emoji — displays the current emotion/status emoji
  • Scrolling text — LLM responses scroll smoothly, synchronized with TTS playback timing
  • Image display — generated images and captured photos are displayed on the virtual screen
  • Camera live feed — when the camera is active, the web display streams the live camera feed at ~5 fps
  • Brightness simulation — screen dimming is simulated with an overlay

RGB LED

A virtual LED indicator mirrors the physical HAT's RGB LED color, showing the current state visually (e.g., green for idle, blue for listening, etc.).

Virtual Button

The PRESS button in the web UI functions identically to the physical HAT button:

  • Single click (press and release) — starts/stops voice recording
  • Double click — enters camera capture mode (if ENABLE_CAMERA=true)

The button supports both mouse and touch input, making it usable on phones and tablets.

How It Works

The web display runs a lightweight HTTP + WebSocket server alongside the main chatbot process:

  1. HTTP server (Koa) serves the static web UI and provides REST endpoints for images (/image) and camera frames (/camera)
  2. WebSocket (/ws) pushes real-time state updates to all connected browsers — no polling required
  3. Button press/release events from the browser are sent back to the chatbot via WebSocket, triggering the same logic as the physical button

Multiple browser tabs/devices can connect simultaneously. State is broadcast to all connected clients.

Using Without a Physical HAT

The web display works independently of the physical Whisplay HAT. If you are running the chatbot on a device without the HAT (e.g., a regular Raspberry Pi, a PC, or a server), you can disable the physical device and use only the web display:

# Disable the physical HAT (no Python UI process will be started)
WHISPLAY_DEVICE_ENABLED=false

# Enable the web display as the sole interface
WHISPLAY_WEB_ENABLED=true

In this mode, the chatbot is fully controlled through the web browser.

.env Reference

Variable Required Default Description
WHISPLAY_WEB_ENABLED No false Set to true to enable the web display
WHISPLAY_WEB_PORT No 17880 HTTP/WebSocket port for the web display
WHISPLAY_WEB_HOST No 0.0.0.0 Bind address. Use 0.0.0.0 for LAN access, 127.0.0.1 for local-only

Notes

  • The web display adds minimal overhead — it only serves static files and broadcasts JSON state via WebSocket.
  • If no browser is connected, the WebSocket broadcast is a no-op with no performance impact.
  • The web display can run alongside the physical HAT. Both will show the same content simultaneously.
  • Camera live feed requires ENABLE_CAMERA=true and uses the same camera daemon as the physical HAT.
  • The web UI is responsive and works on desktop, tablet, and mobile browsers.

Clone this wiki locally