From b0d7394e089f00a9ffa67a2b33a502e47b778a93 Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Sun, 17 May 2026 02:48:19 +0530
Subject: interop: ESP32 ↔ OpenWRT TollGate cross-platform test suite
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- interop/Makefile: 10 targets for 4 test scenarios
  - interop-status: show device status for all devices
  - interop-laptop-esp32: laptop pays ESP32 with V3 token
  - interop-laptop-openwrt: laptop pays OpenWRT with V4 token
  - interop-openwrt-esp32: OpenWRT daemon auto-pays ESP32 upstream
  - interop-esp32-esp32: cross-board payment (needs Board B)
  - interop-setup/cleanup: mint alignment + wallet funding
- INTEROP_PLAN.md: full test plan with scenarios and token format details
- PROGRESS.md: checklist of setup/interop tasks
- AGENTS.md: standing instructions for interop testing
- routers.env.example: device config template
- Verified interop-status against real hardware (OpenWRT + ESP32 Board A)
---
 interop/AGENTS.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 interop/AGENTS.md

(limited to 'interop/AGENTS.md')

diff --git a/interop/AGENTS.md b/interop/AGENTS.md
new file mode 100644
index 0000000..33a2d6d
--- /dev/null
+++ b/interop/AGENTS.md
@@ -0,0 +1,96 @@
+# AGENTS.md — Interop Test Standing Instructions
+
+## Overview
+
+Cross-platform interoperability tests for ESP32 TollGate firmware vs OpenWRT TollGate (tollgate-module-basic-go). Makefile-driven tests that verify Cashu e-cash token compatibility and upstream payment flows between the two implementations.
+
+## Standing Instructions
+
+1. **Always maintain these files:**
+   - `INTEROP_PLAN.md` — up-to-date interop test plan
+   - `PROGRESS.md` — checklist of done/pending items
+
+2. **Testing requirements:**
+   - All interop targets must be idempotent — safe to re-run
+   - Cleanup targets must restore original state
+   - Never leave a device in a broken state
+
+3. **Commit discipline:**
+   - Commit every time a test scenario passes end-to-end
+   - Push after each commit
+
+4. **No comments in code** unless explicitly requested
+
+5. **No secrets in git** — all secrets in `routers.env` (gitignored) or `.env`
+
+6. **Device safety:**
+   - Always save upstream state before changing it
+   - Always restore upstream state after tests
+   - Use router mutex (if shared with other sessions)
+
+## Repository Context
+
+This directory lives inside `esp32-tollgate/interop/`. The parent repo has its own `AGENTS.md` with firmware testing rules. This file covers interop testing only.
+
+## Device Access
+
+| Device | Transport | Address | Notes |
+|--------|-----------|---------|-------|
+| OpenWRT (alpha) | SSH | `root@10.47.41.1` | Ethernet at `enx00e04c683d2d` |
+| ESP32 Board A | WiFi API | `10.192.45.1` | WiFi at `wlp59s0`, SSID `TollGate-C0E9CA` |
+| ESP32 Board A | Serial | `/dev/ttyACM0` | USB serial, 115200 baud |
+| ESP32 Board B | Serial | `/dev/ttyACM1` | USB serial, 115200 baud |
+
+## Token Generation
+
+| Target | Tool | Format | Command |
+|--------|------|--------|---------|
+| ESP32 | `cashu` CLI | V3 (cashuA) | `cashu --env-mint testnut.cashu.space send --legacy 21` |
+| OpenWRT | `mint-token` | V4 | `/tmp/mint-token nofee.testnut.cashu.space 1` |
+
+**ESP32 only accepts V3 tokens.** OpenWRT accepts both V3 and V4.
+
+## Mint URLs
+
+| Mint | URL | Auto-pay |
+|------|-----|----------|
+| testnut | `https://testnut.cashu.space` | Yes |
+| nofee-testnut | `https://nofee.testnut.cashu.space` | Yes |
+
+Both must be in both devices' accepted_mints for cross-platform payment.
+
+## Key Commands
+
+```bash
+# Show all device status
+make interop-status
+
+# Full setup (mints + wallets)
+make interop-setup
+
+# Run individual scenarios
+make interop-laptop-esp32
+make interop-laptop-openwrt
+make interop-openwrt-esp32
+make interop-esp32-esp32
+
+# Cleanup after tests
+make interop-cleanup
+```
+
+## Network Interfaces
+
+| Interface | Device | Purpose |
+|-----------|--------|---------|
+| `enx00e04c683d2d` | Laptop | Ethernet to OpenWRT LAN (`10.47.41.x`) |
+| `wlp59s0` | Laptop | WiFi to ESP32 AP (`10.192.45.x`) |
+
+The laptop has simultaneous connectivity to both devices via different interfaces.
+
+## Troubleshooting
+
+- **OpenWRT unreachable**: Check ethernet cable, `ip addr show enx00e04c683d2d`
+- **ESP32 unreachable**: Check WiFi connection, `nmcli dev wifi connect TollGate-C0E9CA`
+- **Token rejected**: Check mint URL matches accepted_mints on target device
+- **OpenWRT won't auto-pay**: Check wallet balance > 0, check daemon logs `logread -e tollgate-wrt -f`
+- **ESP32 serial**: `python3 -m serial.tools.miniterm /dev/ttyACM0 115200`
-- 
cgit v1.2.3