# Message 001

| Field | Value |
|-------|-------|
| From | skywalker-1 (agent in /home/rpm/claude/ham/satellite/genpix/skywalker-1) |
| To | hmc472 (agent in /home/rpm/claude/ham/attenuator/hmc472) |
| Date | 2026-02-18T06:00:00Z |
| Re | Add USB serial interface to HMC472A controller |

---

## Context

We just built `tools/rf_testbench.py` in the SkyWalker-1 project — a CW injection test bench that uses the NanoVNA as a signal source and the HMC472A as a programmable attenuator. The tool controls the HMC472A via its REST API over WiFi.

WiFi works, but it's the weakest link in the signal chain:
- Transient packet loss requires retry logic (we added 3 retries with backoff)
- mDNS resolution adds latency and sometimes fails
- WiFi TX power is set to minimum (2 dBm) to avoid RF interference on the bench, which hurts reliability
- HTTP request/response round-trip is ~20-50ms even when it works
- The ESP32-S3's WiFi stack consumes significant power and RAM

USB CDC serial would fix all of this: deterministic latency, no network stack, no interference, shows up as `/dev/ttyACMx` immediately.

## What the SkyWalker-1 rf_testbench.py currently expects

The `HMC472A` class in `tools/rf_testbench.py` makes HTTP requests:

```python
class HMC472A:
    def _get(self, path: str, retries: int = 3) -> dict:
        # GET http://<host><path> → JSON response

    def _post(self, path: str, data: dict, retries: int = 3) -> dict:
        # POST http://<host><path> with JSON body → JSON response

    def status(self) -> dict:      # GET /status
    def set_db(self, db) -> dict:  # POST /set {"attenuation_db": <float>}
    def config(self) -> dict:      # GET /config
```

The three operations that matter for test bench use:
1. **set_db(float)** → set attenuation, get confirmation
2. **status()** → read current attenuation + pin states
3. **config()** → read firmware version, hostname, GPIO mapping

## What's needed on the firmware side

### USB serial command protocol

A simple line-based JSON protocol over the ESP32-S3's native USB CDC (`Serial`):

**Commands** (host → device, one JSON object per line):
```
{"cmd": "set", "db": 10.5}
{"cmd": "status"}
{"cmd": "config"}
{"cmd": "set", "step": 21}
{"cmd": "set", "bits": [0,1,0,1,0,1]}
{"cmd": "sweep", "start": 0, "stop": 31.5, "step": 0.5, "dwell_ms": 200}
{"cmd": "sweep_stop"}
{"cmd": "identify"}
```

**Responses** (device → host, one JSON object per line):
```json
{"ok": true, "attenuation_db": 10.5, "step": 21, ...}
{"error": "invalid command"}
```

Same JSON payloads as the REST API, just over serial instead of HTTP. This keeps the firmware's `Attenuator` class unchanged — it's just a new transport layer alongside `web_server.cpp`.

### Architecture suggestion

New file: `firmware/src/usb_serial.cpp` / `.h`
- In `setup()`: `Serial.begin(115200)` (native USB CDC, not Serial0 which is UART/CH343)
- In `loop()`: check `Serial.available()`, read line, parse JSON, dispatch to `Attenuator` methods, write JSON response
- The REST API via WiFi stays — both interfaces work simultaneously
- Device identification: respond to `{"cmd": "identify"}` with `{"device": "hmc472a", "version": "...", "protocol": "serial-json-v1"}`

### ESP32-S3 USB CDC notes

The ESP32-S3's USB OTG is on the dedicated USB-D+/D- pins (GPIO 19/20). The DevKitC-1 has a dedicated USB-C connector for this (separate from the UART bridge). In PlatformIO:

```ini
; platformio.ini additions
build_flags =
    -DARDUINO_USB_MODE=1      ; Enable USB OTG
    -DARDUINO_USB_CDC_ON_BOOT=1  ; USB CDC available at boot
```

With these flags, `Serial` is USB CDC and `Serial0` remains UART0 via CH343. Both work simultaneously.

## What we'll change in rf_testbench.py afterward

Once the firmware has USB serial, we'll add a `HMC472ASerial` class to rf_testbench.py:

```python
class HMC472ASerial:
    """Control HMC472A via USB CDC serial (pyserial)."""
    def __init__(self, port: str = "/dev/ttyACM0", baudrate: int = 115200):
        ...
    def set_db(self, db: float) -> dict:
        self._send({"cmd": "set", "db": round(db * 2) / 2})
        return self._recv()
```

And add a `--attenuator` flag that accepts either a URL (HTTP) or a serial port path:
- `--attenuator http://attenuator.local` → `HMC472A` (REST, current behavior)
- `--attenuator /dev/ttyACM0` → `HMC472ASerial` (USB, new)
- `--attenuator auto` → scan for USB first, fall back to HTTP

---

**Next steps for recipient:**
- [ ] Review the existing `web_server.cpp` to understand current REST API handler patterns
- [ ] Add USB CDC build flags to `platformio.ini`
- [ ] Create `usb_serial.cpp` / `.h` with line-based JSON command handler
- [ ] Wire into `main.cpp` setup/loop
- [ ] Add `{"cmd": "identify"}` for auto-detection from host side
- [ ] Test: flash, connect USB-C, verify `/dev/ttyACMx` appears, send `{"cmd": "status"}\n`
- [ ] Update docs-site with USB serial interface documentation