Please note: work in progress!
Hey everyone,
I recently set up the development environment that allows me to try out esphome display layouts without having to flash code onto an actual physical device. This makes it faster to try things out, and you don’t even need to have the device around yet for which you want to design something.
Please note: this post is mostly written as a draft for a potential extension for SDL2 Display on host platform — ESPHome, and highly based on my own single experience, so any feedback that makes this more correct and easier to follow: bring it on, highly appreciated 
Who is this suitable for: anyone who wants to code esphome display stuff without having to use an actual device, who works with a Windows10 laptop/pc, and who is comfortable with doing commandline stuff.
Who is this not suitable for: Mac/Linux users (from what I understood the stuff in SDL2 Display on host platform — ESPHome already got you covered), people who depend on the esphome environment within HA for development
What you will have once setting everything up: you’ll be able to write, compile and “flash” code on your Windows system and have it running as a virtual esphome device, including the connection to your live HA instance (as long as your laptop runs in the same network).
A lot of the basic steps were originally lined out in Discord, so thanks to the people involved for laying the groundwork
Steps needed:
-
Download and install Visual Studio Code: Download Visual Studio Code - Mac, Linux, Windows
-
If not automatically available: find and install the WSL extension in VS code
-
Install the Windows Subsystem for Linux (WSL): open the Windows command line as an administrator (via right-click on the command line icon) and run
wsl --install
(details via Install WSL | Microsoft Learn if needed)
- Install SDL2 within the linux environment: run
sudo apt install libsdl2-dev libsodium-dev build-essential git
and wait until everything is done.
- Update python if needed, install the venv module for virtual environments, and create a virtual environment.
sudo apt-get update
sudo apt-get install libpython3-dev
sudo apt-get install python3-venv
python3 -m venv chooseanamehere
(“chooseanamehere” is a placeholder for whatever name you want to give your virtual environment and its folder, replace it with what you like, e.g. “virtualesphome”. Going on from here, everywhere you read “chooseanamehere” in this document replace it with whatever you picked in the end)
- Start the virtual environment you just created
source chooseanamehere/bin/activate
The terminal commandline should now have the name of the virtual environment in brackets at the front.
- Navigate into the folder of your virtual environment and Install esphome
cd chooseanamehere
pip3 install wheel
pip3 install esphome
(Details via Installing ESPHome Manually — ESPHome)
- Open your venv folder for the first time in Visual Studio Code by running
code .
inside the WSL command line, this will complete the initial connection between WSL and Visual Studio Code (see Developing in the Windows Subsystem for Linux with Visual Studio Code for details)
- Create a minimal yaml file inside the virtual environment folder and try out your first compilation/run via “esphome compile example.yaml” or “esphome run example.yaml” in the Visual Studio Code WSL terminal.
Minimal example yaml:
esphome:
name: sdl
host:
display:
- platform: sdl
#show_test_card: true
dimensions:
width: 480
height: 320
auto_clear_enabled: false
touchscreen:
platform: sdl
lvgl:
#log_level: INFO
color_depth: 16
bg_color: 0x000000
pages:
- id: main_page
widgets:
- label:
text_font: montserrat_36
text: "hello world"
id: hellowordlabel
align: center
text_color: 0xFFFFFF
After shutting down your laptop or restarting Visual Studio Code you might need to reactivate your virtual environment via
source chooseanamehere/bin/activate
in the WSL terminal to continue working with the setup.
Connecting the virtual esphome device to your HA instance
The esphome node you run will not be autodetected by HA as usual, this needs additional steps:
- Windows needs to forward the esphome network connection to the virtual device, you can set that up using
netsh interface portproxy add v4tov4 listenport=6053 listenaddress=0.0.0.0 connectport=6053 connectaddress=172.123.123.123
in the windows command line. Replace the last ip address with the ip address your WSL environment has (find out by running “ifconfig” in your WSL environment)
-
Run a working yaml file and start the esphome node via Visual Studio Code and keep it running (aka: don’t close the small esphome display window that pops up after you execute “esphome run …”)
-
Add the esphome node manually in HA via Settings => Devices => esphome => “add device” and use the ip address of your laptop (not the one of the WSL environment)
This now allows you to e.g. use real sensor values from HA inside your virtual esphome node.
That’s it for now, more work to do here though:
ToAdd: more screenshots, notes about touchscreen support, …