DIGI Detection Node 2.4Ghz WiFi/BLE firmware. Standalone or for use in conjunction with the AntiHunter Command Center

1. Firmware Overview
2. Primary Detection Modes
3. System Architecture
4. Secure Data Destruction
5. RF Configuration
6. Hardware Requirements
7. Getting Started
   • Quick Flasher
   • Development Setup
8. Mesh Command Reference
9. API Reference
10. Credits
11. Terms & Disclaimer

AntiHunter is a low-cost, open-source distributed perimeter defense system for wireless network security and operational awareness. It enables comprehensive monitoring and protection of wireless environments, transforming spectrum activity into actionable security intelligence.

Built on the ESP32-S3 platform with mesh networking, AntiHunter creates a scalable sensor network for real-time threat detection, device mapping, and perimeter security. The system combines WiFi/BLE scanning, GPS positioning, environmental sensors, and distributed coordination to provide a digital and physical "tripwire".

Maintain a watchlist of target MAC addresses (full 6-byte) or OUI prefixes (first 3-byte vendor IDs). AntiHunter systematically sweeps designated WiFi channels and BLE frequencies, providing immediate alerts and detailed logging when targets are detected.

Features:

• Target Monitoring: Track specific devices by MAC address or vendor OUI prefix
• Dual Protocol Scanning: WiFi-only, BLE-only, or combined WiFi+BLE modes
• Global Allowlist: User configurable, applies to all scans
• Logging: Records RSSI, channel, GPS coordinates, and device names to SD card
• Real-time Alerts: Immediate notifications via web interface, command center and mesh network

Experimental Feature

Triangulation coordinates multiple AntiHunter nodes across a mesh network to achieve precise location tracking of target devices. Each node simultaneously scans for the specified target, recording signal strength (RSSI) and GPS coordinates. Detection data is aggregated and forwarded over mesh to the AP and command center for RSSI-based trilateration processing.

Note: The bill of materials antennas/MCUs will be close. It is tuned for the offical PCB power, so adjustment may be needed in the constants of triangulation.cpp

Key Capabilities:

• Multi-node Coordination: Distributed scanning across mesh network nodes
• GPS Integration: Each node contributes location data for accurate positioning
• RSSI-Based Trilateration:
  • Method: RSSI-based weighted trilateration + Kalman filtering
  • Metrics: Average HDOP, GPS Coordinates, Confidence, Est. Uncertainty (m), GPS Quality
  • Output: Google Maps link sent over mesh with details

Experimental T114 Support:

Small buffer and slow speed causes some latency. Using a Heltec v3 is recommended but not required.

• WiFi Urban: 30-50m | Rural: 80-150m LoS
• BLE Urban: 10-30m | Rural: 40-100m LoS
• Wall Attenuation: -20 to -30 dB urban, -10 to -15 dB drywall

Path loss model: distance = 10^((RSSI0 - RSSI) / (10 * n))

Note: Values calibrated for 5-8 dBi RX antenna gain. BLE has higher path loss exponent due to lower TX power and increased multipath susceptibility. Auto-calibration refines values during triangulation operations.

• Captures all WiFi and Bluetooth devices in range
• Records MAC addresses, SSIDs, signal strength, names and channels
• Provides complete 2.4GHz wireless spectrum visibility

• Two-phase scanning: establishes baseline, then monitors for anomalies
• Detects new devices, disappeared/reappeared devices, significant RSSI changes
• Configurable RAM cache (200-500 devices) and SD storage (1K-100K devices). Defaults to 1500 devices if no SD card.
• Persistent storage with automatic tiering, survives reboots
• Real-time mesh alerts with GPS coordinates and anomaly reasons
• Use cases: distributed "trail cam" for poachers/trespassers, perimeter security, surveillance detection, threat identification

• WiFi deauth/disassoc attack sniffer with frame filtering and real-time detection
• Integration with randomization tracking for source identification

• Identifies drones broadcasting Remote ID (FAA/EASA compliant)
• Supports ODID/ASTM F3411 protocols (NAN action frames and beacon frames)
• Detects French drone ID format (OUI 0x6a5c35)
• Extracts UAV ID, pilot location, and flight telemetry data
• Sends immediate mesh alerts with drone detection data, logs to SD card and two API endpoints for data

Experimental Feature

• Traces device identities across randomized MAC addresses using behavioral signatures
• IE fingerprinting, channel sequencing, timing analysis, RSSI patterns, and sequence number correlation
• Assigns unique identity IDs (format: T-XXXX) with persistent SD storage
• Supports up to 30 simultaneous device identities with up to 50 linked MACs each
• Dual signature support (full and minimal IE patterns)
• Confidence-based linking with threshold adaptation
• Detects global MAC leaks and WiFi-BLE device correlation

• Perimeter security and intrusion detection
• WiFi penetration testing, security auditing, and MAC randomization analysis
• Device fingerprinting and persistent identification across randomization
• Counter-UAV operations and airspace awareness
• Event security and monitoring
• Red team detection and defensive operations
• Wireless threat hunting, forensics, and privacy assessments

• Interface: UART2 (RX=GPIO44, TX=GPIO43) at 9600 baud using TinyGPS++
• Functionality: Parses NMEA sentences for location, altitude, and satellite data
• Web Interface: Real-time GPS status and fix quality
• API Endpoint: /gps returns current latitude/longitude coordinates
• Integration: All detection events include GPS coordinates when available

• Interface: SPI
• Storage: Logs to /antihunter.log with timestamps, detection types, and metadata
• Format: Structured entries including MAC addresses, RSSI, GPS data, and timestamps
• Diagnostics: Web interface shows storage status and usage stats

• Sensor: SW-420 vibration sensor
• Detection: Interrupt-driven monitoring with 3-second rate limiting
• Alerts: Mesh network notifications with GPS coordinates and timestamps
• Format: NODE_ABC: VIBRATION: Movement detected at HH:MM:SS GPS:lat,lon
• Status: Real-time sensor state displayed in diagnostics panel

• Module: DS3231 RTC via I2C
• Functionality: Accurate timekeeping during power outages and GPS synchronization
• Features: Automatic time sync from NTP on flash with fallback to system time and GPS, sync status monitoring & obedience/drift correction.
• Web Interface: Current time display and synchronization status
• Time Zone: All timestamps use UTC (Coordinated Universal Time)

AntiHunter includes tamper detection and emergency data wiping capabilities to protect data from unauthorized access

• Auto-erase on tampering: Configurable vibration detection triggers automatic data destruction
• Setup delay: Grace period after enabling auto-erase to complete deployment and walk away
• Manual secure wipe: Web interface for operator-initiated data destruction
• Remote force erase: Immediate mesh-commanded data destruction with token authentication
• Mesh integration: Real-time tamper alerts and erase status monitoring
• Token-based authentication: Time-limited tokens prevent unauthorized mesh erase commands

Configure auto-erase settings via the web interface:

• Setup delay: Grace period before auto-erase becomes active (30 seconds - 10 minutes)
• Vibrations required: Number of device movements to trigger (2-5)
• Detection window: Time frame for vibration detection (10-60 seconds)
• Erase delay: Countdown period before data destruction (10-300 seconds)
• Cooldown period: Minimum time between tamper attempts (5-60 minutes)

• Auto-erase is disabled by default for safety
• Setup delay prevents accidental triggering during deployment
• ERASE_FORCE requires device-generated authentication tokens that expire in 5 minutes
• Tokens are device-specific and generated via ERASE_REQUEST command on target device
• Overwrites SD buffer, erases all (including hidden) files and folders
• Creates a dummy IoT weather device config file for obfuscation

1. Enable auto-erase via web interface with appropriate setup delay
2. Configure detection thresholds based on deployment environment
3. Deploy device and walk away during setup period
4. Monitor mesh alerts for tamper detection events
5. For remote erase: Send @NODE ERASE_REQUEST to generate token, then use received token with @NODE ERASE_FORCE:<token>

Warning: Data destruction is permanent and irreversible. Configure thresholds carefully to prevent false triggers.

AntiHunter provides adjustable RF scan parameters to optimize detection performance for different operational scenarios.

• WiFi Channel Time: Duration per WiFi channel (50-300ms)
• WiFi Scan Interval: Time between WiFi scan cycles (1000-10000ms)
• BLE Scan Interval: Time between BLE scan cycles (1000-10000ms)
• BLE Scan Duration: Active BLE scanning duration per cycle (1000-5000ms)
• RSSI Threshold: Global signal strength filter in dBm (-100 to -10). Filters weak signals from general scans; triangulation operations exempt from filtering
• WiFi Channels: Comma-separated list (1,6,11) or range (1..14) of 2.4GHz channels. Default: 1,6,11 if not specified

Configure via web interface at http://192.168.4.1 or API endpoints (see API Reference below). All settings persist to NVS and SD card when available.

• Lower intervals: Faster detection, higher power consumption
• Higher intervals: Reduced power, may miss brief transmissions
• Channel time: Affects WiFi hop rate; shorter = faster coverage
• BLE duration: Longer improves discovery but reduces WiFi scan frequency
• RSSI threshold: Lower values (-100) capture distant/weak signals; higher (-60) focus on nearby devices. Triangulation exempt from filtering
• Channel selection: Use 1,6,11 for focused monitoring or 1..14 for comprehensive coverage

Adjust parameters based on deployment environment, power budget, target detection requirements, and regulatory constraints.

AntiHunter operates as a distributed sensor network where each node functions independently while contributing to the overall security picture. Nodes communicate via Meshtastic mesh networking, enabling:

• Scalable Coverage: Deploy multiple nodes to cover large areas
• Redundant Detection: Multiple nodes improve detection reliability
• Distributed Processing: Local decision-making with centralized coordination
• Resilient Communications: Mesh networking ensures connectivity in challenging environments

1. Local Detection: Each node performs independent WiFi/BLE scanning based on configured parameters
2. Target Identification: Matches detected devices against configured watchlists
3. Data Collection: Records detection metadata (RSSI, GPS, timestamp, etc.)
4. Mesh Coordination: Broadcasts alerts and status to other nodes and command center
5. Central Processing: Command center aggregates data for advanced analytics and visualization

While individual nodes provide standalone capability, the full system power comes from integration with a central command center that:

• Aggregates detection data from all nodes
• Provides real-time mapping and visualization
• Enables coordinated/scheduled response operations
• A lot more... stay tuned, public release soon.

PCBs and kits are in final production. Tindie link coming soon

• Find them in the hw folder here

• ESP32-S3 Development Board
  • Minimum 8MB flash memory required for reliable operation)
• Meshtastic Board Heltec v3.2 (recommended) or T114
  • Other alternatives can be found in the discussions
• GPS, SDHC, Vibration and RTC modules

• 1x Seeed Studio XIAO ESP32-S3
• 1x Heltec WiFi LoRa 32 V3.2 (Heltec T114 also compatible, V3.2 preferred)
• 1x ATGM336H GPS Module
• 1x Micro SD SDHC TF Card Adapter Reader Module with SPI
• 1x SD Card (Formatted FAT32, 16GB recommended)
• 1x SW-420 Vibration Sensor
• 1x DS3231 Real Time Clock Module
• 1x KSD9700 Normally Open Thermal Wire Sensor (30-40°C)
• 6x JST 2.54 2-Pin Terminals (2.0 JST can be used in place)
• 2x U.FL to SMA Pigtail Cable (SMA bulkhead, 10-20cm length)
• 1x 8dBi Antenna 2.4GHz (for WiFi/BLE)
• 1x 8dBi Antenna LoRa (region-dependent: 868MHz EU / 915MHz US / 923MHz Asia)
• 1x 30mm 5V Fan
• 1x 3 Pin Mini On/Off Switch

• XIAO ESP32S3 Pin Diagram

For rapid deployment without building from source, precompiled binaries are available.

# Download the script, erase and flash:
curl -fsSL -o flashAntihunter.sh https://raw.githubusercontent.com/lukeswitz/AntiHunter/main/Dist/flashAntihunter.sh

chmod +x flashAntihunter.sh

./flashAntihunter.sh

Headless Configuration (Optional):

Configuration on flash requires the bootloader and partitions files from Dist/ folder in the same directory.

# Run the flasher script with interactive NVS configuration (Headless Firmware)
./flashAntihunter.sh -c

Flashing Process:

1. Connect your ESP32-S3 board via USB
2. Run the flasher script and follow prompts
3. Device will reboot with AntiHunter firmware

Post-Flash Setup:

Full Firmware:

• Connect to Antihunter WiFi AP (password: antihunt3r123)
• Access web interface at http://192.168.4.1
• Configure RF settings, detection modes, and security parameters
• Change SSID and password in RF Settings panel

Headless Firmware:

• Use serial monitor or mesh commands (see Command Reference section)

For developers and advanced users:

Prerequisites:

• PlatformIO
• Git
• USB cable for programming and debugging
• Optional: Visual Studio Code with PlatformIO IDE extension

Repository Setup:

# Clone the AntiHunter repository
git clone https://github.com/lukeswitz/AntiHunter.git
cd AntiHunter

Firmware Flashing:

Option 1 - PlatformIO Command Line:

# Verify device detection
pio device list

# Upload full environment
pio run -e AntiHunter-full -t upload

# Upload headless environment  
pio run -e AntiHunter-headless -t upload

# Monitor with auto-config from platformio.ini
pio device monitor -e AntiHunter-full

# Erase + upload (clean deployment)
pio run -e AntiHunter-full -t erase -t upload

Option 2 - Using VS Code:

1. Select Environment: Click the environment selector in PlatformIO's status bar:

   • Choose AntiHunter-full for web interface version
   • Choose AntiHunter-headless for mesh-only version

2. Build & Upload: Click the "Upload" button (→) in the PlatformIO status bar

3. Monitor Output: Use the Serial Monitor to verify successful boot

Environment Notes:

• Full: Includes web server (ESPAsyncWebServer, AsyncTCP) for AP dashboard
• Headless: Minimal dependencies, ideal for distributed deployment and background operation

AntiHunter integrates with Meshtastic LoRa mesh networks via UART serial communication, creating a robust long-range sensor network.

• Extended Range: LoRa mesh extends detection beyond WiFi/Bluetooth range
• Node Coordination: Distributed scanning and data sharing across nodes
• Remote Control: Command and control via mesh messages
• Alert Propagation: Real-time threat notifications across the network
• Position Reporting: GPS coordinates included in all relevant alerts

• Connection: Mode: TEXTMSG;Speed: 115200 baud ;Pins 10 RX / 9 TX for T114 and 19 RX / 20 TX for the Heltec V3
• Protocol: Standard Meshtastic serial, public and encrypted channels (protobuf support in development)

• Alert Rate Limiting: 3-second intervals prevent mesh flooding, configurable.
• Node Identification: Each device uses a configurable Node ID for addressing.
• Broadcast Commands: @ALL commands coordinate multiple nodes
• Targeted Control: @AH01 commands address specific node AH01
• Status Reporting: Periodic heartbeats and operational status

AntiHunter is the result of collaborative development by security researchers, embedded systems engineers, and open-source contributors. Original concept and hardware design by @TheRealSirHaXalot.

Get involved. The project continues to evolve through community contributions. Contributions via pull requests, issue reports, and documentation improvements are welcome.

AntiHunter (AH) is provided for lawful, authorized use only—such as research, training, and security operations on systems and radio spectrum you own or have explicit written permission to assess. You are solely responsible for compliance with all applicable laws and policies, including privacy/data-protection (e.g., GDPR), radio/telecom regulations (LoRa ISM band limits, duty cycle), and export controls. Do not use AH to track, surveil, or target individuals, or to collect personal data without a valid legal basis and consent where required.

Authors and contributors are not liable for misuse, damages, or legal consequences arising from use of this project.
By using AHCC, you accept full responsibility for your actions and agree to indemnify the authors and contributors against any claims related to your use.
These tools are designed for ethical blue team use, such as securing events, auditing networks, or training exercises. To implement in code, ensure compliance with local laws (e.g., FCC regulations on transmissions) and pair with a directional antenna for enhanced accuracy.

THE SOFTWARE IN THIS REPOSITORY (“SOFTWARE”) IS PROVIDED “AS IS” AND “AS AVAILABLE,” WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, ACCURACY, OR RELIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL THE DEVELOPERS, MAINTAINERS, OR CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF OR OTHER DEALINGS IN THE SOFTWARE, INCLUDING WITHOUT LIMITATION ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR LOSS OF DATA, PROFITS, GOODWILL, OR BUSINESS INTERRUPTION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

YOU ALONE ARE RESPONSIBLE FOR COMPLYING WITH ALL APPLICABLE LAWS, REGULATIONS, AND THIRD-PARTY RIGHTS. NO ADVICE OR INFORMATION, WHETHER ORAL OR WRITTEN, OBTAINED FROM THE PROJECT OR THROUGH THE SOFTWARE, CREATES ANY WARRANTY OR OBLIGATION NOT EXPRESSLY STATED HEREIN. IF APPLICABLE LAW DOES NOT ALLOW THE EXCLUSION OF CERTAIN WARRANTIES OR LIMITATION OF LIABILITY, THE DEVELOPERS’, MAINTAINERS’, AND CONTRIBUTORS’ AGGREGATE LIABILITY SHALL NOT EXCEED THE GREATER OF: (A) THE AMOUNT YOU PAID (IF ANY) FOR THE COPY OF THE SOFTWARE THAT GAVE RISE TO THE CLAIM, OR (B) USD $0.

NOTWITHSTANDING ANYTHING TO THE CONTRARY, THE PROJECT MAINTAINERS SHALL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES ARISING FROM OR RELATED TO ANY THIRD-PARTY INTELLECTUAL PROPERTY CLAIMS, INCLUDING BUT NOT LIMITED TO ATTORNEYS' FEES, SETTLEMENT COSTS, OR INJUNCTIVE RELIEF.

BY USING THIS SOFTWARE, YOU ACKNOWLEDGE THE INHERENT RISKS ASSOCIATED WITH INTELLECTUAL PROPERTY COMPLIANCE AND ASSUME FULL RESPONSIBILITY FOR ENSURING YOUR USE COMPLIES WITH ALL APPLICABLE LAWS AND THIRD-PARTY RIGHTS.

BY ACCESSING, DOWNLOADING, INSTALLING, COMPILING, EXECUTING, OR OTHERWISE USING THE SOFTWARE, YOU ACCEPT THIS DISCLAIMER AND THESE LIMITATIONS OF LIABILITY.