SolarOS 4.6.8 manual · job

displayd

Authenticated HTTP display and remote control. It has two modes:

• With a physical target such as display0, it mirrors and controls the

active session attached to that display without allocating another display framebuffer.

• With web0, it creates an independent monochrome virtual display and a

detached display shell. Its logical dimensions match the board's main display (for example 384x288 on the Freenove PAL target). A headless board uses the historical 400x300 fallback. Apps launched from that shell stay on web0 and do not replace the foreground app on a physical display.

With no target argument, displayd mirrors display0 when it exists and otherwise creates web0. The latter makes the same command useful on headless PSRAM-equipped boards.

Usage:

job start displayd [target]
job stop displayd
job status displayd

Example:

wifi on
job start displayd
job start displayd web0

Starting the job prints a random six-digit access code. Open http://<device>/display, enter that code, and click the displayed image before typing. The browser frontend polls the native 1-bit U8g2 frame up to twenty times per second and performs pixel rotation in the browser instead of the HTTP server task. It sends bounded key input through the scheduler. Ctrl+] remains the application-exit key.

API:

GET  /api/displays
GET  /api/displays/<target>/frame.pbm
GET  /api/displays/<target>/frame.raw
POST /api/displays/<target>/input

All API requests require Authorization: Bearer <code>. The access code is never accepted in the URL. The built-in frontend itself is public so that it can prompt for the code, but keeps the supplied code only in page memory.

Notes:

• web0 is registered as source=virtual, driver=framebuffer while the job

is running. Its framebuffer and session exist independently of whether a browser is connected.

• displayd creates and owns the web0 shell session itself and prints its

session ID. Do not run session create shell web0 afterward; the target is already attached to the browser-controlled shell.

• Ctrl+] exits a foreground app on web0 and returns to its detached shell.

The physical foreground session is unaffected.

• The physical mirror reuses the active U8g2 display and does not create

another display session. The built-in display shell is registered as the session attached to display0.

• A consistent 1-bit frame snapshot and same-sized raw transmit buffer are held

in PSRAM while the job runs. For the 400x300 Waveshare display they consume 30,400 bytes in total. web0 additionally owns a board-sized U8g2 framebuffer (15,200 bytes on Waveshare, 13,824 bytes on the 384x288 PAL target). HTTP transmission never holds a display or registry lock.

• The snapshot is copied into the transmit buffer and released before network

I/O, so a slow browser cannot prevent newer display frames from being published.

• The browser uses frame.raw to avoid per-pixel PBM conversion on the ESP32.

The PBM endpoint remains available for simple external clients.

• If a browser is still reading a frame when the display presents again, that

publication is skipped rather than blocking the display.

• Input is queued by the HTTP task and dispatched only by the normal SolarOS

scheduler. Both physical and virtual targets receive it through their active target-addressed session; browser control does not depend on the device's globally foreground session.

• The server is plain HTTP. The six-digit code provides convenient access

control on a trusted Wi-Fi network but does not encrypt frames or input and is not intended for exposure to an untrusted network.

• displayd and httpd share one HTTP server and may run simultaneously.