Can I Add Post Build Actions to Arduino IDE? The PlatformIO & CLI Decision Path

The Direct Answer: Can I Add Post Build Actions to Arduino IDE?

The short answer is no, not natively within the Arduino IDE GUI (neither the legacy 1.8.x nor the modern 2.x). While the underlying arduino-cli engine supports build hooks via platform.txt, the Arduino IDE GUI sandboxes the execution environment. When you attempt to call a custom Python script or batch file to process your compiled .bin after linking, the GUI either strips the execution permissions, fails silently, or throws pathing errors due to spaces in the Windows AppData directory.

If you are trying to append a post-build action—like calculating an MD5 checksum for an OTA manifest, merging a LittleFS partition, or auto-compressing the binary with gzip—the Arduino IDE GUI is the wrong tool. Before you abandon your workflow, here are the first three things to check when your build hook fails:

1. Are you using the GUI instead of the CLI? If you must stay in the Arduino ecosystem, bypass the GUI and use arduino-cli compile in your terminal, which respects platform.local.txt hooks.
2. Is your platform.local.txt in the exact core directory? For ESP32, this is buried in ~/.arduino15/packages/esp32/hardware/esp32/[version]/. If you put it in the sketch folder, it will be ignored.
3. Are Windows path spaces breaking the hook? If your username has a space (e.g., C:\Users\John Doe\), the Arduino builder's hook parser will truncate the path at the space unless you wrap the entire execution string in escaped quotes.

The Decision Path: How to Actually Automate Your Build

Stop fighting the IDE's architecture. Use this decision matrix to pick the right toolchain for your post-build requirements. The concrete recommendation for any project requiring custom binary manipulation is to migrate to PlatformIO.

Hardware & Pin Mapping for the OTA Checksum Project

To demonstrate why post-build actions are critical, we will build an ESP32 OTA (Over-The-Air) updater that refuses to flash firmware unless the server provides a matching MD5 hash. The post-build script will automatically generate this hash every time you compile.

Parts List

• Microcontroller: ESP32-WROOM-32 DevKit V1 (30-pin, CP2102 USB-UART bridge)
• Power: USB-A to Micro-USB data cable (ensure it is not a charge-only cable)
• Indicator: Onboard SMD LED (Active LOW on most DevKit V1 clones)

Pin Mapping Table

The Firmware: ESP32 OTA Payload Validator

This code targets the esp32dev board variant (ESP32-WROOM-32). It connects to WiFi, fetches an firmware.md5 file generated by our post-build script, and applies it to the Update class before downloading the actual binary. This prevents bricking the device if the server binary is corrupted during upload.

#include <WiFi.h>
#include <HTTPClient.h>
#include <Update.h>

// --- Pin Definitions ---
#define STATUS_LED_PIN 2

// --- Network & Server Config ---
const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";
const char* manifest_url = "http://192.168.1.100/ota/firmware.md5";
const char* firmware_url = "http://192.168.1.100/ota/firmware.bin";

void setup() {
  pinMode(STATUS_LED_PIN, OUTPUT);
  digitalWrite(STATUS_LED_PIN, HIGH); // LED OFF (Active LOW)
  
  Serial.begin(115200);
  while(!Serial) { delay(10); }
  
  Serial.println("Booting OTA Validator...");
  WiFi.begin(ssid, password);
  
  int timeout = 0;
  while (WiFi.status() != WL_CONNECTED && timeout < 40) {
    delay(500);
    Serial.print(".");
    timeout++;
  }
  
  if (WiFi.status() != WL_CONNECTED) {
    Serial.println("\nWiFi Connection Failed. Halting.");
    return;
  }
  
  Serial.printf("\nConnected. IP: %s\n", WiFi.localIP().toString().c_str());
  checkAndApplyOTA();
}

void loop() {
  // Blink LED to indicate idle state
  digitalWrite(STATUS_LED_PIN, !digitalRead(STATUS_LED_PIN));
  delay(1000);
}

void checkAndApplyOTA() {
  HTTPClient http;
  
  // 1. Fetch the MD5 Manifest (Generated by Post-Build Script)
  Serial.println("Fetching MD5 manifest...");
  http.begin(manifest_url);
  int httpCode = http.GET();
  
  if (httpCode != HTTP_CODE_OK) {
    Serial.printf("Manifest fetch failed, error: %s\n", http.errorToString(httpCode).c_str());
    http.end();
    return;
  }
  
  String expected_md5 = http.getString();
  expected_md5.trim();
  http.end();
  
  if (expected_md5.length() != 32) {
    Serial.println("Error: Invalid MD5 string length from server.");
    return;
  }
  
  // 2. Fetch and Flash Firmware
  Serial.println("Fetching firmware binary...");
  http.begin(firmware_url);
  httpCode = http.GET();
  
  if (httpCode != HTTP_CODE_OK) {
    Serial.printf("Firmware fetch failed, error: %s\n", http.errorToString(httpCode).c_str());
    http.end();
    return;
  }
  
  int content_length = http.getSize();
  WiFiClient *client = http.getStreamPtr();
  
  if (!Update.begin(content_length)) {
    Serial.println("Error: Not enough space for OTA.");
    http.end();
    return;
  }
  
  // Apply the MD5 check BEFORE writing to flash
  Update.setMD5(expected_md5.c_str());
  
  Serial.println("Writing to flash...");
  digitalWrite(STATUS_LED_PIN, LOW); // LED ON during flash
  
  size_t written = Update.writeStream(*client);
  
  if (written != content_length) {
    Serial.printf("Error: Written %zu of %d bytes.\n", written, content_length);
    http.end();
    return;
  }
  
  if (!Update.end()) {
    Serial.printf("Update Error: %s\n", Update.errorString());
    http.end();
    return;
  }
  
  if (Update.isFinished()) {
    Serial.println("Update successful. Rebooting...");
    ESP.restart();
  } else {
    Serial.println("Update failed unexpectedly.");
  }
  
  http.end();
}

The Post-Build Script: Calculating the MD5 Manifest

In PlatformIO, you define post-build actions in a Python script using the SCons environment API. Create a file named post_build.py in the root of your project directory, and add extra_scripts = post:post_build.py to your platformio.ini.

import os
import hashlib
from SCons.Script import Import

Import("env")

def calculate_md5(file_path):
    hash_md5 = hashlib.md5()
    with open(file_path, "rb") as f:
        for chunk in iter(lambda: f.read(4096), b""):
            hash_md5.update(chunk)
    return hash_md5.hexdigest()

def post_build_action(source, target, env):
    # Path to the compiled firmware binary
    firmware_path = env.subst("$BUILD_DIR/${PROGNAME}.bin")
    
    if not os.path.exists(firmware_path):
        print(f"Post-Build Error: Firmware not found at {firmware_path}")
        return
    
    md5_hash = calculate_md5(firmware_path)
    manifest_path = os.path.join(env.subst("$BUILD_DIR"), "firmware.md5")
    
    with open(manifest_path, "w") as f:
        f.write(md5_hash)
    
    print(f"\n--- Post-Build Action Complete ---")
    print(f"Firmware MD5: {md5_hash}")
    print(f"Manifest saved to: {manifest_path}\n")

# Hook into the post-build phase (after linking and bin generation)
env.AddPostAction("$BUILD_DIR/${PROGNAME}.bin", post_build_action)

Troubleshooting: Exact Error Strings and Fixes

When working with build hooks, the compiler output can be opaque. Here are the exact error strings you will encounter and how to fix them.

Error 1: The Missing Binary

Exact String: FileNotFoundError: [Errno 2] No such file or directory: '.pio/build/esp32dev/firmware.bin'

• Cause (Most Likely): You used env.AddPostAction("$BUILD_DIR/${PROGNAME}.elf", ...) instead of targeting the .bin. The .elf is generated before the Espressif esptool.py converts it to a .bin. Your script runs before the binary exists.
• Fix: Ensure your hook targets the .bin extension as shown in the script above, or use the generic "buildprog" target if your core supports it.

Error 2: The MD5 Mismatch

Exact String: Update Error: ERROR_MD5_MISMATCH (Printed to Serial Monitor)

• Cause (Most Likely): You uploaded the firmware.bin to your web server via FTP in "ASCII" mode instead of "Binary" mode, which corrupted the line endings and changed the hash. Alternatively, you compiled a new version but forgot to upload the new firmware.md5 alongside it.
• Fix: Always transfer .bin files in Binary mode. Verify the server's .md5 file matches the local build output.

Error 3: PlatformIO Environment Attribute

Exact String: AttributeError: 'SConsEnvironment' object has no attribute 'AddPostAction'

• Cause: You placed the script logic outside the function scope or failed to Import("env") correctly at the top of the file.
• Fix: Ensure Import("env") is at the root of the Python file and that env.AddPostAction is called at the root indentation level, not inside a conditional block that evaluates to false.

How to Extend or Simplify the Build

Once you have the basic post-build hook running, you can adapt it to your specific production needs.

Extending the Build (Gzip Compression)

If your ESP32 is downloading firmware over a low-bandwidth cellular connection (e.g., via a SIM7600 modem), you can extend the Python script to gzip the binary and update the manifest. Add import gzip and import shutil to the Python script, and wrap the output in a .gz file. On the ESP32 side, you will need to stream-decompress the payload into the Update class using a library like ESP32-targz.

Simplifying the Build (Local Network Only)

If you are only flashing devices on your local workbench and don't need HTTP-based OTA manifests, strip the Python script and the HTTPClient logic entirely. Rely on the native ArduinoOTA library. ArduinoOTA uses mDNS and pushes the binary directly from the IDE/CLI over TCP, bypassing the need for external web servers and MD5 manifest files altogether. You can enable this by adding upload_protocol = espota to your platformio.ini.

For more details on the underlying build architecture, refer to the Arduino CLI Platform Specification and the PlatformIO Extra Scripts documentation. For ESP32 specific OTA mechanics, consult the Espressif OTA API Reference.