This page provides a high-level introduction to HackMaster Pi, describing its purpose, architecture, core capabilities, and key components. It serves as the entry point to the documentation, orienting readers to the system's design and functionality.
For specific setup instructions, see Installation and Setup. For detailed information about individual technology domains, see WiFi Attack Tools, Bluetooth Low Energy (BLE) Tools, RFID/NFC Tools, and Infrared (IR) Tools.
HackMaster Pi is an open-source IoT security testing platform built on the Raspberry Pi Zero 2 W. The system is designed as a cost-effective educational tool for learning IoT device attack and defense methodologies. It integrates multiple wireless communication technologies—WiFi, Bluetooth Low Energy, RFID/NFC, and infrared—into a single portable device with a web-based management interface.
The platform runs a FastAPI application accessible via web browser on port 4000, providing a unified interface for controlling hardware modules and executing security testing operations. All functionality is managed through systemd services that ensure automatic startup and recovery.
Project Status: Active development, open-source under MIT License
Repository: https://github.com/1PingSun/HackMaster-Pi
Sources: README.md1-63
HackMaster Pi organizes its functionality into four primary technology domains, weighted by implementation importance:
| Domain | Importance Score | Status | Key Features |
|---|---|---|---|
| WiFi | 78.0 | ✓ Implemented | Network scanning, password cracking (aircrack-ng), deauthentication attacks, handshake capture, wordlist generation, AP emulation (planned) |
| BLE | 19.53 | ✓ Implemented | Beacon scanning, iBeacon emulation, profile management, AirPods device emulation |
| RFID/NFC | 10.03 | ✓ Implemented | ISO14443A card identification, UID reading, CUID card writing, card emulation (planned) |
| Infrared | Referenced | ⧗ Planned | Signal learning, remote control cloning, signal enumeration |
The WiFi domain represents the most comprehensive feature set, implementing a complete attack chain from network discovery through password recovery. BLE and RFID capabilities provide secondary attack vectors for IoT device testing.
Sources: High-level system diagrams, README.md21-34
System Architecture Layers
The architecture is organized into five distinct layers:
Sources: High-level system diagrams, README.md40-46
| Component | Interface | Purpose | Configuration |
|---|---|---|---|
| Raspberry Pi Zero 2 W | Host | ARM Cortex-A53 quad-core processor, 512MB RAM | Runs Raspberry Pi OS |
| PN532 NFC/RFID Module | I2C (0x24) | ISO14443A card operations | Shared I2C bus via /dev/i2c-1 |
| OLED Display 0.96" | I2C (0x3C) | IP address and status display | SSD1306 controller, 128x64 pixels |
| YS-IRTM IR Module | GPIO | Infrared signal transmission (planned) | GPIO pin configuration required |
| Built-in Bluetooth | BCM43438 | BLE beacon operations | Managed via hciconfig, hcitool |
| WiFi Adapter 8812AU | USB | Monitor mode, packet injection | Requires rtl8812au driver |
| 3D Printed Case | Physical | Device enclosure | 3d-case/Part1.stl, Part2.stl |
The I2C bus architecture allows both the PN532 module and OLED display to share /dev/i2c-1 with different addresses (0x24 and 0x3C respectively), configured via /boot/config.txt.
Sources: README.md40-46 High-level system diagrams
Key Software Components:
0.0.0.0:4000luma.oled for display control, pn532pi for NFC operationsap_scan.py for network scanning, WeakPasswordGenerater.py for wordlist creation, beacon_emulator.py for BLE operationsThe application runs in a Python virtual environment (app/env/) with all dependencies isolated from system Python packages.
Sources: High-level system diagrams
Route-to-Code Mapping:
This diagram bridges the HTTP API surface to actual code entities. Each route path corresponds to:
main.py using @app.get() and @app.post() decoratorsapp/WiFi/, app/BLE/, app/RFID/)airodump-ng, aireplay-ng, aircrack-ng, hcitoolBeaconEmulator and PN532_I2C that abstract hardware access.cap files for packet capturesSources: High-level software module dependencies diagram
Implementation Status by Domain:
WiFi (Fully Implemented): Complete 9-step attack workflow from interface configuration to password recovery. Uses aircrack-ng suite for all operations. Custom ap_scan.py module parses airodump-ng CSV output. WeakPasswordGenerater.py creates targeted wordlists from personal information patterns.
BLE (Fully Implemented): BeaconEmulator class in beacon_emulator.py uses hcitool commands for iBeacon advertising. Profiles stored in beacon_profiles.json with UUID, Major, Minor, and Power fields. AirPods emulation via external script adv_airpods.py in apple_bleee/ directory.
RFID (Partially Implemented): RFIDlib/main.py provides PN532_I2C class for hardware abstraction. Supports ISO14443A card reading and CUID card writing. Card emulation planned but not implemented.
IR (Planned): YS-IRTM hardware present but no software implementation yet.
Sources: High-level system diagrams, README.md21-34
HackMaster Pi uses two systemd services for automated lifecycle management:
| Service | File | Purpose | Managed Process |
|---|---|---|---|
oled-ip-display.service | /etc/systemd/system/oled-ip-display.service | Display IP address and status on OLED | app/oled_ip_display.py |
hackmaster-pi.service | /etc/systemd/system/hackmaster-pi.service | Main web application | uvicorn main:app --host 0.0.0.0 --port 4000 |
Both services are configured to start automatically on boot and restart on failure. The setup process is orchestrated by setup.sh, which executes three sub-scripts:
scripts/enable_i2c.sh: Configures I2C interface in /boot/config.txtscripts/setup_ip_show.sh: Installs OLED display servicescripts/setup_hackmasterpi.sh: Installs main application service and dependenciesThe main application runs in a Python virtual environment at app/env/ with all dependencies isolated. Uvicorn serves the FastAPI application on all interfaces (0.0.0.0) at port 4000.
Sources: High-level deployment and runtime architecture diagram
The user interface is built using server-side rendering with Jinja2 templates:
app/templates/index.html provides card-based navigation to four technology domainswifi-cracker.html, wifi-scanner.html, wordlist-generator.htmlbeacon-scanner.html, beacon-emulator.html, airpods-emulator.htmlidentify-rfid.html, write-rfid.htmlapp/static/styles.css implements cyberpunk-inspired dark theme with VT323 monospace fontapp/static/ contains images, favicon, and JavaScript for AJAX interactionsAll pages follow a consistent design pattern with status indicators, loading animations, and real-time feedback for long-running operations.
Sources: High-level system diagrams
HackMaster Pi is designed specifically for educational purposes in IoT security:
Learning Objectives:
Authorized Use Cases:
Ethical Guidelines: The system includes a disclaimer requiring users to operate only on networks and devices they own or have explicit authorization to test. Unauthorized access to computer systems and networks is illegal. The MIT License provides the software "as-is" without warranty.
Sources: README.md48-54
Implemented Features:
Planned Features:
Project tracking available at: https://github.com/users/1PingSun/projects/1
Sources: README.md21-34
For detailed information about specific aspects of HackMaster Pi:
Sources: Table of contents structure
Refresh this wiki