flash-platformio

PlatformIO Flashing

Applicable Scenarios

• Project Profile is specified in build_system: platformio or exists in the workspace platformio.ini。
• The user wants to flash the build artifacts to the target board, using PlatformIO's built-in upload mechanism.
• Supports multiple upload protocols such as serial, JTAG, DFU, etc., determined by the platformio.ini in upload_protocol .

Required Inputs

• PlatformIO project directory (containing platformio.ini）。
• Optional environment name and upload port.

Automatic Detection

• On script startup, automatically reuse the last successful profile in the project root directory .em_skill.json as default parameters (explicit parameters take precedence, no need to manually pass --resume）；--resume is only used to assert that the cache must exist; if there is no cache, exit with a non-zero code. When there is no cache or the user explicitly requests re-detection, the script automatically falls back to a normal scan.
• Automatically locate pio CLI。
• Parse the environment list in platformio.ini and upload_protocol。
• If no environment is specified, use default_envs or the first environment.
• Can list connected devices to help the user confirm the port.

Execution Steps

1. First read references/usage.md, and confirm this operation.
2. For common scenarios, complete flashing directly with a single call:

   python scripts/pio_flasher.py --flash --project-dir <工程目录> --env <环境名>
   

3. If an upload port needs to be specified:

   python scripts/pio_flasher.py --flash --project-dir <工程目录> --env <环境名> --upload-port COM3
   

4. Read the flashing result report output by the script, focusing on the success/failure status and evidence.
5. Write the flashing result back to Project Profile, and recommend the next skill.

Failure Triage

• connection-failure: device not connected, serial port occupied, or insufficient permissions.
• project-config-error: invalid board configuration or non-existent environment name.
• upload-failure: an error occurred during the upload process.

Output Conventions

Example output format:

烧录成功 ✅
  工程: ESP32_DEV → 环境: esp32dev
  板卡: esp32dev | 平台: espressif32
  固件: firmware.bin (200.0 KB)
  耗时: 15.3 秒

• On success, recommend serial-monitor(view serial output) or debug-platformio(online debugging).
• On failure, output the failure category and log evidence.

Handoff Relationships

• Receive successfully compiled project information from build-platformio .
• After successful flashing, hand off to serial-monitor(view serial output) or debug-platformio(online debugging).