Getting Started
Quick Start
After flashing PenESP to your ESP32, connect via serial terminal at 115200 baud. Type help to see the full command menu.
Serial Connection
PenESP uses a serial command interface for all operations. You can connect using:
- Web Serial Terminal: 0Xploit.net/serial
- Arduino IDE Serial Monitor (115200 baud)
- PuTTY, screen, minicom, or any serial terminal
Command Structure
Commands are simple text strings sent over serial. Most commands are executed immediately, while some require additional input prompts. To stop any running operation, use the stop command.
WiFi Commands
wifi_scan
WiFi
Scans for nearby WiFi networks and displays all available access points with details including SSID, BSSID, channel, RSSI, and encryption type.
Usage: wifi_scan
ssid_info
WiFi
Get detailed information about a specific network from the last scan. You'll be prompted to enter the network number.
Usage: ssid_info
Then enter: [network number from scan]
beacon_funny
WiFi
Broadcasts beacon frames with humorous SSID names. Creates fake access points with names like "FBI Surveillance Van", "Pretty Fly for a WiFi", etc.
Usage: beacon_funny
beacon_random
WiFi
Generates and broadcasts beacon frames with randomly generated SSID names.
Usage: beacon_random
beacon_custom
WiFi
Broadcasts beacon frames with your custom SSID names. You'll be prompted to enter custom SSIDs.
Usage: beacon_custom
deauth_set
WiFi
Advanced
Sets the target access point for deauthentication attacks. You must run wifi_scan first to identify targets.
Usage: deauth_set
Then enter: [target SSID name]
deauth_send
WiFi
Advanced
Sends deauthentication packets to the target set with deauth_set. You'll be prompted for the number of packets to send.
Usage: deauth_send
Then enter: [number of packets, e.g., 100]
sniff
WiFi
Advanced
Starts promiscuous mode packet sniffing on a specified channel. Captures and displays 802.11 management frames with addresses and metadata.
Usage: sniff
Then enter: [channel 1-13]
ap_start
WiFi
Starts the ESP32's built-in access point with the SSID "PenESP-AP". Useful for creating a testing environment or captive portal.
Usage: ap_start
ap_stop
WiFi
Stops the ESP32 access point if it's currently running.
Usage: ap_stop
Legal Warning
Some items may be illegal in your jurisdiction. Only use these features on hardware you own or have explicit permission to test.
BLE Commands
BLE Support
BLE commands require Bluetooth to be enabled in your ESP32. If you see "BLE not enabled", you'll need to try a BLE-compatible board.
ble_scan
BLE
Scans for nearby Bluetooth Low Energy devices and displays device names, addresses, RSSI values, and manufacturer data.
Usage: ble_scan
Then enter: [scan duration in seconds]
ble_fingerprint
BLE
Advanced BLE scanning that identifies device types and manufacturers from advertisement data. Can detect Apple, Microsoft, Samsung, and Google devices.
Usage: ble_fingerprint
spam_ios
BLE
Broadcasts BLE advertisement packets mimicking various Apple devices including AirPods Pro, AirPods Max, AirTags, and Beats products. Used to test iOS device reactions.
Usage: spam_ios
spam_android
BLE
Broadcasts Google Fast Pair advertisements mimicking devices like Pixel Buds, Sony WH-1000XM4, JBL, and Bose headphones.
Usage: spam_android
spam_samsung
BLE
Broadcasts Samsung Fast Pair advertisements for Galaxy Buds, Galaxy Watches, and other Samsung devices.
Usage: spam_samsung
spam_windows
BLE
Broadcasts Microsoft Swift Pair advertisements for Surface devices and accessories.
Usage: spam_windows
spam_all
BLE
Cycles through all device types (iOS, Android, Samsung, Windows) broadcasting a variety of BLE pairing prompts. Maximum chaos mode for testing.
Usage: spam_all
Legal Warning
Some items may be illegal in your jurisdiction. Only use these features on hardware you own or have explicit permission to test.
System Commands
help
System
Displays the main menu with all available commands organized by category.
Usage: help
stop
System
Immediately stops all running operations including beacon spam, BLE spam, sniffing, and access points. Essential emergency stop command.
Usage: stop
clear
System
Clears the serial terminal screen. Uses ANSI escape codes to reset the display.
Usage: clear
Legal Warning
Educational Use Only
PenESP is designed for educational purposes and authorized security testing only. Unauthorized access to computer networks, wireless interference, and interception of communications are illegal in most jurisdictions.
Responsible Use Guidelines
- Only test on networks and devices you own or have written permission to test
- Deauthentication attacks can disrupt legitimate network services
- BLE spam features can be annoying and disruptive to nearby users
- Packet sniffing may capture sensitive data - handle responsibly
- Some features may violate radio spectrum regulations
- Always comply with local laws and regulations
Ethical Considerations
Security research and penetration testing serve important purposes in improving system security, but must be conducted ethically and legally. Always obtain proper authorization before testing, respect privacy, and disclose findings responsibly.
Troubleshooting
Common Issues
| Issue |
Solution |
| BLE commands show "not enabled" |
Try a different board with Bluetooth support |
| Serial connection fails |
Check baud rate is set to 115200 and correct port selected |
| WiFi scan returns no results |
Ensure antenna is properly connected and device has power |
| Deauth not working |
Ensure target was set correctly and is in range |
| Commands not responding |
Use the stop command to reset operations |
| Device crashes or reboots |
May be power issue - use quality USB cable and power supply |
Performance Tips
- For best WiFi range, use an ESP32 with an external antenna
- BLE and WiFi operations may conflict - run them separately
- Beacon spam is resource-intensive - expect slower response times
- Stop operations before switching to different commands
- Monitor serial buffer - some operations generate lots of output
Getting Help
If you encounter issues not covered here:
- Check the PenESP website for updates
- Join the Discord community for support
- Review the source code on GitHub for technical details
- Ensure you're using compatible ESP32 hardware
Quick Reference
| Command |
Category |
Description |
| help | System | Show command menu |
| stop | System | Stop all operations |
| clear | System | Clear terminal |
| wifi_scan | WiFi | Scan for networks |
| ssid_info | WiFi | Get network details |
| beacon_funny | WiFi | Funny beacon spam |
| beacon_random | WiFi | Random beacon spam |
| beacon_custom | WiFi | Custom beacon spam |
| deauth_set | WiFi | Set deauth target |
| deauth_send | WiFi | Send deauth packets |
| sniff | WiFi | Packet sniffer |
| ap_start | WiFi | Start access point |
| ap_stop | WiFi | Stop access point |
| ble_scan | BLE | Scan BLE devices |
| ble_fingerprint | BLE | Identify BLE devices |
| spam_ios | BLE | iOS device spam |
| spam_android | BLE | Android device spam |
| spam_samsung | BLE | Samsung device spam |
| spam_windows | BLE | Windows device spam |
| spam_all | BLE | All device spam |