Remote WebView Client

Demo video

This is a client that connects to Remote WebView Server — a headless browser that renders target web pages (e.g., Home Assistant dashboards) and streams them as image tiles over WebSocket to lightweight clients (ESP32 displays).

ESPHome component

The latest version of the client is implemented as an ESPHome external component, which greatly simplifies installation and configuration for end users. It leverages the display and touchscreen components to render images and handle touch input.

Configuration example (Guition-ESP32-S3-4848S040)

esphome:
name: esp32-4848s040-t1friendly_name: ESP32-4848S040-T1platformio_options:
board_build.flash_mode: dioesp32:
board: esp32-s3-devkitc-1variant: esp32s3flash_size: 16MBframework:
type: esp-idfsdkconfig_options:
COMPILER_OPTIMIZATION_SIZE: yCONFIG_ESP32S3_DEFAULT_CPU_FREQ_240: "y"CONFIG_ESP32S3_DATA_CACHE_64KB: "y"CONFIG_ESP32S3_DATA_CACHE_LINE_64B: "y"CONFIG_SPIRAM_FETCH_INSTRUCTIONS: yCONFIG_SPIRAM_RODATA: ycomponents:
- name: "espressif/esp_websocket_client"ref: 1.5.0
- name: "espressif/esp-dsp"ref: 1.7.0
- name: "bitbank2/jpegdec"source: https://github.com/strange-v/jpegdec-esphomepsram:
mode: octalspeed: 80MHzexternal_components:
- source: github://Sw1zero/RemoteWebViewClient@mainrefresh: 0scomponents: [ remote_webview ]logger:
hardware_uart: UART0api:
encryption:
key: "XXXXXXXXX"ota:
- platform: esphomepassword: "XXXXXXXXX"wifi:
ssid: !secret wifi_ssidpassword: !secret wifi_passwordcaptive_portal:
spi:
clk_pin: GPIO48mosi_pin: GPIO47i2c:
- id: bus_asda: GPIO19scl: GPIO45display:
- platform: st7701sshow_test_card: Falseupdate_interval: neverauto_clear_enabled: Falsespi_mode: MODE3data_rate: 2MHzcolor_order: RGBinvert_colors: Falsedimensions:
width: 480height: 480cs_pin: 39de_pin: 18hsync_pin: 16vsync_pin: 17pclk_pin: 21pclk_frequency: 12MHzpclk_inverted: Falsehsync_pulse_width: 8hsync_front_porch: 10hsync_back_porch: 20vsync_pulse_width: 8vsync_front_porch: 10vsync_back_porch: 10init_sequence:
- 1
- [0xFF, 0x77, 0x01, 0x00, 0x00, 0x10]
- [0xCD, 0x00]data_pins:
red:
- GPIO11
- GPIO12
- GPIO13
- GPIO14
- GPIO0green:
- GPIO8
- GPIO20
- GPIO3
- GPIO46
- GPIO9
- GPIO10blue:
- GPIO4
- GPIO5
- GPIO6
- GPIO7
- GPIO15touchscreen:
platform: gt911transform:
mirror_x: falsemirror_y: falsei2c_id: bus_aoutput:
- platform: ledcpin: GPIO38id: backlight_pwmlight:
- platform: monochromaticoutput: backlight_pwmname: "Display Backlight"id: back_lightrestore_mode: ALWAYS_ONremote_webview:
id: rwvserver: 172.16.0.252:8081url: http://172.16.0.252:8123/dashboard-mobile/0 # set url: "self-test" to initiate the self-testfull_frame_tile_count: 1max_bytes_per_msg: 61440jpeg_quality: 85backlight_id: back_lightdimming_steps:
- timeout: 5minbrightness: 50%
- timeout: 15minbrightness: 10%
- timeout: 30minbrightness: 0%text:
- platform: templateid: rwv_urlname: "URL"optimistic: truerestore_value: falsemode: TEXTmin_length: 1set_action:
- lambda: |- if (!id(rwv).open_url(std::string(x.c_str()))) { id(rwv).set_url(std::string(x.c_str())); ESP_LOGI("remote_webview", "URL queued (not connected): %s", x.c_str()); }

Supported Parameters

YAML key	Type	Required	Example	Description
display_id	id	❌	panel	Display to draw on. Optional, if only one display is defined in the YAML.
touchscreen_id	id	❌	touch	Touch input source. Optional, if only one touchscreen is defined in the YAML.
server	string	✅	172.16.0.252:8081	WebSocket server address. Must be hostname_or_IP:port.
url	string	✅	http://…/dashboard	Page to open on connect.
device_id	string	❌	"my-device" or auto (esp32-<mac>)	Identifier used by the server. If not set, the component derives esp32-<mac> from the chip MAC and still sends it.
tile_size	int	❌	32	Tile edge size in pixels. Helps the server choose tile packing; it’s best to keep it a multiple of 16.
full_frame_tile_count	int	❌	4	Number of tiles the server should use for full-frame updates.
full_frame_area_threshold	float	❌	0.50	Area delta (fraction of screen) above which the server should send a full frame.
full_frame_every	int	❌	50	Force a full-frame update every N frames (0 disables).
every_nth_frame	int	❌	1	Frame-rate divider. Server should send only every Nth frame.
min_frame_interval	int (ms)	❌	80	Minimum time between frames on the wire, in milliseconds.
jpeg_quality	int	❌	85	JPEG quality hint for the server’s encoder.
max_bytes_per_msg	int (B)	❌	14336 or 61440	Upper bound for a single WS binary message.
big_endian	bool	❌	true or false	Use big-endian RGB565 pixel order for JPEG output (set false for little-endian panels). Default is true.
rotation	int	❌	0, 90, 180, 270	Enables software rotation for both the display and touchscreen.
backlight_id	id	❌	back_light	ID of the light component controlling the display backlight.
dimming_steps	list	❌	see example below	List of dimming steps based on inactivity. Each step defines timeout and a brightness percentage.

Recommendations

• full_frame_tile_count set to 1 is the most efficient way to do a full-screen update; use it if your network/device memory allows it.
• every_nth_frame must be 1 if you don’t want to miss changes (though increasing it may reduce server load). I recommend keeping it set to 1.
• min_frame_interval should be slightly larger than the render time reported by the self-test (set self-test as a url parameter in the YAML).
• max_bytes_per_msg should be larger than your maximum tile size (full-frame or partial).
• jpeg_quality — lower values encode faster and reduce bandwidth (but increase artifacts). Start at 85, drop toward 70–75 if you need speed.
• big_endian — defaults to true. If colors look wrong (swapped/tinted), set big_endian: false for panels that require little-endian RGB565.
• Red tile / red screen — this indicates a tile payload exceeded max_bytes_per_msg. Increase max_bytes_per_msg or reduce tile size/JPEG quality so each tile fits.

No on-screen keyboard

There’s no on-screen keyboard; you’ll need to use Chrome DevTools for any required input.