Skip to content

Instantly share code, notes, and snippets.

@niradler

niradler/ESP32Marauder_guide.md

Created December 15, 2025 22:17
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save niradler/1ccdbc82217305516a157fc1af8803f6 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save niradler/1ccdbc82217305516a157fc1af8803f6 to your computer and use it in GitHub Desktop.
Download ZIP
ESP32 Marauder Pocket Guide
Raw
ESP32Marauder_guide.md

ESP32 Marauder Pocket Guide

TTGO T-Display - Complete Command Reference

Serial Setup: 115200 baud | Press Enter for prompt
No SD Card Required for most functions

📡 WiFi Commands

WiFi Scanning

scanap - Scan for access points (WiFi networks)
Used for: Finding nearby WiFi networks with SSID, MAC, channel, signal strength

scansta - Scan for stations (WiFi clients/devices)
Used for: Finding phones, laptops, IoT devices connected to WiFi

sniffbeacon - Sniff beacon frames from APs
Used for: Passive WiFi network discovery, analyzing AP broadcast info

sniffdeauth - Sniff deauthentication frames
Used for: Detecting WiFi jamming attacks, monitoring disconnections

sniffpmkid - Sniff PMKID handshakes for WPA cracking
Used for: Capturing WiFi password hashes for offline cracking (educational)

sniffpwn - Sniff for Pwnagotchi devices
Used for: Detecting nearby Pwnagotchi AI WiFi security tools

sniffesp - Sniff for other ESP32 Marauder devices
Used for: Finding other Marauders in the area

sniffraw - Raw WiFi packet capture
Used for: Low-level packet analysis, captures all WiFi traffic on channel

WiFi Information

list -a - List all scanned access points with index numbers
Used for: Viewing scan results to select targets

list -c - List all scanned clients/stations
Used for: Viewing connected devices to select for attacks

channel [1-14] - Set WiFi channel
Used for: Focusing on specific WiFi channel (1, 6, 11 most common)

clearlist -a - Clear access point list from memory
Used for: Freeing memory, starting fresh scan

clearlist -c - Clear client/station list
Used for: Freeing memory

select -a [index] or -a all - Select AP by index number
Used for: Choosing target network for attacks (e.g., select -a 0)

select -c [index] or -c all - Select client by index
Used for: Choosing target device for deauth (e.g., select -c 0)

WiFi Attacks ⚠️

LEGAL WARNING: Only on YOUR networks or with written permission!

attack -t deauth - Deauthentication attack
Targets: Selected CLIENT from selected AP (disconnect device)
Used for: Kicking specific device off specific network (needs AP + client selected)

attack -t beacon -r - Random beacon spam
Targets: Everyone nearby (creates fake WiFi networks)
Used for: Testing detection systems, creating fake SSIDs (no selection needed)

attack -t beacon -l - List beacon spam (needs SD + SSID list)
Targets: Everyone nearby
Used for: Broadcasting custom fake network names

attack -t beacon -ap - AP clone beacon spam
Targets: Everyone nearby
Used for: Cloning real APs to confuse clients (needs AP selected first)

attack -t probe - Probe request flood
Targets: All APs in range
Used for: Fake device search broadcasts

attack -t rickroll - Rick Roll beacon spam
Targets: Everyone nearby
Used for: Fun beacon spam with Rick Astley lyrics as SSIDs

stopscan - Stop any running scan or attack
Used for: Ending current operation

WiFi Network Management

join -s [ssid] -p [password] - Connect to WiFi network
Used for: Joining WiFi to use features like Evil Portal

ssid -a -n [name] - Add SSID to list
Used for: Adding custom network name to SSID list (for beacon attacks)

ssid -g [wordlist] - Generate SSIDs from wordlist
Used for: Creating SSID list from file on SD card

ssid -r - Remove SSID from list
Used for: Cleaning up SSID list

WiFi Advanced

sigmon -t [ap/sta] - Signal monitor for APs or stations
Used for: Tracking signal strength of specific device/network

packetcount - Show packet counts per channel
Used for: Finding busiest WiFi channels

pingscan - Scan for devices on connected network
Used for: Finding active IPs when connected to WiFi (needs join first)

wardrive - WiFi wardriving with GPS
Used for: Mapping WiFi networks with location data (needs GPS module)

evilportal -a - Evil portal captive portal attack
Targets: Devices connecting to fake AP
Used for: Creating fake login page (needs HTML file on SD, join network first)

📱 Bluetooth/BLE Commands

Bluetooth Scanning

sniffbt - Bluetooth/BLE scanner
Used for: Discovering nearby Bluetooth devices (phones, headphones, IoT)

btwardrive - Bluetooth wardriving with GPS
Used for: Mapping Bluetooth devices with location (needs GPS module)

Bluetooth Spam Attacks

Targets: Nearby Bluetooth devices (causes notification/pairing spam)

btspamall -t samsung - Samsung BLE spam
Used for: Fake Samsung device pairing notifications

btspamall -t apple or sourapple - Apple BLE spam (SwiftPair)
Used for: Fake AirPods/Apple device notifications

btspamall -t windows or swiftpair - Windows BLE spam
Used for: Fake Windows Swift Pair notifications

btspamall -t google - Google Fast Pair spam
Used for: Fake Google device pairing notifications

btspamall -t flipper - Flipper Zero BLE spam
Used for: Fake Flipper Zero advertisements

btspamall -t all - All BLE spam types at once
Used for: Maximum Bluetooth chaos

spoofat - Spoof Apple AirTag
Used for: Broadcasting fake AirTag to trigger Find My network

🛰️ GPS Commands

Note: Requires external GPS module (not included on TTGO T-Display)

gpsdata - Display current GPS information
Used for: Checking GPS lock status, coordinates, satellites

wardrive - WiFi wardriving with GPS logging
Used for: Mapping WiFi networks to SD card with coordinates

btwardrive - Bluetooth wardriving with GPS
Used for: Mapping Bluetooth devices with location data

📻 Sub-GHz/RF Commands

Note: Requires CC1101 module (not standard on TTGO T-Display)

ESP32 Marauder does NOT natively support:

  • ❌ IR (Infrared) commands
  • ❌ RF analysis beyond 433MHz CC1101 module
  • ❌ NRF24 (requires separate hardware mod)

If you have CC1101 module:

  • 433MHz scanning and transmission
  • Garage door, car key fob analysis
  • IoT device RF protocols

Check hardware: CC1101 support requires expansion board like:

  • Flipper Zero WiFi Dev Board with CC1101
  • DIY CC1101 module wired to ESP32

🎮 Device/System Commands

help - Show all commands
Used for: Getting command list

help [command] - Show help for specific command
Used for: Learning command syntax (e.g., help attack)

info - Display device information
Used for: Checking firmware version, hardware specs

settings - View/modify Marauder settings
Used for: Configuring device options

settings -s - Save settings to flash
Used for: Keeping configuration after reboot

led -r [0-255] -g [0-255] -b [0-255] - Control RGB LED
Used for: Setting LED color (e.g., led -r 255 -g 0 -b 0 = red)

reboot - Restart device
Used for: Rebooting Marauder

update -w - Web update firmware
Used for: Updating via WiFi OTA (needs WiFi connection)

💾 SD Card Commands

Note: Optional - most features work without SD card

save -a - Save AP list to SD
Used for: Backing up scan results

save -c - Save client list to SD
Used for: Backing up device list

save -ssid - Save SSID list to SD
Used for: Backing up custom network names

load -a - Load AP list from SD
Used for: Restoring previous scan

load -c - Load client list from SD
Used for: Restoring device list

load -ssid - Load SSID list from SD
Used for: Loading custom network names

SD card used for:

  • Saving PCAP files (packet captures)
  • Custom SSID lists for beacon attacks
  • Evil Portal HTML files
  • Firmware updates
  • Scan result logs

Quick Workflows

1. WiFi Reconnaissance (Safe)

scanap              # Find networks
list -a             # View results
scansta             # Find devices
list -c             # View clients

2. Deauth Attack (YOUR network only!)

scanap              # Find networks
list -a             # View with index
select -a 0         # Select your AP
scansta             # Find clients
list -c             # View with index
select -c 0         # Select your device
attack -t deauth    # Start attack
stopscan            # Stop

3. Beacon Spam Test

attack -t beacon -r     # Random fake networks
stopscan                # Stop

4. Bluetooth Spam

btspamall -t samsung    # Samsung spam
stopscan                # Stop

5. BLE Reconnaissance

sniffbt                 # Scan for BLE devices
list -b                 # View found devices
stopscan                # Stop

Supported Protocols by Domain

WiFi (2.4 GHz) ✅

  • Standards: 802.11 b/g/n
  • Frames: Beacon, Probe, Deauth, Auth, EAPOL
  • Encryption: Open, WEP, WPA/WPA2-PSK detection
  • Functions: Scanning, sniffing, injection, AP mode

Bluetooth ✅

  • Classic Bluetooth: Discovery, enumeration
  • BLE (Bluetooth Low Energy): Scanning, advertising, spam attacks
  • Protocols: GAP, GATT advertisements
  • Vendor Spam: Samsung, Apple, Google, Microsoft, Flipper

GPS (Optional) ✅

  • Protocol: NMEA 0183 over UART
  • Functions: Location, wardriving, coordinate logging
  • Requires: External GPS module (NEO-6M, NEO-7M, etc.)

Sub-GHz RF (Optional - CC1101) ⚠️

  • Frequency: 300-928 MHz (typically 433 MHz)
  • Functions: Raw capture, transmission, signal analysis
  • Protocols: ASK/OOK, FSK, MSK, GFSK
  • Requires: CC1101 transceiver module

NOT Supported ❌

  • IR (Infrared) - No IR transmitter/receiver on ESP32
  • NRF24 - Requires separate module
  • 5 GHz WiFi - ESP32 is 2.4 GHz only
  • Zigbee/Z-Wave - Different hardware needed
  • LoRa - Requires LoRa module

TTGO T-Display Specific

Built-in Features:

  • 2.4 GHz WiFi (802.11 b/g/n)
  • Bluetooth 4.2 + BLE
  • 1.14" TFT LCD screen (135x240)
  • Two buttons (GPIO 0 and GPIO 35)
  • USB-C port
  • 16MB Flash

NOT Included (needs mods):

  • SD card slot
  • GPS module
  • CC1101 RF module
  • External antenna (uses PCB antenna)

Power:

  • USB-C powered
  • Can add battery mod with JST connector

Command Cheat Sheet

SCAN:         scanap, scansta, sniffbeacon, sniffbt, sniffraw
LIST:         list -a, list -c
SELECT:       select -a [n], select -c [n]
ATTACK:       attack -t deauth, attack -t beacon -r
BLUETOOTH:    btspamall -t [type], sniffbt, spoofat
CHANNEL:      channel [1-14]
STOP:         stopscan
CLEAN:        clearlist -a, clearlist -c
GPS:          gpsdata, wardrive, btwardrive
NETWORK:      join, ssid, pingscan, evilportal
SYSTEM:       help, info, settings, led, reboot, update
SD:           save, load

Troubleshooting

No prompt? → Press Enter 2-3 times
Commands fail? → Check spelling, use help [command]
No results? → Try different channels with channel [n]
Memory full? → Use clearlist -a and clearlist -c
GPS not working? → TTGO T-Display needs external GPS module
RF not working? → TTGO T-Display needs CC1101 module added

Legal Notice ⚠️

Legal Uses Only: ✅ Your own networks
✅ Written permission
✅ Educational labs
✅ Security research on owned devices

Illegal Uses: ❌ Others' networks
❌ Public WiFi disruption
❌ Unauthorized access
❌ Malicious attacks

Penalties: Fines, criminal charges, imprisonment

Use responsibly and legally! 🔒

For latest commands: help or check https://github.com/justcallmekoko/ESP32Marauder/wiki

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment