From e7f4d42161c17e482d7e9be9973e51310093c2e3 Mon Sep 17 00:00:00 2001
From: Eddy de Vink <github@eddydev.ink>
Date: Thu, 13 Aug 2026 12:43:14 +0200
Subject: [PATCH] Add usbtoggle-relay skill for USB power-cycle workflow

---
 .omp/skills/usbtoggle-relay/SKILL.md | 97 ++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 .omp/skills/usbtoggle-relay/SKILL.md

diff --git a/.omp/skills/usbtoggle-relay/SKILL.md b/.omp/skills/usbtoggle-relay/SKILL.md
new file mode 100644
index 0000000..35bbc2e
--- /dev/null
+++ b/.omp/skills/usbtoggle-relay/SKILL.md
@@ -0,0 +1,97 @@
+---
+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`).