Skip to content

E2E test: API call trigger + hardware reliability (ESP32 reset, address fallback) - #39

Merged
JamesSmartCell merged 2 commits into
masterfrom
cursor/e2e-api-trigger-557d
Nov 17, 2026
Merged

JamesSmartCell merged 2 commits into
masterfrom
cursor/e2e-api-trigger-557d

Conversation

@JamesSmartCell

Copy link
Copy Markdown
Member

Overview

This PR completes the E2E hardware test to verify the full TCP bridge protocol including API call forwarding through the public proxy. Adds critical hardware reliability improvements for real-world testing.

Changes

1. E2E Test Now Requires Real API Call ✅

Problem: Previous test passed without exercising API call forwarding through proxy

Solution:

  • Firmware now fails if no API call received within 60 seconds (was incorrectly passing)
  • run-e2e.ts actively triggers API call when device signals WAITING_FOR_API
  • Calls GET https://scriptproxy.percolate.one/api/<device_address>/e2eTest
  • Proxy forwards opcode 0x04 to device, device responds with opcode 0x08
  • Test reaches E2E:DONE PASS only after successful round-trip

Verified: Route /api/:Address/:method returns HTTP 201 per SmartLayerProxy routes.ts

2. ESP32 Automatic Reset on Port Open ✅

Problem: Runner often missed boot serial output, couldn't capture device address → test failed

Solution:

  • Runner pulses DTR/RTS when opening port: DTR=false, RTS=true for 200ms, then RTS=false
  • Standard esptool EN-pin reset sequence for ESP32 DevKit boards
  • Ensures all serial output captured from clean boot
  • Eliminates "Cannot trigger API call - device address not yet captured" error

3. Device Address Fallback Mechanisms ✅

Problem: If runner starts after device boot, device address missed from serial → test fails

Solutions:

  • CLI flag: --address <0xABCD...> to pre-configure address
  • Telemetry API fallback: Fetches recent device connections if address missed and TELEMETRY_API_KEY set
  • Case-insensitive parsing: Accepts 0x prefix or without, normalizes to lowercase

Usage:

npx tsx run-e2e.ts COM15 --address 0x123...
npx tsx run-e2e.ts COM3 --timeout 180000

4. Git Version Dirty Detection Fix ✅

Problem: Version built as e2e-<sha>-dirty immediately after clean git reset --hard

Root Cause: Build creates untracked files (.pio/, node_modules/), git status --porcelain reported them as changes

Solution:

  • Uses git diff --quiet HEAD instead of git status --porcelain
  • Ignores untracked files (only checks tracked file modifications)
  • Now produces clean e2e-<sha> after build

Verified: e2e-094bb44 (clean) after full rebuild

Expected Test Sequence

E2E:START
E2E:FW_VERSION=e2e-094bb44
E2E:KEYID=OK
E2E:WIFI=OK
E2E:DEVICE_ADDRESS="0x..."
E2E:LOGIN=OK opcode=0x09
E2E:DIAG_SENT opcode=0x0A
E2E:KEEPALIVE count=1-3
E2E:WAITING_FOR_API
  → Runner: GET https://scriptproxy.percolate.one/api/<address>/e2eTest
  → Proxy: Forward opcode 0x04 to device
  → Device: Respond opcode 0x08 to proxy
E2E:API_CALL name="e2eTest" count=1
E2E:DONE PASS time_ms=45000

Build Status

  • ✅ test/hardware/proxy_e2e: Compiles cleanly (72.5% flash)
  • ✅ Git version: e2e-094bb44 (clean, no false dirty flag)
  • ✅ All changes tested on real ESP32 hardware (COM15 on Windows)

Testing

Hardware Requirements

  1. ESP32 pre-provisioned with Web3E-Setup-Firmware (KeyID + WiFi networks)
  2. USB connection for serial monitor

Run Test

cd test/hardware/proxy_e2e

# Flash firmware
pio run -t upload --upload-port COM15

# Run test (auto-resets ESP32, triggers API call)
npx tsx run-e2e.ts COM15 180000

# Or with address fallback:
npx tsx run-e2e.ts COM15 --address 0xABCD... --timeout 180000

Proxy Requirements

Uses public proxy at https://scriptproxy.percolate.one:

  • ✅ HTTP GET /api/<address>/<method>?param=value
  • ✅ Forwards as opcode 0x04 to TCP-connected device
  • ✅ Returns device's opcode 0x08 response as HTTP 201
  • ✅ No authentication required for basic API forwarding

Documentation

  • Updated README with reset behavior, --address flag, and usage examples
  • Added telemetry fallback explanation
  • Documented complete test sequence with API trigger step
Open in Web Open in Cursor 

cursoragent and others added 2 commits November 17, 2026 02:04
1. git_version.py improvements:
   - Reliably produces e2e-<short-sha>[-dirty] even from detached HEAD
   - Uses PROJECT_DIR with __file__ fallback (handles SCons exec context)
   - Checks for git availability before attempting commands
   - Only falls back to 'unknown' if git truly unavailable
   - Ensures version <=32 ASCII chars

2. E2E test completes with real API call:
   - Firmware now FAILs if no API call received (was incorrectly passing)
   - run-e2e.ts actively triggers API call when device signals WAITING_FOR_API
   - Calls https://scriptproxy.percolate.one/api/<address>/e2eTest
   - Proxy forwards opcode 0x04 to device, device responds with 0x08
   - Test reaches E2E:DONE PASS after successful API round-trip

3. Documentation updated:
   - README now documents the complete sequence including API trigger
   - Added WAITING_FOR_API and API_CALLS_RECEIVED to message table
   - Notes that test fails without API call (tests full e2e flow)

Expected serial sequence:
START → FW_VERSION → KEYID → WIFI → LOGIN(0x09) → DIAG(0x0A) →
KEEPALIVE×3 → WAITING_FOR_API → API_CALL → DONE PASS

Runner command: npx tsx run-e2e.ts <serial-port>

Co-authored-by: James Brown <JamesSmartCell@users.noreply.github.com>
…it version

1. ESP32 automatic reset on port open:
   - Pulses DTR=false, RTS=true for 200ms, then RTS=false
   - Standard esptool EN-pin reset for ESP32 DevKit boards
   - Ensures runner captures all serial output from boot
   - Fixes 'Cannot trigger API call - device address not yet captured'

2. Device address fallback mechanisms:
   - Added --address flag: npx tsx run-e2e.ts COM15 --address 0x123...
   - Falls back to telemetry API if address missed from serial
   - Parses addresses case-insensitively (0x or without prefix)
   - Prevents test failure when serial buffer starts mid-boot

3. Git version dirty detection fix:
   - Uses 'git diff --quiet HEAD' instead of 'git status --porcelain'
   - Ignores untracked files (.pio/, node_modules/, build artifacts)
   - Fixes false 'dirty' flag after clean build
   - Now produces clean e2e-<sha> instead of e2e-<sha>-dirty

4. Verified proxy API route:
   - Confirmed route is /api/:Address/:method (status 201 on success)
   - Matches SmartLayerProxy implementation in routes.ts
   - handleApiCall forwards opcode 0x04 to TCP device

Usage: npx tsx run-e2e.ts COM15 180000
  npx tsx run-e2e.ts COM3 --address 0xABCD... --timeout 180000
Co-authored-by: James Brown <JamesSmartCell@users.noreply.github.com>
@JamesSmartCell
JamesSmartCell merged commit f3697cd into master Nov 17, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants