Flash Devices

Flash Devices

Flash the current workspace firmware to a physical ESPHome device. Default to the Guition ESP32-S3 4848S040 over Wi-Fi at 192.168.6.100 unless the user names another device, gives another IP address, or explicitly asks for USB.

Default Target

Use dev.yaml by default because it includes local packages and local components from the current workspace. Do not use esphome.yaml or factory build wrappers unless the user specifically asks to flash a release/factory configuration.

Network Flash - Default

Use Docker ESPHome so the command works consistently without relying on a locally installed ESPHome CLI:

docker run --rm \
  -v "$PWD:/config" \
  ghcr.io/esphome/esphome:stable \
  run /config/devices/guition-esp32-s3-4848s040/dev.yaml \
  --device 192.168.6.100 \
  --no-logs

If the user provides another IP, keep the same config unless they also name a different device:

docker run --rm \
  -v "$PWD:/config" \
  ghcr.io/esphome/esphome:stable \
  run /config/devices/guition-esp32-s3-4848s040/dev.yaml \
  --device <ip-address> \
  --no-logs

--no-logs keeps the command as a one-shot flash instead of staying attached to the device logs after upload. Interpret a successful flash as ESPHome compiling successfully, connecting to the device, uploading the OTA image, and reporting completion without an error. If ESPHome cannot connect to 192.168.6.100, report that the device may be offline, on another IP, or not yet running compatible OTA firmware.

USB Flash

Use USB only when the user asks for USB, serial, or a physically connected device. Docker on macOS should compile the firmware, but the host should run esptool.py or esptool for the actual USB flash.

Compile first:

docker run --rm \
  -v "$PWD:/config" \
  ghcr.io/esphome/esphome:stable \
  compile /config/devices/guition-esp32-s3-4848s040/dev.yaml

Find the serial port:

ls /dev/cu.usb* /dev/cu.wchusbserial* /dev/tty.usb* /dev/tty.wchusbserial* 2>/dev/null

Find the compiled factory image, then flash it:

FIRMWARE="$(find "$PWD" -path '*/.esphome/build/music-dashboard-dev/.pioenvs/music-dashboard-dev/firmware.factory.bin' -print -quit)"
esptool.py --port <serial-port> --chip esp32s3 write_flash 0x0 "$FIRMWARE"

If esptool.py is not available, try esptool with the same arguments. If no serial port appears, ask the user to check the USB cable, port, and boot mode. If flashing times out, ask the user to hold BOOT while starting the flash.

Other Devices

If the user names another supported device, select its matching dev.yaml and chip:

For network flashing another device, require the user to provide the target IP. For USB flashing another device, use the listed chip in the esptool command.

Before Flashing

• Run from the worktree that contains the changes the user wants to test.
• If web UI assets may have changed, run python3 scripts/build.py before the ESPHome command so bundled assets are current.
• If Docker reports that the ESPHome image is missing or stale, pull ghcr.io/esphome/esphome:stable and retry.
• Do not commit, push, or change branches as part of flashing unless the user asks for that separately.

Report Back

Keep the result short and practical:

Flash result:
  Device: Guition ESP32-S3 4848S040
  Method: IP 192.168.6.100
  Config: devices/guition-esp32-s3-4848s040/dev.yaml
  Result: OK

For failures, include the first meaningful ESPHome or esptool error and the next action needed, such as checking power, Wi-Fi/IP, USB cable, or BOOT mode.