agentleFS
SensorsIotSensorsIot/Embedded-AI-Harness/.claude/skills/testbench-wifi/SKILL.md

testbench-wifi

Skill235 starsChanged 3 months agoMITView on GitHub

Use this skill whenever you need to control the testbench's WiFi radio for testing — starting a SoftAP for DUTs to connect to, joining a DUT's captive portal as a station, scanning for networks, relaying HTTP requests to devices on the WiFi network, or provisioning DUT WiFi credentials. Essential for any test that involves WiFi connectivity, captive portal flows, or HTTP communication with devices on the isolated test network (192.168.4.x). Triggers on "wifi", "AP", "station", "scan", "provision", "captive portal", "enter-portal", "HTTP relay", "wifi test", "SoftAP".

  • Sends data out

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If device doesn't connect, testbench joins the device's captive portal SoftAP (portal_ssid)

    line 168

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ESP32 WiFi & Provisioning

Base URL: $TESTBENCH_URL — see Step 0

Step 0: Point at a bench

There are several benches and their addresses move, so nothing here writes one down. $BENCH is not usable either — a container cannot resolve mDNS. Discover the bench and export its URL:

export TESTBENCH_URL=$(sudo python3 .claude/skills/esp-idf-handling/discover-testbench.py \
                         --url --name <bench-hostname>)
curl -s "$TESTBENCH_URL/api/info"        # confirm before anything else

--url refuses to guess when more than one bench answers, so --name is required whenever a second bench is powered on. TESTBENCH_URL is the same variable pytest --wt-url falls back to.

Operating Modes

The testbench has two WiFi operating modes:

Modewlan0 usageWiFi endpoints
wifi-testing (default)Test instrument (AP/STA/scan)Active
serial-interfaceJoins WiFi for additional LANDisabled
# Check current mode
curl $TESTBENCH_URL/api/wifi/mode

# Switch to wifi-testing mode
curl -X POST $TESTBENCH_URL/api/wifi/mode \
  -H 'Content-Type: application/json' \
  -d '{"mode": "wifi-testing"}'

# Switch to serial-interface mode (joins a WiFi network)
curl -X POST $TESTBENCH_URL/api/wifi/mode \
  -H 'Content-Type: application/json' \
  -d '{"mode": "serial-interface", "ssid": "MyNetwork", "pass": "password"}'

Endpoints

Request and response shapes: FSD Appendix D.4, plus /api/enter-portal in D.2.

AP and STA are mutually exclusive — one radio. Starting the AP drops any STA association and vice versa, so a test that needs both must sequence them.

WiFi AP (Access Point)

# Start AP
curl -X POST $TESTBENCH_URL/api/wifi/ap_start \
  -H 'Content-Type: application/json' \
  -d '{"ssid": "TestAP", "pass": "testpass123", "channel": 6}'

# Check AP status and connected clients
curl $TESTBENCH_URL/api/wifi/ap_status

# Stop AP
curl -X POST $TESTBENCH_URL/api/wifi/ap_stop

AP and STA are mutually exclusive — starting one stops the other.

WiFi STA (Station)

# Join a network
curl -X POST $TESTBENCH_URL/api/wifi/sta_join \
  -H 'Content-Type: application/json' \
  -d '{"ssid": "MyNetwork", "pass": "password", "timeout": 15}'

# Disconnect
curl -X POST $TESTBENCH_URL/api/wifi/sta_leave

WiFi Scan

curl $TESTBENCH_URL/api/wifi/scan

WiFi On/Off Testing

To test a device's behavior when WiFi connectivity is lost and restored:

# 1. Ensure device is connected to testbench AP
curl -X POST $TESTBENCH_URL/api/wifi/ap_start \
  -H 'Content-Type: application/json' \
  -d '{"ssid": "TestAP", "pass": "testpass123"}'

# 2. Stop AP — device loses WiFi
curl -X POST $TESTBENCH_URL/api/wifi/ap_stop

# 3. Monitor device behavior (serial or UDP logs)
# ... wait for desired duration ...

# 4. Restart AP — device should reconnect
curl -X POST $TESTBENCH_URL/api/wifi/ap_start \
  -H 'Content-Type: application/json' \
  -d '{"ssid": "TestAP", "pass": "testpass123"}'

# 5. Wait for device to reconnect
curl "$TESTBENCH_URL/api/wifi/events?timeout=30"

HTTP Relay

IMPORTANT: Devices on the testbench AP (192.168.4.x) are NOT directly reachable from the development machine. Always use this relay to make HTTP requests to device endpoints (e.g. /status, /ota). The response body is base64-encoded — decode it to get the actual JSON.

# GET request to device
curl -X POST $TESTBENCH_URL/api/wifi/http \
  -H 'Content-Type: application/json' \
  -d '{"method": "GET", "url": "http://192.168.4.2/status", "timeout": 10}'

# POST with base64-encoded body
BODY=$(echo -n '{"key":"value"}' | base64)
curl -X POST $TESTBENCH_URL/api/wifi/http \
  -H 'Content-Type: application/json' \
  -d "{\"method\": \"POST\", \"url\": \"http://192.168.4.2/config\", \"headers\": {\"Content-Type\": \"application/json\"}, \"body\": \"$BODY\", \"timeout\": 10}"

# Decode the base64 response body
curl -s -X POST $TESTBENCH_URL/api/wifi/http \
  -H 'Content-Type: application/json' \
  -d '{"method": "GET", "url": "http://192.168.4.x:8080/endpoint", "timeout": 10}' \
  | python3 -c "import json,sys,base64; r=json.load(sys.stdin); print(base64.b64decode(r['body']).decode())"

WiFi Events

Long-poll for STA_CONNECT / STA_DISCONNECT events:

curl "$TESTBENCH_URL/api/wifi/events?timeout=30"

Enter-Portal (Captive Portal Provisioning)

Ensures a device is connected to the testbench AP. If the device has no WiFi credentials, the testbench provisions it via the device's captive portal.

curl -X POST $TESTBENCH_URL/api/enter-portal \
  -H 'Content-Type: application/json' \
  -d '{"portal_ssid": "<DUT-portal-SSID>", "ssid": "TestAP", "password": "testpass123"}'
FieldDescription
portal_ssidDevice's captive portal SoftAP name
ssidTestbench's AP SSID (filled into the device's portal form)
passwordTestbench's AP password (filled into the device's portal form)

Procedure:

  1. Starts testbench AP (using ssid/password) if not already running
  2. Waits for the device to connect (it may already have credentials)
  3. If device doesn't connect, testbench joins the device's captive portal SoftAP (portal_ssid)
  4. Follows the auto-redirect to the portal page
  5. Parses the HTML form and fills in the testbench AP credentials
  6. Submits the form
  7. Disconnects from the device's SoftAP
  8. Waits for the device to reboot and connect to the testbench AP

All three values must come from the project FSD — never guess them.

Monitor progress via GET /api/log.

Getting the device into portal mode first

/api/enter-portal assumes the device will offer its portal. A device that already holds credentials will not, so the portal has to be forced. Three ways, best first — all of them need the pin, the active level and the serial marker looked up in the project's FSD:

GPIO — fully automated, when a Pi pin is wired to the device's portal button:

try:
    wt.gpio_set(PI_PIN, 0)                 # hold the portal pin low
    result = wt.serial_reset(SLOT)          # reset — device boots into portal
    assert any(PORTAL_MARKER in l for l in result["output"])
finally:
    wt.gpio_set(PI_PIN, "z")               # always release, even on failure

Release the pin in a finally: left driven, it holds the device in portal mode for every later test in the run. ok: true confirms the write — do not poll gpio_get() to check.

Rapid resets — for firmware with a boot-counter trigger: wt.enter_portal(SLOT, resets=3), then wait for idle.

An operator — no GPIO wiring: raise a blocking prompt (see testbench-test-handling) on a thread, reset, and match the marker while the operator holds the button.

Common Workflows

  1. Ensure device is connected to testbench AP:
    • POST /api/enter-portal with all three values
    • GET /api/wifi/ap_status — verify device appears as connected client
  2. Test device WiFi connectivity:
    • POST /api/enter-portal — ensure device is on testbench AP
    • POST /api/wifi/http — relay HTTP to device's IP to verify it responds
  3. Test WiFi disconnect/reconnect behavior:
    • POST /api/wifi/ap_stop — device loses WiFi
    • Monitor device via serial (see testbench-logging)
    • POST /api/wifi/ap_start — device should reconnect
    • GET /api/wifi/events — confirm reconnection

Troubleshooting

ProblemFix
AP won't startCheck that mode is wifi-testing via GET /api/wifi/mode
STA join timeoutVerify SSID/password; increase timeout
HTTP relay failsEnsure testbench is on same network as target (AP or STA)
enter-portal "already running"Previous run still active; wait for it to finish
No events from long-pollDUT may not have connected yet; increase timeout
WiFi endpoints return "disabled"System is in serial-interface mode; switch to wifi-testing

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.