Project_SylDa/docs/superpowers/plans/2026-08-04-auto-detect-port-fix.md

Auto-detect Upload Port Fix Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Fix auto-detect upload port failure when active log output interferes with ID? response detection.

Architecture: Two-part fix — script-side filtering continues reading until ID match, firmware-side serial mute pauses all output during ID? response.

Tech Stack: Python 3 + pyserial (script), ESP32-S3 + Arduino + ESP-IDF logging (firmware)

---

File Structure

File	Action	Purpose
tools/pio_upload_port.py	Modify	Filter ID responses in query_id()
src/main.cpp	Modify	Add serial mute for server
src/client.cpp	Modify	Add serial mute for client

---

Task 1: Script-side ID filtering

Files:

• Modify: tools/pio_upload_port.py:46-61

• Step 1: Update query_id() to filter for ID response

Replace lines 46-61 in tools/pio_upload_port.py:

def query_id(port, timeout=5):
    try:
        ser = serial.Serial(port, 115200, timeout=0.5)
        time.sleep(0.1)
        ser.reset_input_buffer()
        ser.write(b"ID?\n")
        deadline = time.time() + timeout
        while time.time() < deadline:
            line = ser.readline().decode("utf-8", errors="ignore").strip()
            if "SylDa_Server" in line or "SylDa_Client" in line:
                ser.close()
                return line
        ser.close()
    except (serial.SerialException, OSError):
        pass
    return None

• Step 2: Commit

git add tools/pio_upload_port.py
git commit -m "fix(script): filter ID response in query_id()"

---

Task 2: Server firmware serial mute

Files:

• Modify: src/main.cpp

• Step 1: Add serialMuted flag and mute helper

After line 17 (static const char *TAG = "server";), add:

static bool serialMuted = false;

static void muteSerial() {
    serialMuted = true;
    esp_log_level_set("*", ESP_LOG_NONE);
}

static void unmuteSerial() {
    serialMuted = false;
    esp_log_level_set("*", CONFIG_LOG_DEFAULT_LEVEL);
}

• Step 2: Update ID? handler to use mute

Replace lines 591-592:

            } else if (serialBuf == "ID?") {
                Serial.flush();
                muteSerial();
                Serial.println("SylDa_Server");
                delay(50);
                unmuteSerial();

• Step 3: Commit

git add src/main.cpp
git commit -m "fix(server): add serial mute during ID? response"

---

Task 3: Client firmware serial mute

Files:

• Modify: src/client.cpp

• Step 1: Add serialMuted flag and mute helper

After line 15 (static const char *TAG = "client";), add:

static bool serialMuted = false;

static void muteSerial() {
    serialMuted = true;
    esp_log_level_set("*", ESP_LOG_NONE);
}

static void unmuteSerial() {
    serialMuted = false;
    esp_log_level_set("*", CONFIG_LOG_DEFAULT_LEVEL);
}

• Step 2: Update ID? handler to use mute

Replace lines 425-426:

            } else if (serialBuf == "ID?") {
                Serial.flush();
                muteSerial();
                Serial.println("SylDa_Client");
                delay(50);
                unmuteSerial();

• Step 3: Commit

git add src/client.cpp
git commit -m "fix(client): add serial mute during ID? response"

---

Task 4: Build and verify

• Step 1: Build both environments

pio run -e s3lite-server
pio run -e s3lite-client

Expected: Both compile without errors.

• Step 2: Verify firmware version bump

Check version.txt exists with correct format.

• Step 3: Push branch

git push -u origin fix/issue-16-auto-detect-port

---

Testing Checklist

After implementation, test with actual hardware:

1. Connect both server and client via USB
2. Run pio run -e s3lite-client -t upload — should auto-detect client
3. Run pio run -e s3lite-server -t upload — should auto-detect server
4. Verify log output resumes after upload completes
5. Test during active ECDH handshake (worst case)