Repository navigation
Add authenticated firmware version reporting and WiFi diagnostics to TCP bridge - #37
Merged
Merged
Conversation
- Add TcpBridge::setFirmwareVersion() API (max 32 bytes ASCII) - Support compile-time default from FW_VERSION build flag - Introduce opcode 0x09 for authenticated firmware version reporting - Legacy opcode 0x07 preserved when no version is set (backward compatible) - Opcode 0x09 wire format: [opcode][20-byte address][65-byte signature][1-byte versionLen][version bytes] - Signature computed over keccak256(challenge || versionLen || version) - Document TCP Bridge protocol and wire formats in README - Update Wallet Bridge 1 example to demonstrate firmware version usage Co-authored-by: James Brown <JamesSmartCell@users.noreply.github.com>
Explicitly document that older firmware must not break and servers must accept both opcode 0x07 (no version) and 0x09 (with version). Co-authored-by: James Brown <JamesSmartCell@users.noreply.github.com>
Features: - WiFi watchdog: configurable timeout (default 30s), cycles through networks up to 3 times, reboots if no connection after all attempts - Diagnostics tracking: reset reason, boot count since last login, WiFi attempts, connect time, network index, failure stage, disconnect reason - NVS storage: survives reboots, does not overlap KeyID/EEPROM - Automatic reporting: sends diagnostics (opcode 0x0A) after successful TCP bridge login, then resets counters Wire format (opcode 0x0A, 14 bytes): [opcode][resetReason][bootCount(2)][wifiAttempts(2)][connectTimeMs(4)] [networkIndex][lastFailureStage][lastDisconnectReason][reserved] All fields use big-endian byte order for multi-byte integers. Backward compatible: - Old firmware: no diagnostics sent (fully compatible) - New firmware: sends opcode 0x0A after login - Old servers: unknown opcode safely ignored (TCP protocol extensible) - New servers: parse and store diagnostics for monitoring Comprehensive documentation added to README with field specifications, reset reason codes, failure stage codes, and server implementation guide. Co-authored-by: James Brown <JamesSmartCell@users.noreply.github.com>
cursor Bot
pushed a commit
to JamesSmartCell/SmartLayerProxy
that referenced
this pull request
Nov 17, 2026
Updates to match AlphaWallet/Web3E#37 exact wire formats: Opcode 0x09 (auth with version): - Wire format: [addr20][sig65][versionLen1 (0-32)][ASCII version] - Signature over: keccak256(challenge || versionLen || version), no prefix - Already correctly implemented, no changes needed Opcode 0x0A (WiFi diagnostics) - NEW: - 14 bytes total, big-endian: [0]=0x0A opcode [1]=resetReason (esp_reset_reason_t) [2-3]=bootCount uint16 [4-5]=wifiAttempts uint16 [6-9]=connectTimeMs uint32 [10]=networkIndex [11]=lastFailureStage (0 none,1 assoc,2 auth,3 dhcp,4 dns,5 tls,6 proxy_connect) [12]=lastDisconnectReason (wifi_err_reason_t) [13]=reserved - Sent once after successful login by authenticated device - Uses readUInt16BE/readUInt32BE for proper big-endian parsing - Decoder functions for ESP reset reasons and WiFi error codes - Stores in device_diagnostics with decoded human-readable strings Backward Compatibility Analysis: - Documented master branch behavior with unknown opcodes - Master has NO default case in switch statement - Unknown opcodes fall through silently without dropping connection - TCP framing robust: each data event = one message, buffer resets after - New firmware safe with old proxy: 0x09/0x0A silently ignored - Old firmware safe with new proxy: 0x07 still fully supported Database Schema: - Removed ssidHash field (not in Web3E format) - Added wifiDisconnectReason field - All fields properly decoded to human-readable names Tests: - 32 new WiFi diagnostics tests - Covers big-endian parsing, ESP reason decoding, all failure stages - All 149 tests passing Documentation: - docs/unknown-opcode-behavior.md explains master's silent ignore behavior - Confirms deployment strategy: proxy first, then firmware Co-authored-by: James Brown <JamesSmartCell@users.noreply.github.com>
Doc fixes:
- Correct esp_reset_reason_t values (0-10, per ESP-IDF)
- Clarify wifi_err_reason_t uses 200+ codes (BEACON_TIMEOUT, etc.)
WifiStore (src/WifiStore.{h,cpp}):
- Read-only implementation matching Web3E-Setup-Firmware format exactly
- EEPROM layout: offset 33, magic WIFI, version 1, records, terminator, CRC32
- Validates magic, version, and CRC32 (little-endian)
- Does NOT overlap KeyID storage (bytes 0-32)
Hardware E2E test (test/hardware/proxy_e2e/):
- Standalone PlatformIO project depending on local Web3E via symlink
- Firmware (src/main.cpp):
* Reads pre-provisioned KeyID from EEPROM (never creates/overwrites)
* Reads WiFi networks from WifiStore EEPROM block
* Connects to scriptproxy.percolate.one:8082
* Exercises: 0x09 login, 0x0A diagnostics, 0x06 keep-alives, 0x04 API calls
* Prints machine-parseable E2E: lines at 115200 baud
* FW_VERSION set via build flag (e2e-<git-sha>)
- Runner (run-e2e.ts):
* TypeScript/Node test harness
* Monitors serial output, parses E2E protocol
* Verifies SmartLayerProxy telemetry API (firmwareVersion, diagnostics)
* Prints PASS/FAIL summary, exits 0/1 for CI
- Comprehensive README with flash commands, serial spec, runner usage
Build: pio run in test/hardware/proxy_e2e/
Flash: pio run -t upload --upload-port COM3
Test: npm test COM3 (requires device pre-provisioned via Web3E-Setup-Firmware)
Co-authored-by: James Brown <JamesSmartCell@users.noreply.github.com>
Problem (arduino-esp32 3.x):
- KeyID constructor calls EEPROM.begin(33)
- WifiStore reader calls EEPROM.begin(1024)
- EEPROMClass::begin() TRUNCATES NVS blob when size < existing
- KeyID running first wipes WifiStore at offset 33+ every boot
- Observed as CRC mismatch on real hardware
Root cause: Each component called EEPROM.begin() with different sizes,
causing NVS truncation and data loss.
Solution:
- New header: src/Web3EEeprom.h defines WEB3E_EEPROM_SIZE (1024 bytes)
- Overridable via build flag: -DWEB3E_EEPROM_SIZE=2048
- KeyID and WifiStore both use WEB3E_EEPROM_SIZE
- Minimum 828 bytes enforced at compile time
- Layout unchanged: KeyID at 0-32, WifiStore at 33+
Changes:
- src/Web3EEeprom.h: Shared EEPROM size constant with documentation
- src/KeyID.{h,cpp}: Use WEB3E_EEPROM_SIZE, log size on init
- src/WifiStore.{h,cpp}: Use WEB3E_EEPROM_SIZE, log size on init
- test/hardware/proxy_e2e/src/main.cpp: Print E2E:EEPROM_SIZE=<size>
- README.md: Document bug, fix, layout, and override mechanism
- test/hardware/proxy_e2e/README.md: Document EEPROM size output
Testing:
- E2E test now prints opened EEPROM size for verification
- Existing provisioned devices preserved (layout unchanged)
- Prevents future truncation by enforcing single size constant
Co-authored-by: James Brown <JamesSmartCell@users.noreply.github.com>
Hardware validation on 0350646 revealed DNS failure with old domain. BREAKING CHANGES: - Default proxy: scriptproxy.percolate.one:8083 (was: smarttokenlabs.com:8003) - Old smarttokenlabs.com domain NO LONGER RESOLVES - Stock Web3E 1.45 and earlier will fail DNS lookup - GarageDoor and production deployments MUST update or configure custom proxy TCP Bridge changes: - Default host: scriptproxy.percolate.one (port 8083) - New method: setProxy(host, port) for runtime configuration - Compile-time overrides: WEB3E_PROXY_HOST, WEB3E_PROXY_PORT - Also honors PROXY_HOST/PROXY_PORT (e.g. from e2e test) - Logs configured proxy on init: 'TCP Bridge: host:port' UDP Bridge changes: - Default host: scriptproxy.percolate.one (port 8083, per SmartLayerProxy) - Fixed to use serverName member (was using stale hostName constant) - Compile-time overrides: WEB3E_PROXY_HOST, WEB3E_PROXY_PORT - Logs configured proxy on init: 'UDP Bridge: host:port' E2E test fixes: - Use port 8083 (matches Rob's working GarageDoor) - Fix git_version.py to properly override FW_VERSION (was 'e2e-esp32dev') - Now correctly generates 'e2e-<short-sha>' from git repo root Documentation: - New CHANGELOG.md with full breaking change details - README updated with migration guide and override examples - SmartLayerProxy GitHub repo link corrected (TypeScript implementation) Hardware test results (0350646): ✅ EEPROM fix works (size 1024, KeyID recovered, WifiStore read 1 network) ✅ WiFi connected in 1507ms ❌ TCP connect failed: DNS for old smarttokenlabs.com domain ✅ Fixed with new percolate.one default From Rob's network: TCP 8083/443 open, 8082/8003 closed on percolate.one Co-authored-by: James Brown <JamesSmartCell@users.noreply.github.com>
This was referenced Nov 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds three major features to Web3E's TCP bridge plus a critical EEPROM bug fix:
All features are backward compatible with existing servers.
🔥 CRITICAL: EEPROM Truncation Bug Fix
The Problem (Discovered on Real Hardware)
On arduino-esp32 3.x,
EEPROM.begin(size)uses NVS (Non-Volatile Storage) as a blob. When you callEEPROM.begin()with a smaller size than previously stored, it TRUNCATES the blob, destroying data at higher offsets.What was happening:
Observed symptom: WifiStore CRC validation failed after device reboot, even though provisioning succeeded.
The Fix
Introduced
WEB3E_EEPROM_SIZE(default 1024 bytes) used by ALL Web3E components:EEPROM Layout (Unchanged)
Overriding Size
Minimum: 828 bytes (enforced at compile time).
Files changed:
src/Web3EEeprom.h- New shared constant with documentationsrc/KeyID.{h,cpp}- UseWEB3E_EEPROM_SIZE, log size on initsrc/WifiStore.{h,cpp}- UseWEB3E_EEPROM_SIZE, log size on inittest/hardware/proxy_e2e/- E2E test printsE2E:EEPROM_SIZE=1024README.md- Document bug, fix, and override mechanismPart 1: Firmware Version Reporting
API
TcpBridge::setFirmwareVersion(const char* version)- Set firmware version (max 32 bytes ASCII)-DFW_VERSION="v1.2.3"build flagProtocol
[0x09][20-byte address][65-byte signature][1-byte versionLen][version bytes]keccak256(challenge || versionLen || version)Wire Format (Opcode 0x09)
Signature Preimage
Part 2: WiFi Connection Diagnostics
WiFi connection is the primary failure point for IoT devices. This feature adds comprehensive diagnostics tracking and watchdog protection.
Features
Watchdog Timer:
Diagnostics Tracking:
esp_reset_reason_t)wifi_err_reason_t)Storage:
Protocol
Wire Format (Opcode 0x0A)
Total packet size: 14 bytes
Reset Reason Codes (ESP-IDF
esp_reset_reason_t):0: ESP_RST_UNKNOWN1: ESP_RST_POWERON2: ESP_RST_EXT3: ESP_RST_SW4: ESP_RST_PANIC5: ESP_RST_INT_WDT6: ESP_RST_TASK_WDT7: ESP_RST_WDT8: ESP_RST_DEEPSLEEP9: ESP_RST_BROWNOUT10: ESP_RST_SDIOFailure Stage Codes:
0x00: None0x01: Association failed0x02: Authentication failed0x03: DHCP failed0x04: DNS failed0x05: TLS failed0x06: Proxy connection failedWiFi Disconnect Reason Codes (
wifi_err_reason_t):200: WIFI_REASON_BEACON_TIMEOUT201: WIFI_REASON_NO_AP_FOUND202: WIFI_REASON_AUTH_FAIL203: WIFI_REASON_ASSOC_FAIL204: WIFI_REASON_HANDSHAKE_TIMEOUTPart 3: WifiStore Reader
Reads WiFi credentials from EEPROM in Web3E-Setup-Firmware format.
EEPROM Layout
WifiStore Format
API
Part 4: Hardware End-to-End Test
Comprehensive hardware test firmware in
test/hardware/proxy_e2e/that exercises the full TCP bridge protocol.Test Firmware Features
E2E:protocol lines at 115200 baude2e-<git-sha>automaticallyE2E:EEPROM_SIZE=1024to verify fixTypeScript Test Runner
Build & Run
Serial Protocol Example
Backward Compatibility
Firmware Version (Opcode 0x09):
0x07(no version) and0x09(with version)0x070x090x07work with legacy devices0x07is byte-for-byte identical to original implementationWiFi Diagnostics (Opcode 0x0A):
0x0Aafter successful loginWifiStore:
EEPROM Size Fix:
WEB3E_EEPROM_SIZEto smaller value will truncate - always use same or largerUsage
Firmware Version:
WiFi Diagnostics:
WifiStore:
Custom EEPROM Size:
Companion PR Required
SmartLayerProxy (https://github.com/JamesSmartCell/SmartLayerProxy, agent bc-d379e7ba) needs updates:
For Opcode 0x09 (Firmware Version):
0x09insrc/service/ASyncTCPService.tskeccak256(challenge || versionLen || version)insrc/crypto/signature.ts0x07for legacy devices (critical!)For Opcode 0x0A (WiFi Diagnostics):
0x0A(14-byte packet)GET /api/telemetry/feed?deviceAddress=0x...Documentation