Board setup (once)

Finish Setup PC.cmd first. Use the ESP-IDF 5.5.5 PowerShell terminal with P4 and S3 tools installed. Change into the extracted pack folder. This guide targets the Waveshare P4 rev3.x (32 MB) and S3-Touch-AMOLED-1.75 (16 MB flash / 8 MB PSRAM), not the 1.75C.

Match your round screens

Connect one round screen at a time using USB data. In the ESP-IDF terminal, identify the actual port and board:

python -m serial.tools.list_ports -v
python -m esptool --chip esp32s3 --port COMx read_mac
python -m esptool --chip esp32s3 --port COMx flash_id
python -m esptool --chip esp32s3 --port COMx get_security_info

These spellings match esptool 4.12 included with IDF 5.5.5. Replace COMx with its actual port. Record each board’s Wi-Fi station MAC, label it health, ammo or mission, then configure all three together (replace the example values):

.venv/Scripts/python.exe prepare.py --health-mac AA:BB:CC:DD:EE:01 --ammo-mac AA:BB:CC:DD:EE:02 --mission-mac AA:BB:CC:DD:EE:03

This generates experiments/doom_hud/wireless_private/. Keep it private and retain it for future updates. Both firmware builds must share it. Changing credentials or the board mapping means rebuilding and reflashing the P4 and all three S3s. All three S3s use the same firmware image; their MAC selects the role.

Build firmware

In the ESP-IDF 5.5.5 PowerShell terminal, change to the pack folder:

./Build-Firmware.ps1 -Board P4
./Build-Firmware.ps1 -Board S3

Outputs go to build/P4 and build/S3. The P4 config targets rev3.x with 32 MB flash; S3 targets 16 MB flash / 8 MB octal PSRAM. Do not apply this P4 build to earlier silicon or the S3 build to the 1.75C. The P4’s onboard C6 retains its factory ESP-Hosted firmware.

Back up, then install

Connect only the intended board. For the P4, use USB TO UART. For the S3, use its USB data connection; enter its download mode if needed according to Waveshare’s instructions. Check chip/revision, flash size and security state. Stop if those differ from section 4 or if secure boot/flash encryption is enabled.

Save each board’s full original flash in its own folder before replacing it. Example for one identified S3 in download mode:

New-Item -ItemType Directory -Force backups/health
python -m esptool --chip esp32s3 --port COMx read_flash 0 0x1000000 backups/health/original.bin
python -m esptool --chip esp32s3 --port COMx verify_flash 0 backups/health/original.bin
Get-FileHash backups/health/original.bin -Algorithm SHA256

Record port, MAC, chip, flash size and hash alongside the backup. For the P4 use --chip esp32p4 and size 0x2000000 (32 MB), after confirming its identity. Repeat separately for each S3. A successful readback is required before proceeding.

To install, in the IDF terminal, replace COMx for the intended board:

python "$env:IDF_PATH/tools/idf.py" -C experiments/p4_pc_stream/firmware -B build/P4 -p COMx flash
python "$env:IDF_PATH/tools/idf.py" -C experiments/doom_hud/satellite -B build/S3 -p COMx flash

Run the S3 command separately for each round display. Check each flash verification succeeds, then reset the board. Do not touch eFuses or flash the separate C6 radio. Restore only that board’s verified original image at offset 0 if needed, using esptool’s write_flash with its correct chip and port.

After flashing, move the P4 cable to USB for playback. Power the round displays via their USB ports. The P4 creates their private Wi-Fi network; your PC stays on its usual network. Open Play on PC.cmd and verify all four screens before assembling the stand.