Skip to content

Installation

Jump to bottom
MichalZaniewicz edited this page Jun 17, 2026 · 5 revisions

Installation

You can install this two ways: with the ESPHome dashboard (graphical, easiest - good for non-technical users) or from the command line. Either way the steps are: set your Wi-Fi + entities, do the first flash over USB (the 16 MB partition layout can't be set over the air), then all later updates go wireless.

How the config is structured

You keep one thin file, guition-va.yaml, with your entities and a packages: block. That block pulls the actual firmware - the always-on core (base/core.yaml) and the optional screens (base/screens/*.yaml) - straight from this GitHub repo at compile time, together with the fonts, images and sounds. So the only files that ever live on your disk are:

  • guition-va.yaml (your config)
  • partitions.csv (the flash layout - must be a local path, see below)
  • secrets.yaml (Wi-Fi)

Requirements

  • Home Assistant with the Assist voice pipeline configured (STT + TTS, and optionally an LLM/conversation agent). The on-device wake word only runs while the device is connected to HA.
  • ESPHome 2024.11+ - either the ESPHome Device Builder add-on in Home Assistant (the dashboard) or the esphome CLI. The config uses qspi_dbi with model: CUSTOM and a manual init_sequence, plus esp32_rmt_led_strip, micro_wake_word, voice_assistant, lvgl, the speaker media player, and remote packages: - all in stable ESPHome.
  • A USB-C cable for the first flash.
  • For the web flasher: a Chromium browser (Chrome or Edge).

1. Get the files

You only need two files from the repo on disk: guition-va.yaml and partitions.csv. The simplest way is to clone (or download) the repo and copy those two out; everything else (the base/ firmware and assets/) is fetched from GitHub during the build, so you don't have to keep it locally.

git clone https://github.com/MichalZaniewicz/esphome-guition-jc3636k718c-va.git

About partitions.csv (where, how, why, when)

  • What it is: a tiny text file that defines the flash layout (where the app, OTA slots and storage live). This board has 16 MB of flash, and because ESPHome bakes the images and fonts into the app binary, the file gives each of the two app slots the maximum size (~7.9 MB).
  • Where it goes: in the same folder as guition-va.yaml. The core refers to it with a plain relative path (partitions: partitions.csv), resolved next to the file you run, so it must sit beside your YAML even though the core is pulled remotely. On the dashboard that folder is /config/esphome/; on the CLI it is whatever directory you run esphome from. If the two files are not side by side the build fails with "partitions.csv not found".
  • Why it is a local file: unlike images/sounds (pulled from GitHub by URL), the partitions: option is handed straight to the build toolchain (PlatformIO) as a local path - it cannot be a URL, so this one file must exist on disk.
  • When it is used: at every compile/build (not just the first flash). It actually changes the device's flash layout only on the first USB flash; changing the layout later again requires a USB flash, never OTA.

2. Configure (Wi-Fi + your entities)

Secrets: create secrets.yaml with your Wi-Fi (in the dashboard use the Secrets editor; on the CLI copy the template cp secrets.example.yaml secrets.yaml):

wifi_ssid: "YOUR_WIFI_SSID"
wifi_password: "YOUR_WIFI_PASSWORD"

Entities: edit the substitutions: block at the top of guition-va.yaml:

substitutions:
  name: voice-knob                               # ESPHome node name
  friendly_name: "Voice Knob"
  timezone: "Europe/Warsaw"                      # IANA zone for the clock (DST automatic)
  ha_base_url: "http://homeassistant.local:8123" # your HA URL (for album art)
  player_entity: media_player.voice_knob_player  # this device's own player
  weather_entity: weather.home                   # home-screen weather
  room_temp_entity: sensor.temperature_...       # home-screen temperature
  room_hum_entity: sensor.humidity_...           # home-screen humidity
  forecast_entity: sensor.va_weekly_forecast     # weather screen (HA helper, see Configuration)

  # The four swipe-up control tiles - each is any HA entity + an icon name + a label:
  tile1_entity: light.living_room
  tile1_icon: "bulb"
  tile1_name: "Light"
  # ... tile2 / tile3 / tile4 the same

The control tiles are fully configurable here (no code editing) - see Configuration for the icon-name list and the weather forecast helper.

The API has no encryption key and OTA has no password in this config; add them if you want (see the api: / ota: blocks in base/core.yaml).

Choosing screens

In the packages: block of guition-va.yaml, comment out a base/screens/*.yaml line to drop that screen, and set the left-to-right carousel order with the screen_order substitution. The clock + control tiles + settings (in base/core.yaml) are always on.

3. Sounds (fetched automatically)

wake.wav and alarm.wav are pulled from GitHub at compile time, so it builds out of the box with nothing to copy. To use your own, point the two file: entries under media_player: in base/core.yaml at your files (16-bit PCM, mono, 16 kHz) or regenerate the originals with python scripts/make_sounds.py.

4. Before the first flash: read this

The very first flash is different from every later update, for two reasons:

1. The puck ships with Chinese factory firmware. Out of the box it runs a vendor demo, not ESPHome, so there is nothing to update over the air. The first flash has to be a full factory flash over USB with plain ESPHome (the standard "Factory format" / esphome run serial install). After that one USB flash, all later updates go wireless (OTA).

2. The 16 MB partition table (partitions.csv) is custom. In ESPHome the images, fonts and animations are compiled into the app binary, so this project uses a partition layout with the biggest possible app slots (~7.9 MB each). Changing the partition table can only be done by a full USB flash, never over OTA. That is the other reason the first flash must be USB.

Entering download (boot) mode. If the board does not show up as a serial port, or the flash will not start, put the ESP32-S3 into download mode by hand:

  1. Connect the USB-C cable.
  2. Hold the BOOT button (the small button to the left of the charging/USB port) pressed.
  3. While still holding it, power on / replug the device (or tap reset), then release BOOT after a second or two.
  4. The chip is now in download mode - start the flash. After it finishes, power-cycle the puck once and it boots straight into ESPHome.

You only need this dance for the first flash (or if a flash ever fails). Normal OTA updates afterwards need no buttons at all.

4a. Install with the ESPHome dashboard (GUI - recommended)

  1. Add ESPHome to HA: Settings → Add-ons → Add-on Store → ESPHome Device Builder → Install → Start → Open Web UI.
  2. Copy the project into ESPHome's folder. Put guition-va.yaml and partitions.csv into /config/esphome/, side by side in the same folder (use the Samba share, File editor, or Studio Code Server add-on). The build looks for partitions.csv next to the YAML, so both must live in that one folder. The base/ firmware and assets/ are pulled from GitHub during the build - nothing else to copy.
  3. Secrets: in the ESPHome dashboard click Secrets (top right) and add your wifi_ssid / wifi_password.
  4. Set entities: on the guition-va card click Edit, adjust the substitutions:, then Save.
  5. First flash (USB): plug the puck into the computer running the browser. On the card choose Install → Plug into this computer, pick the USB-C serial port, wait.
    • If HA runs on a machine with no USB access, use Install → Manual download → Factory format (.bin), then open https://web.esphome.io in Chrome/Edge, connect the puck over USB, and flash that file. (This first step must be USB because of the 16 MB partition table.)
  6. Later updates: Install → Wirelessly (OTA).

4b. Install with the CLI (alternative)

esphome run guition-va.yaml          # pick the USB serial port for the first flash

After the first USB flash, esphome run updates wirelessly (OTA).

5. Keeping up to date

Because the firmware is pulled from GitHub, getting the latest changes is just a re-pull:

esphome clean guition-va.yaml        # clears the cached package
esphome run   guition-va.yaml        # pulls the latest core + screens, then flashes (OTA)

(The config uses refresh: 0s, but esphome clean guarantees a fresh pull. Pin a specific version by setting ref: to a tag instead of a branch in the packages: block.)

6. Hook up Home Assistant

  1. HA → Settings → Devices & Services → the new ESPHome device appears → Configure.
  2. Assign an Assist pipeline to the device (this enables the wake word).
  3. (Optional) For the player's transport buttons and the control tiles, enable "Allow the device to perform Home Assistant actions" for the device.

7. Verify

  • Say "Alexa" -> the ring/overlay reacts, the wake beep plays, then speak a command.
  • Turn the knob -> volume changes (the ring shows a volume bar).
  • Swipe down -> Settings; swipe up -> control tiles; swipe left/right -> carousel.

If something's off, check Troubleshooting. You can stream live logs over the native API with python scripts/esplog.py <seconds> (set the host in the script).

Clone this wiki locally