SDL2 Display on host platform

Usage

The sdl display platform allows you to use create an ESPHome display on a desktop system running Linux or MacOS. This is particularly useful for designing display layouts, since compiling and running a host binary is much faster than compiling for and flashing a microcontroller target system.

# Example configuration entry
esphome:
  name: sdl

host:

display:
  - platform: sdl
    show_test_card: true
    dimensions:
      width: 450
      height: 600

Configuration variables

lambda (Optional, lambda): The lambda to use for rendering the content on the display. See Display Rendering Engine for more information.
update_interval (Optional, Time): The interval to re-draw the screen. Defaults to 1s.
sdl_options (Optional, string): Build arguments if required to specify include or library paths. Should not be required if SDL2 is properly installed.
headless (Optional, boolean): Draw into memory instead of opening a window. Defaults to false. See Headless Operation. May not be used together with window_options or snapshot_key.
snapshot_key (Optional): A key that saves a snapshot when pressed, for example SDLK_F12. See the SDL binary sensor for the list of key names. Since this needs a keyboard, it may not be used with headless. Each press saves one snapshot; holding the key down does not keep saving them.
pages (Optional, list): Show pages instead of a single lambda. See Display Pages.
id (Optional, ID): Manually specify the ID used for code generation.
window_options (Optional): Options that affect how the display renders on the host system. All default to false, except position, which defaults to SDL’s undefined position
- position (Optional): Specify the position of the display window on the host system. If not specified, SDL will choose a default position. Either x and y or centered_on_display may be used, but not together.
  - x (Optional, int): X position of the display window in pixels
  - y (Optional, int): Y position of the display window in pixels
  - centered_on_display (Optional, int): For use with multiple display screens. Centers the window on the specified display number. Display numbering starts at 0. May not be used with x or y.
- borderless (Optional, boolean): Whether to draw the display window with or without borders
- always_on_top (Optional, boolean): Whether to always draw the display window above other windows or not
- fullscreen (Optional, boolean): Whether to draw the display window in fullscreen or not. This may resize the resolution of the host display to match the SDL display dimensions
- skip_taskbar (Optional, boolean): Whether to skip adding a taskbar icon for the display window or not
- resizable (Optional, boolean): Whether the display window can be manually resized

NOTE

To build with this display you must have the SDL2 package installed.

Headless Operation

With headless: true the display draws into memory and no window is opened. This lets the display run on a system with no graphical desktop, such as a continuous integration runner or a machine you are logged into over SSH. Taking a snapshot is then the only way to see what was drawn.

display:
  - platform: sdl
    id: my_display
    headless: true
    show_test_card: true
    dimensions:
      width: 320
      height: 240

Because there is no window, a headless display receives no mouse or keyboard events. The SDL touchscreen and SDL binary sensor cannot be used with it, and neither can window_options or snapshot_key.

If all you want is a picture of what a configuration draws, consider the snapshot display instead. It does the same job without SDL, so it needs no graphics library installed.

Snapshots

A snapshot writes the current contents of the display to a .bmp file, either when snapshot_key is pressed or from the snapshot.take action. It works with or without a window.

on_...:
  - snapshot.take:
      id: my_display
      filename: start_screen.bmp

Where the file goes and how it is named is described under snapshots.

MacOS SDL2 Installation

The easiest way to install SDL2 on MacOS is using homebrew :

brew install sdl2

It may also be necessary to run the command:

brew link sdl2

To ensure that the files are symlinked correctly. You can check installation with the command sdl2-config --libs --cflags.

You will need the XCode command-line tools installed to build for the host platform.

Linux SDL2 Installation

On Debian/Ubuntu derived Linux systems you can install with apt ; also check that you have the necessary build tools installed. You must be using a desktop system with a graphic display, unless you set headless.

apt install libsdl2-dev build-essential git

You can check installation with the command sdl2-config --libs --cflags.

Microsoft Windows

Although SDL2 is supported, natively running ESPHome on Windows isn’t easy. However the Windows Subsystem for Linux (WSL) can be used to install and use a Linux development environment on Windows, which will enable use of ESPHome and SDL2 as per the Linux instructions above. See https://learn.microsoft.com/en-us/windows/wsl/install for more information on WSL.

Build and run

The esphome run yourfile.yaml command will compile and automatically run the build file on the host platform.