ESP32/doc/ASYNC_MANUAL.md

ESP32 Fleet Management Tools: User Manual

This document provides instructions for using the asynchronous Python tools designed to manage, flash, and configure large fleets (30+) of ESP32 devices simultaneously.

⚠️ Build Target Selection (Carve Out)

Critical Step: Before using the mass deployment tools, you must define which chip architecture you are building for. The async_mass_deploy.py script relies on the project's current configuration.

Run one of the following commands in the project root to set the target:

Target Hardware	Command
Original ESP32	idf.py set-target esp32
ESP32-S3	idf.py set-target esp32s3
ESP32-C5	idf.py set-target esp32c5

Note: Changing the target forces a full clean rebuild. Ensure you see a successful configuration message before proceeding to deployment.

---

NVS Behavior Summary

Understanding how Non-Volatile Storage (NVS) is handled is critical to preventing data loss or configuration mismatch.

Script	Operation Mode	NVS Behavior	Use Case
async_mass_deploy.py	Default (No credentials)	Preserved	Updating firmware code without changing IP/WiFi settings.
async_mass_deploy.py	With SSID/Pass	Partially Rewritten	Updating firmware AND forcing new WiFi credentials/IPs.
async_mass_deploy.py	With --erase	WIPED Completely	Factory reset. Deletes all settings, calibration, and code.
async_batch_config.py	Normal Run	Partially Rewritten	Changing WiFi/IP settings without touching firmware.
async_find_failed.py	Audit / Diagnostics	Read-Only	Checking status. No changes to NVS.

---

1. async_mass_deploy.py

The "Factory Floor" Tool. Use this to flash the compiled binary (.bin) to the chips. It combines building, flashing (via esptool), and optional initial configuration.

When to use:

• You have new, blank ESP32 chips.
• You have modified the C code (main.c) and need to update the firmware.
• Devices are stuck in a boot loop and need a full erase.

Usage Examples:

A. Firmware Update Only (Preserve Settings) Updates the code but keeps the existing WiFi SSID, Password, and Static IP stored on the device.

python3 async_mass_deploy.py