esp-brookesia-build-flash

name

esp-brookesia-build-flash

description

Use when working in this esp-brookesia repository to regenerate board manager config, compile ESP-IDF firmware, package merged firmware binaries, flash a board, capture startup logs, or troubleshoot repo-specific build/package/flash issues such as stale sdkconfig pollution, merged-bin path quirks, board defaults not taking effect, COM port contention, or missing board-side audio/display initialization.

ESP-Brookesia Build, Package & Flash

Build and flash from the example project at examples/agent/chatbot. Treat board selection, board_manager.defaults, and sdkconfig state as part of the build input, not as passive background files.

Quick Start

1. Enter the project directory: <ESP_BROOKESIA_REPO>\examples\agent\chatbot
2. Load the ESP-IDF environment in the way you normally use it. The repo script does not lock to a specific IDF version path. One example on Windows is:

. 'C:\Espressif\tools\Microsoft.v5.5.4.PowerShell_profile.ps1'

3. Regenerate board manager config before building a board whose YAML or sdkconfig.defaults.board changed:

idf.py gen-bmgr-config -b rymcu_bigsmart

4. Reconfigure and build:

idf.py reconfigure build

5. Package the firmware with the bundled skill script. This step already produces the merged package artifacts:

& '<THIS_REPO>\scripts\package-merged-firmware.ps1' -RepoRoot '<ESP_BROOKESIA_REPO>' -Board rymcu_bigsmart

If your current working directory is already inside the repo, the script can auto-detect -RepoRoot and you can omit it.

6. Flash:

idf.py -p <PORT> flash

7. If you only need a short boot log, prefer a short serial capture over a long-running monitor.

Workflow

1. Regenerate board config first when board-side changes are involved

• Run idf.py gen-bmgr-config -b <board> after changing:
  • board_peripherals.yaml
  • board_devices.yaml
  • sdkconfig.defaults.board
  • board-specific setup code
• Expect generated outputs under examples/agent/chatbot/components/gen_bmgr_codes/.
• Treat components/gen_bmgr_codes/board_manager.defaults as the bridge between board YAML/defaults and the final build.

2. Watch for stale sdkconfig

• A stale sdkconfig can silently keep old board options active and make it look like code changes did nothing.
• In this repo, idf.py gen-bmgr-config -b rymcu_bigsmart may back up the old file to sdkconfig.bmgr_board.old to prevent configuration pollution.
• After regeneration and reconfigure, verify the final examples/agent/chatbot/sdkconfig really contains the expected board options before trusting the build.

For rymcu_bigsmart, the critical recorder route options are:

CONFIG_BROOKESIA_HAL_ADAPTOR_AUDIO_CODEC_RECORDER_ENABLE_MAIN_REFERENCE_ROUTE=y
CONFIG_BROOKESIA_HAL_ADAPTOR_AUDIO_CODEC_RECORDER_MAIN_REFERENCE_ROUTE_RAW_CHANNELS=4
CONFIG_BROOKESIA_HAL_ADAPTOR_AUDIO_CODEC_RECORDER_MAIN_REFERENCE_ROUTE_GAIN_CHANNELS=4
CONFIG_BROOKESIA_HAL_ADAPTOR_AUDIO_CODEC_RECORDER_MAIN_REFERENCE_ROUTE_MAIN_SLOT=2
CONFIG_BROOKESIA_HAL_ADAPTOR_AUDIO_CODEC_RECORDER_MAIN_REFERENCE_ROUTE_MAIN_GAIN_CHANNEL=1
CONFIG_BROOKESIA_HAL_ADAPTOR_AUDIO_CODEC_RECORDER_MAIN_REFERENCE_ROUTE_REFERENCE_SLOT=1
CONFIG_BROOKESIA_HAL_ADAPTOR_AUDIO_CODEC_RECORDER_MAIN_REFERENCE_ROUTE_REFERENCE_GAIN_CHANNEL=2

3. Build from the example project, not the repo root

• Use examples/agent/chatbot as the working directory for idf.py.
• After a successful build, check:
  • build/example_agent_chatbot.bin
  • build/bootloader/bootloader.bin
  • build/partition_table/partition-table.bin
  • build/flash_args

4. Prefer the bundled merged-package script for handoff artifacts

• Use scripts\package-merged-firmware.ps1 as the source-of-truth packaging flow.
• Treat this packaging step as the merge step too. It already generates the merged bin, timestamped package directory, and zip archive; do not plan an extra post-package merge unless the user explicitly asks for a different artifact shape.
• Pass -RepoRoot <ESP_BROOKESIA_REPO> when you invoke the bundled script from outside the repo. If you run it from examples/agent/chatbot or another repo subdirectory, it can auto-detect the root from the current working directory.
• The script:
  • first uses the current shell's ESP-IDF environment when idf.py is already available
  • optionally accepts -PowerShellProfile or -IdfPath
  • can auto-discover a Windows ESP-IDF PowerShell profile or export.ps1 when needed
  • can auto-discover the repo root or accept -RepoRoot explicitly
  • does not hardcode a single ESP-IDF version path
  • regenerates board config by default
  • reconfigures and builds the chatbot example
  • merges all flash partitions into build/<board>_merged.bin
  • creates a timestamped package under build/packages/<board>/<timestamp>/
  • emits manifest.json, flash_args.txt, flasher_args.json, and a zip archive
• The merged raw image is intended to flash at offset 0x0.
• Prefer direct python -m esptool ... merge_bin @flash_args inside the build directory when scripting. It avoids the relative-output-path pitfalls of idf.py merge-bin.

5. Flash and verify immediately

• Flash with idf.py -p <port> flash.
• If you already created a merged package, you can also flash it directly with:

python -m esptool --chip esp32s3 -p <PORT> -b 460800 --before default_reset --after hard_reset write_flash 0x0 build\rymcu_bigsmart_merged.bin

• If the serial port is busy, look for leftover idf.py monitor / esp_idf_monitor Python processes and stop them before retrying.
• After flash, capture startup logs and confirm the board initialized the expected peripherals instead of assuming success from esptool.py alone.

RYMCU BigSmart Checks

For rymcu_bigsmart, the most useful post-flash checks are:

• Board selection:
  • Selected Board: rymcu_bigsmart
• ES7210 / audio ADC bring-up:
  • ES7210: Enable ES7210_INPUT_MIC1
  • ES7210: Enable ES7210_INPUT_MIC2
  • ES7210: Enable ES7210_INPUT_MIC3
  • ES7210: Enable ES7210_INPUT_MIC4
  • ES7210: Enable TDM mode
• I2S RX mode:
  • I2S_IF: TDM mode, dir: RX
  • total_slot: 4
  • slot_mask: 0xf
• AFE startup:
  • pcm_config.total_ch_num: 2
  • pcm_config.mic_num: 1: [ ch0 ]
  • pcm_config.ref_num: 1: [ ch1 ]
  • aec_init: true

If those lines are missing, do not assume the mic problem is fixed.

Troubleshooting Rules

• If board-specific Kconfig changes seem ignored, suspect stale sdkconfig before suspecting driver code.
• If gen-bmgr-config was not rerun after board file changes, rerun it before debugging runtime behavior.
• If flash succeeded but behavior did not change, verify the new sdkconfig, build timestamp, and startup logs all reflect the intended board/config.
• If merged packaging fails, inspect build/flash_args and build/flasher_args.json before changing offsets by hand.
• If idf.py merge-bin writes to an unexpected location or fails on a relative output path, switch to an absolute output path or use the bundled script.
• If the bundled script cannot locate the repo automatically, rerun it from somewhere inside the repo or pass -RepoRoot <ESP_BROOKESIA_REPO>.
• If you only need proof of boot-time initialization, use a short pyserial capture instead of leaving a monitor attached.
• Use build/flash_args when you need to confirm exactly which binaries and offsets were flashed.

Reference Map

• Read rymcu-bigsmart-build-flash.md for the concrete command sequence, expected log snippets, and common failure patterns that came up during the bigsmart adaptation.
• Read rymcu-bigsmart-merge-package.md for the exact merged-package layout, merge command, and packaging outputs used for rymcu_bigsmart.