v1.7.0 - RX Packet Filtering & External Antenna Support + Debug Mode + Unified RX Architecture

[MrAlders0n]

Major Features & Improvements

Unified RX Event Handler Architecture

• Refactored RX packet handling into single unified listener (handleUnifiedRxLogEvent())
• Always-on listener started at connection, handles ALL incoming packets (no header filtering at entry point)
• Two-stage routing: TX echo tracking (6s window) → passive RX logging (when wardriving active)
• Consolidated handleTxLogging() and handleRxLogging() under unified handler
• Header filtering moved inside handleTxLogging() for echo detection (only GroupText 0x15 packets can be echoes)
• Eliminated duplicate LogRxData event handlers, single source of truth for packet metadata parsing
• parseRxPacketMetadata() extracts headers/paths once, reused by both TX and RX flows

RX Packet Filtering System

• Implemented comprehensive packet validation before logging/API submission
• Filters by path length (≤9 hops), packet type (ADVERT/GRP_TXT only), channel hash validation
• Validates message printability (≥80% threshold) and strict ASCII for ADVERT names
• Tracks dropped packets with detailed debug logging and UI counter ("X observations, Y dropped")
• Configurable thresholds: MAX_RX_PATH_LENGTH, RX_ALLOWED_CHANNELS, RX_PRINTABLE_THRESHOLD

External Antenna Configuration

• Added required "External Antenna" Yes/No setting (alongside Radio Power)
• Both settings locked after connection to prevent accidental changes during wardrive
• Settings unlock automatically on disconnect
• Visual feedback (greyed out, no hover) when locked
• external_antenna field added to all API payloads (TX and RX)

RX Auto Mode (Future Feature)

• Added RX Auto button for passive-only wardriving mode (currently disabled)
• Button permanently disabled with tooltip: "RX Auto temporarily disabled - backend API not ready"
• Infrastructure complete: startRxAuto() / stopRxAuto() functions, wake lock management
• When enabled: monitors all incoming packets, logs RX observations, queues for API
• Lower power consumption than TX/RX Auto (no mesh transmissions)
• Will be activated once backend API endpoint is ready

Debug Mode via Backend API

• MeshMapper API can now enable debug mode per device via capacity check response
• When debug_mode=1 returned by API, raw packet data is included in all API submissions
• Debug data includes: raw packet hex, parsed headers, path bytes, SNR/RSSI, repeater IDs
• Applies to both TX and RX wardrive data for comprehensive backend troubleshooting
• Debug mode automatically cleared on disconnect

UI/UX Enhancements

• RX Log now displays "X observations, Y dropped" to show filter effectiveness
• Drop counter increments for packets failing validation (path length, unknown channels, corrupted data)
• Both Radio Power and External Antenna selections required before Connect button enables
• Connect button shows specific error messages: "Select radio power to connect", "Select external antenna to connect", or "Select radio power and external antenna to connect"
• Settings remain editable while disconnected, locked during active session

API Queue Improvements

• Disconnect sequence now waits for pending background API posts before releasing capacity slot
• Prevents "missing session_id" errors from delayed posts firing after disconnect
• Tracks pending promises in state.pendingApiPosts[] array
• Clean shutdown: pending posts → flush queue → release capacity → cleanup
• Improved error handling for slot revocation and capacity denial

Channel Configuration

• Expanded RX allowed channels: #wardriving, #public, #testing, #ottawa
• Pre-computed channel hashes/keys at startup for performance (RX_CHANNEL_MAP)
• O(1) lookup for channel validation during packet filtering

Testing Infrastructure

• Added test_single_packet.js for standalone packet validation testing
• Supports decryption, printability checks, and filter logic validation
• Excluded from git via .gitignore (along with packet.json, package.json, package-lock.json test data)
• Uses actual crypto libraries (aes-js) for realistic testing

Technical Changes

Validation Functions

• validateRxPacket(): Main filter orchestrator with detailed debug output (logs raw hex, headers, validation steps)
• parseAdvertName(): Extracts and validates ADVERT name field
• isStrictAscii(): Checks for ASCII-only characters (32-126)
• getPrintableRatio(): Calculates printable character percentage

State Management

• Added rxLogState.dropCount to track filtered packets
• state.pendingApiPosts[] array for disconnect coordination
• getExternalAntennaSetting() helper for antenna configuration
• state.debugMode flag tracks API-controlled debug state
• state.tempTxRepeaterData stores repeater metadata for debug payloads
• state.rxTracking.isListening - TRUE when unified listener active (always on when connected)
• state.rxTracking.isWardriving - TRUE when TX/RX Auto OR RX Auto enabled (controls logging)

Settings Lock/Unlock

• lockWardriveSettings(): Disables power/antenna inputs with visual feedback (opacity 0.5, pointer-events-none)
• unlockWardriveSettings(): Re-enables inputs and restores styling
• Applied on connect/disconnect lifecycle events

Debug Data Building

• buildDebugData(): Constructs debug payload with raw packet, parsed fields, and metadata
• Includes: raw packet hex, SNR/RSSI, parsed header, path bytes, encrypted payload, repeater ID
• Conditionally added to API payloads when state.debugMode === true

Bug Fixes

• Fixed race condition where API posts could fire after session_id cleared
• Corrected packet validation to use actual parsed path bytes (not metadata references)
• Improved GPS age updater cleanup on disconnect
• Fixed inline style opacity for locked settings (higher specificity than Tailwind classes)

Breaking Changes

None - all changes are additive or internal implementation improvements.

[Copilot]

Pull request overview

This is a major release (v1.7.0) implementing three significant architectural improvements: unified RX packet parsing, comprehensive TX/RX naming standardization, and RX Auto mode infrastructure. The PR adds packet filtering, external antenna configuration, and API-controlled debug mode.

Key Changes:

• Unified RX parsing architecture with single metadata extraction point
• Complete naming standardization from "session log"/"auto ping" to "TX log"/"TX/RX Auto"
• RX Auto mode infrastructure (currently disabled awaiting backend API)
• Comprehensive RX packet filtering with validation thresholds
• External antenna configuration requirement added to settings
• API-controlled debug mode for detailed packet inspection

Reviewed changes

Copilot reviewed 13 out of 16 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
content/wardrive.js	Core refactor: unified RX parsing, TX/RX naming standardization, RX Auto mode, packet filtering, debug mode, external antenna support
index.html	UI updates: renamed TX log elements, added external antenna selector, added RX Auto button
content/style.css	Updated CSS comments for TX log naming
docs/*.md	Updated documentation for TX/RX terminology and RX Auto workflow
package.json, package-lock.json	Deleted (moved to .gitignore for local dev only)
.gitignore	Added package files and test data exclusions
.github/copilot-instructions.md	New comprehensive AI agent instructions file
README.md	Version bump to 1.7.0
CHANGES_SUMMARY.md	Deleted (outdated historical document)