From 886cbf291a80c339e06f63f60a49eff7b34c30d8 Mon Sep 17 00:00:00 2001 From: Robert McMahon Date: Sun, 28 Dec 2025 17:53:13 -0800 Subject: [PATCH] Add USB port mapping instructions to README.md - Introduced a new section detailing the `gen_udev_rules.py` script for stable USB port mapping. - Explained features, usage, and installation steps for generated udev rules to ensure consistent device identification across reboots. --- README.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/README.md b/README.md index cb4e3ae..5b9c824 100644 --- a/README.md +++ b/README.md @@ -128,6 +128,37 @@ python3 esp32_deploy.py \ See `doc/DEPLOYMENT_GUIDE.md` for complete deployment instructions. +### USB Port Mapping (`gen_udev_rules.py`) + +When deploying to multiple ESP32 devices, Linux assigns `/dev/ttyUSB*` ports that can change between reboots or when devices are reconnected. The `gen_udev_rules.py` script creates stable symbolic links (e.g., `/dev/esp_port_01`, `/dev/esp_port_02`) based on each device's USB physical topology (`ID_PATH`), ensuring consistent port identification across system reboots. + +**Features:** +- Uses `ID_PATH` for stable device identification (not just port numbers) +- Creates predictable symlinks: `/dev/esp_port_01`, `/dev/esp_port_02`, etc. +- Supports full scan (generate from scratch) or incremental updates (append new devices) +- Sorts devices by physical USB topology for consistent ordering + +**Usage:** + +```bash +# Generate complete rules file from scratch +python3 gen_udev_rules.py --full + +# Append only new devices to existing rules (default mode) +python3 gen_udev_rules.py --append + +# Dry run to preview changes +python3 gen_udev_rules.py --append --dry-run +``` + +After generating rules, install them: +```bash +sudo cp 99-esp32-stable.rules /etc/udev/rules.d/ +sudo udevadm control --reload-rules && sudo udevadm trigger +``` + +The deployment script (`esp32_deploy.py`) can use these stable symlinks when `--map-ports` is used, or devices can be referenced directly by their `esp_port_XX` names. + ## Project Structure ```