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.

🛠️ Critical Step: Set Build Target

Before running async_mass_deploy.py, you must configure the project for your specific chip architecture. The deployment script uses the currently configured target.

Run one of the following commands in your project root before deployment:

For Original ESP32:

idf.py set-target esp32

For ESP32-S3:

idf.py set-target esp32s3

For ESP32-C5:

idf.py set-target esp32c5

Note: Changing the target triggers a full re-build. Ensure the build completes successfully before attempting mass deployment.

⚠️ NVS Behavior Summary (Read First)
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	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

B. Full Factory Deployment (Erase & Provision)
Wipes the chip clean, flashes new code, and sets up WiFi/IPs from scratch.

python3 async_mass_deploy.py \
  --erase \
  --start-ip 192.168.1.101 \
  -s ClubHouse2G \
  -p ez2remember

2. async_batch_config.py

The "Field Update" Tool. Use this to change settings (IP, WiFi, Mode) on devices that are already running valid firmware. It is much faster than mass_deploy because it does not flash binaries.

NVS Behavior:

Rewrites: SSID, Password, IP, Gateway, Netmask, Mode, Bandwidth.
Preserves: Any other NVS keys not explicitly touched by the config command.

Usage Examples:

A. Configure for Station Mode (Standard)
Sets sequential IPs starting at .101.

python3 async_batch_config.py \
  --start-ip 192.168.1.101 \
  -s ClubHouse2G \
  -P ez2remember

B. Configure for Monitor Mode (Sniffer)
Sets devices to listen promiscuously on Channel 36.

python3 async_batch_config.py \
  --start-ip 192.168.1.101 \
  -s ClubHouse2G \
  -P ez2remember \
  -M MONITOR \
  -mc 36 \
  -ps NONE

3. async_find_failed.py

The "Doctor" Tool. Use this to audit the status of the fleet. It does not flash or configure; it only asks the devices "Are you okay?" and displays the result.

NVS Behavior:

Read-Only: Does not write to NVS during scanning.
Recovery: The "Soft Reconnect" option sends a command to retry WiFi, but does not permanently alter the saved config.

Usage:

python3 async_find_failed.py

Output: Displays a table of Port, IP, Mode, and LED status.
Interactive Menu: Allows you to reboot or send reconnect commands to failed devices found during the scan.