PlatformIO Firmware Flashing

Applicable Scenarios

• Project Profile

  specifies

  build_system: platformio

  or

  platformio.ini

  exists in the workspace.
• Users want to flash compiled artifacts to the target board using PlatformIO's built-in upload mechanism.
• Supports multiple upload protocols such as serial port, JTAG, DFU, determined by

  upload_protocol

  in

  platformio.ini

  .

Required Inputs

• PlatformIO project directory (contains

  platformio.ini

  ).
• Optional environment name and upload port.

Automatic Detection

• Automatically locates the

  pio

  CLI.
• Parses the list of environments and

  upload_protocol

  in

  platformio.ini

  .
• If no environment is specified, uses

  default_envs

  or the first environment.
• Can list connected devices to help users confirm the port.

Execution Steps

1. First read references/usage.md to confirm the operation.
2. For common scenarios, complete flashing with a single call:
   bash

   python scripts/pio_flasher.py --flash --project-dir <project directory> --env <environment name>

3. To specify an upload port:
   bash

   python scripts/pio_flasher.py --flash --project-dir <project directory> --env <environment name> --upload-port COM3

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

   Project Profile

   and recommend the next skill.

Failure Diversion

• connection-failure

  : Device not connected, serial port occupied, or insufficient permissions.

• project-config-error

  : Invalid board configuration or environment name does not exist.

• upload-failure

  : Error occurred during upload.

Output Convention

Flashing succeeded ✅
  Project: ESP32_DEV → Environment: esp32dev
  Board: esp32dev | Platform: espressif32
  Firmware: firmware.bin (200.0 KB)
  Time taken: 15.3 seconds

• After success, recommend

  serial-monitor

  (view serial output) or

  debug-platformio

  (online debugging).
• Output failure category and log evidence when failed.

Handover Relationships

• Receives project information of successful compilation from

  build-platformio

  .
• After successful flashing, hand over to

  serial-monitor

  (view serial output) or

  debug-platformio

  (online debugging).