229 lines
8.5 KiB
HTML
229 lines
8.5 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>ESP32 Fleet Management Manual</title>
|
|
<style>
|
|
body {
|
|
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
|
|
line-height: 1.6;
|
|
color: #333;
|
|
max-width: 900px;
|
|
margin: 0 auto;
|
|
padding: 20px;
|
|
background-color: #f9f9f9;
|
|
}
|
|
.container {
|
|
background-color: #fff;
|
|
padding: 40px;
|
|
border-radius: 8px;
|
|
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
|
|
}
|
|
h1 { border-bottom: 2px solid #eaeaea; padding-bottom: 10px; color: #2c3e50; }
|
|
h2 { margin-top: 30px; color: #34495e; border-bottom: 1px solid #eee; padding-bottom: 5px; }
|
|
h3 { margin-top: 20px; color: #455a64; }
|
|
|
|
table {
|
|
width: 100%;
|
|
border-collapse: collapse;
|
|
margin: 20px 0;
|
|
}
|
|
th, td {
|
|
border: 1px solid #ddd;
|
|
padding: 12px;
|
|
text-align: left;
|
|
}
|
|
th { background-color: #f2f2f2; color: #333; }
|
|
tr:nth-child(even) { background-color: #f9f9f9; }
|
|
|
|
code {
|
|
background-color: #f4f4f4;
|
|
padding: 2px 5px;
|
|
border-radius: 3px;
|
|
font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
|
|
font-size: 0.9em;
|
|
color: #d63384;
|
|
}
|
|
pre {
|
|
background-color: #2d3436;
|
|
color: #dfe6e9;
|
|
padding: 15px;
|
|
border-radius: 5px;
|
|
overflow-x: auto;
|
|
font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
|
|
}
|
|
pre code {
|
|
background-color: transparent;
|
|
color: inherit;
|
|
padding: 0;
|
|
}
|
|
|
|
.alert {
|
|
background-color: #fff3cd;
|
|
border: 1px solid #ffeeba;
|
|
color: #856404;
|
|
padding: 15px;
|
|
border-radius: 5px;
|
|
margin-bottom: 20px;
|
|
}
|
|
.info-box {
|
|
background-color: #e1f5fe;
|
|
border-left: 5px solid #039be5;
|
|
padding: 15px;
|
|
margin-bottom: 20px;
|
|
}
|
|
.tag-green { color: #27ae60; font-weight: bold; }
|
|
.tag-yellow { color: #f39c12; font-weight: bold; }
|
|
.tag-red { color: #c0392b; font-weight: bold; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<div class="container">
|
|
|
|
<h1>ESP32 Fleet Management Tools: User Manual</h1>
|
|
<p>This document provides instructions for using the asynchronous Python tools designed to manage, flash, and configure large fleets (30+) of ESP32 devices simultaneously.</p>
|
|
|
|
<div class="info-box">
|
|
<h2>🛠️ Critical Step: Set Build Target</h2>
|
|
<p>Before running <code>async_mass_deploy.py</code>, you <strong>must</strong> configure the project for your specific chip architecture. The deployment script uses the currently configured target.</p>
|
|
<p>Run <strong>one</strong> of the following commands in your project root before deployment:</p>
|
|
|
|
<p><strong>For Original ESP32:</strong></p>
|
|
<pre><code>idf.py set-target esp32</code></pre>
|
|
|
|
<p><strong>For ESP32-S3:</strong></p>
|
|
<pre><code>idf.py set-target esp32s3</code></pre>
|
|
|
|
<p><strong>For ESP32-C5:</strong></p>
|
|
<pre><code>idf.py set-target esp32c5</code></pre>
|
|
|
|
<p><em>Note: Changing the target triggers a full re-build. Ensure the build completes successfully before attempting mass deployment.</em></p>
|
|
</div>
|
|
|
|
<div class="alert">
|
|
<strong>⚠️ NVS Behavior Summary (Read First)</strong><br>
|
|
Understanding how Non-Volatile Storage (NVS) is handled is critical to preventing data loss or configuration mismatch.
|
|
</div>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Script</th>
|
|
<th>Operation Mode</th>
|
|
<th>NVS Behavior</th>
|
|
<th>Use Case</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>async_mass_deploy.py</code></td>
|
|
<td>Default</td>
|
|
<td><span class="tag-green">Preserved</span></td>
|
|
<td>Updating firmware code without changing IP/WiFi settings.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>async_mass_deploy.py</code></td>
|
|
<td>With SSID/Pass</td>
|
|
<td><span class="tag-yellow">Partially Rewritten</span></td>
|
|
<td>Updating firmware AND forcing new WiFi credentials/IPs.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>async_mass_deploy.py</code></td>
|
|
<td>With <code>--erase</code></td>
|
|
<td><span class="tag-red">WIPED Completely</span></td>
|
|
<td>Factory reset. Deletes all settings, calibration, and code.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>async_batch_config.py</code></td>
|
|
<td>Normal Run</td>
|
|
<td><span class="tag-yellow">Partially Rewritten</span></td>
|
|
<td>Changing WiFi/IP settings <em>without</em> touching firmware.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>async_find_failed.py</code></td>
|
|
<td>Audit / Diagnostics</td>
|
|
<td><span class="tag-green">Read-Only</span></td>
|
|
<td>Checking status. No changes to NVS.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<hr>
|
|
|
|
<h2>1. async_mass_deploy.py</h2>
|
|
<p><strong>The "Factory Floor" Tool.</strong> Use this to flash the compiled binary (<code>.bin</code>) to the chips. It combines building, flashing (via <code>esptool</code>), and optional initial configuration.</p>
|
|
|
|
<h3>When to use:</h3>
|
|
<ul>
|
|
<li>You have new, blank ESP32 chips.</li>
|
|
<li>You have modified the C code (<code>main.c</code>) and need to update the firmware.</li>
|
|
<li>Devices are stuck in a boot loop and need a full erase.</li>
|
|
</ul>
|
|
|
|
<h3>Usage Examples:</h3>
|
|
|
|
<p><strong>A. Firmware Update Only (Preserve Settings)</strong><br>
|
|
Updates the code but keeps the existing WiFi SSID, Password, and Static IP stored on the device.</p>
|
|
<pre><code>python3 async_mass_deploy.py</code></pre>
|
|
|
|
<p><strong>B. Full Factory Deployment (Erase & Provision)</strong><br>
|
|
Wipes the chip clean, flashes new code, and sets up WiFi/IPs from scratch.</p>
|
|
<pre><code>python3 async_mass_deploy.py \
|
|
--erase \
|
|
--start-ip 192.168.1.101 \
|
|
-s ClubHouse2G \
|
|
-p ez2remember</code></pre>
|
|
|
|
<hr>
|
|
|
|
<h2>2. async_batch_config.py</h2>
|
|
<p><strong>The "Field Update" Tool.</strong> Use this to change settings (IP, WiFi, Mode) on devices that are <em>already</em> running valid firmware. It is much faster than <code>mass_deploy</code> because it does not flash binaries.</p>
|
|
|
|
<h3>NVS Behavior:</h3>
|
|
<ul>
|
|
<li><strong>Rewrites:</strong> SSID, Password, IP, Gateway, Netmask, Mode, Bandwidth.</li>
|
|
<li><strong>Preserves:</strong> Any other NVS keys not explicitly touched by the config command.</li>
|
|
</ul>
|
|
|
|
<h3>Usage Examples:</h3>
|
|
|
|
<p><strong>A. Configure for Station Mode (Standard)</strong><br>
|
|
Sets sequential IPs starting at .101.</p>
|
|
<pre><code>python3 async_batch_config.py \
|
|
--start-ip 192.168.1.101 \
|
|
-s ClubHouse2G \
|
|
-P ez2remember</code></pre>
|
|
|
|
<p><strong>B. Configure for Monitor Mode (Sniffer)</strong><br>
|
|
Sets devices to listen promiscuously on Channel 36.</p>
|
|
<pre><code>python3 async_batch_config.py \
|
|
--start-ip 192.168.1.101 \
|
|
-s ClubHouse2G \
|
|
-P ez2remember \
|
|
-M MONITOR \
|
|
-mc 36 \
|
|
-ps NONE</code></pre>
|
|
|
|
<hr>
|
|
|
|
<h2>3. async_find_failed.py</h2>
|
|
<p><strong>The "Doctor" Tool.</strong> 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.</p>
|
|
|
|
<h3>NVS Behavior:</h3>
|
|
<ul>
|
|
<li><strong>Read-Only:</strong> Does not write to NVS during scanning.</li>
|
|
<li><strong>Recovery:</strong> The "Soft Reconnect" option sends a command to retry WiFi, but does not permanently alter the saved config.</li>
|
|
</ul>
|
|
|
|
<h3>Usage:</h3>
|
|
<pre><code>python3 async_find_failed.py</code></pre>
|
|
<p><em>Output:</em> Displays a table of Port, IP, Mode, and LED status.<br>
|
|
<em>Interactive Menu:</em> Allows you to reboot or send reconnect commands to failed devices found during the scan.</p>
|
|
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|