usbtoggle/.omp/skills/usbtoggle-relay/SKILL.md

name

description

usbtoggle-relay

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:

   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):

   /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

cd /Users/eddy/src/usbtoggle
./relay 1   # relais aan  → USB afgekoppeld (module uit)
./relay 0   # relais uit  → USB aangekoppeld (module aan)
./relay id  # identificatie (chip-ID)
./relay 1 /dev/cu.usbserial-XXXX   # poort expliciet opgeven (alleen als auto-detect faalt)

• Zonder poortargument zoekt het script de module automatisch: het probeert alle CH340-poorten (VID:PID=1A86:7523) met het id-commando en gebruikt de eerste die ID usbtoggle-relay antwoordt. De module wordt dus gevonden waar die ook is aangesloten; de poortnaam hoeft nooit hardcoded te worden.

• 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).