---
name: usbtoggle-relay
description: >
  Hardwarematige USB power-cycle via een relais (Wemos D1 Mini) — USB-module
  af/aan koppelen door het relais te schakelen. TRIGGER: module programmeren/
  flashen (PlatformIO, ESP-IDF, MicroPython, esptool), module hangt of geen
  seriële poort, hardware reset / power cycle nodig, USB afkoppelen/aankoppelen,
  relais, usbtoggle, Wemos D1 vinden. Laatste redmiddel: alleen als
  softwarematige resets falen of niet bestaan.
---

# USB power-cycle via relais (usbtoggle)

## Doel

Een via USB aangesloten module (bv. ESP32-C3) hardwarematig af- en aankoppelen
door een relais te schakelen. Zo wordt een fysieke USB-handeling softwarematig
uitgevoerd — handig als een module hangt of niet meer als seriële poort
verschijnt.

**Relais aan = USB afgekoppeld** (module spanningsloos, verdwijnt van de USB-bus)
**Relais uit = USB aangekoppeld** (module krijgt voeding, verschijnt terug)

Dit is een **last resort**: pas toepassen als alle softwarematige resets voor
de desbetreffende module falen of niet bestaan (bv. `esptool` hard reset,
`machine.reset()`, herflashen, `pio device monitor` herverbinden).

## Hardware-opstelling

- Wemos D1 Mini (ESP8266) met relais-shield; relais-IN op **D1/GPIO5**.
  GPIO0 is bewust niet gebruikt (boot-strapping pin — laag houden boot het
  board in flash-modus).
- Het relais schakelt de voedingslijn van een andere USB-module (bv. ESP32-C3
  via USB-hub). Relais aan → die module verliest voeding.
- Code: `/Users/eddy/src/usbtoggle` (firmware + `relay`-script).

## De Wemos D1 vinden

De poortnaam (`/dev/cu.usbserial-XXXX`) **varieert per USB-poort en per
reboot** — nooit hardcoden. Detectie:

1. Lijst seriële poorten met USB-identiteit:

   ```bash
   python3 -c "
   import serial.tools.list_ports as p
   for x in sorted(p.comports()):
       print(x.device, '|', x.description, '|', x.hwid, '| serial=', x.serial_number)
   "
   ```

   De Wemos D1 (CH340) herken je aan `VID:PID=1A86:7523` en `desc='USB Serial'`.
   De ESP32-C3 (native USB) aan `VID:PID=303A:1001` en een serienummer dat
   gelijk is aan het MAC-adres. `LOCATION=...` is het fysieke USB-pad (stabiel
   zolang de module in dezelfde poort blijft).

2. Bevestiging via chip-ID (uniek per chip, onafhankelijk van poort):

   ```bash
   /Users/eddy/src/usbtoggle/relay id /dev/cu.usbserial-XXXX
   # → ID usbtoggle-relay B52BBC
   ```

   Bij meerdere modules: chip-ID per module noteren en per poort checken.

## Relais bedienen

```bash
cd /Users/eddy/src/usbtoggle
./relay 1 [poort]   # relais aan  → USB afgekoppeld (module uit)
./relay 0 [poort]   # relais uit  → USB aangekoppeld (module aan)
./relay id [poort]  # identificatie (chip-ID)
```

- Replies: `ON` / `OFF` / `ID ...`; exit 0 = gelukt, exit 1 = fout (usage,
  poort niet te openen, geen geldige reply).
- Het script opent de poort met DTR/RTS gedeasserted (geen CH340 auto-reset);
  als het board toch reset, wordt de boot-banner weggegooid (max 2 s wachttijd).

## Power-cycle workflow (module hangt)

1. Zoek de poort van de **Wemos D1** (zie boven), niet die van de hangende module.
2. `./relay 1 <d1-poort>` → wacht 2–3 s tot de module van `/dev/cu.*` verdwenen is.
3. `./relay 0 <d1-poort>` → wacht tot de module weer als seriële poort verschijnt
   (USB enumeration kan enkele seconden duren).
4. Controleer de poort van de module en ga verder met flashen/programmeren.
   Na een power-cycle is de module in fabrieksstaat wat betreft runtime-state:
   firmware opnieuw flashen als dat onderdeel van de flow is.

## Waarschuwingen

- Het relais schakelt **hardwarevoeding** — nooit togglen tijdens een actieve
  flash/schrijfactie; alleen bij hang of als reset nodig is.
- Relais-stand na boot van de Wemos D1 is altijd uit (firmware zet GPIO5 laag
  in `setup()`).
- Werkt alleen als de module daadwerkelijk via het relais gevoed wordt
  (verifiëren: relais aan → device verdwijnt van `serial.tools.list_ports`).