VNC Client

The vnc component connects to a VNC server and shows its screen on a display. It connects when the device starts and reconnects by itself when the server goes away.

A common use is a wall dashboard: a server runs a web browser at the size of the panel, for example with the VNC Web Browser Home Assistant add-on, and an ESPHome device with an e-paper or LCD screen shows it.

WARNING

VNC sends the picture unencrypted. Only use it on a network you trust.

# Example configuration entry
vnc:
  host: 192.168.1.20

The component draws every pixel of the display, so the display must not have its own lambda or pages. Set the server’s screen size to the size of the display after rotation. The picture is not scaled: if the server is larger, only its top-left part is shown.

Configuration Variables

host (Required, string): The IPv4 address or hostname of the VNC server.
port (Optional, int): The port of the VNC server. Defaults to 5900.
display_id (Optional, ID): The display to draw on. Only needed if there is more than one display.
reconnect_interval (Optional, Time): How long to wait before the first new connection attempt after a failure. The wait doubles with each further failure, up to 60 seconds or reconnect_interval, whichever is longer. Defaults to 5s. After a configuration problem, for example when the server is not a VNC server or asks for a password that is not set, the client waits 5 minutes instead.
update_delay (Optional, Time): How long the picture must stay unchanged before the display refreshes. This turns an animation into one refresh that shows where the animation ended. Defaults to 200ms.
max_update_delay (Optional, Time): The longest a change waits for the picture to stop changing. If the picture never stops changing, for example because of a moving background, the display refreshes about this often. Defaults to 1s. On e-paper, a few seconds often looks better.
on_connect (Optional, Automation): An automation to run when the client has connected to the server, before the first picture arrives.
on_disconnect (Optional, Automation): An automation to run when the connection is lost.
id (Optional, ID): Manually specify the ID used for code generation.

Supported Displays

The component works with displays that keep a full picture in memory and accept drawing from other components:

IT8951 E-Paper, for example the M5Paper.
E-Paper SPI.
LCD drivers such as ILI9xxx.
SDL and Snapshot on the host platform, for testing.

The mipi_spi, mipi_rgb and mipi_dsi drivers are not supported yet. The older Waveshare E-Paper driver draws every colour except pure black as ink, so use E-Paper SPI instead.

A display cannot be shared with LVGL or with a second vnc client.

How Refreshing Works

The client asks the server for changes, draws them into the display’s memory as they arrive, and refreshes the display once the picture has stopped changing for update_delay. On e-paper this keeps the number of refreshes low, which means less flashing. While an e-paper panel refreshes, the client waits before asking for the next change.

On e-paper, choose content that changes rarely. Clocks with seconds, blinking text cursors, spinners and moving backgrounds keep the panel refreshing. The Home Assistant login page has a moving background, so log in, or use a long-lived access token.

For the IT8951, the GL16 waveform flashes much less than the default GC16, while full_update_every still clears ghosting from time to time.

Server Setup

The client supports the VNC protocol versions 3.3, 3.7 and 3.8, and the Raw encoding. It works with servers that need no password.

VNC Web Browser add-on for Home Assistant (TightVNC): set the display resolution to the size of the panel, for example 540x960 for an M5Paper in portrait, and keep the colour depth at 16. The add-on disconnects other viewers when a new one connects, so the device and a desktop viewer will push each other off.
TigerVNC: Xvnc :1 -geometry 540x960 -depth 16 -SecurityTypes None.
x11vnc: run it against an X server of the right size, for example Xvfb :1 -screen 0 540x960x16, with -nopw.

Conditions

`vnc.is_connected` Condition

True while the client is connected to the server. This starts before the first picture arrives. After a disconnect, an e-paper display keeps showing the last picture.

on_...:
  if:
    condition:
      vnc.is_connected:
    then:
      - logger.log: "VNC connected"

id (Optional, ID): The vnc client to check. Only needed if there is more than one.

From a lambda, id(my_vnc).is_connected() gives the same answer:

binary_sensor:
  - platform: template
    name: VNC connected
    lambda: return id(my_vnc).is_connected();

M5Paper Example

A dashboard in portrait.

esp32:
  board: m5stack_paper
  flash_size: 16MB
  framework:
    type: esp-idf

psram:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  power_save_mode: none

network:
  enable_high_performance: true

switch:
  # Keeps the M5Paper powered when running on battery
  - platform: gpio
    id: power_hold
    pin: GPIO2
    restore_mode: ALWAYS_ON

spi:
  clk_pin: GPIO14
  mosi_pin: GPIO12
  miso_pin: GPIO13

display:
  - platform: it8951
    id: epd
    model: m5stack-m5paper
    rotation: 270
    update_mode: GL16
    sleep_when_done: false

vnc:
  id: my_vnc
  host: 192.168.1.20
  port: 5901
  max_update_delay: 5s

Troubleshooting

Only part of the screen is shown, or there is an empty border: the server’s screen size does not match the display. The log shows both sizes when the client connects.
“The server requires a password” or “No supported security type”: turn off authentication on the server.
Set the logger level to DEBUG to see a line for every change the server sends, with its size and how long it took.