Semi-Evil M5Dial
Introduction 🎉
Welcome to Semi-Evil M5Dial!
Unlock the full potential of your M5Dial device with our feature-rich firmware. Whether you're a developer, security enthusiast, or hobbyist, Semi-Evil-M5Dial empowers you with advanced tools such as WiFi captive portal management, SSID handling, Karma attacks, and BadUSB script execution. Dive in and transform your M5Dial into a versatile powerhouse!
Table of Contents 📚
Features
- 🔒 WiFi Captive Portal: Create a customizable captive portal for network interactions.
- 📡 SSID Management: Save, select, and manage multiple SSIDs with ease.
- 🕵️♂️ Karma Attack Mode: Perform Karma attacks by spoofing SSIDs and capturing probe requests.
- 💻 BadUSB Integration: Execute pre-defined USB HID scripts to automate keyboard inputs.
- ⚙️ Settings Menu: Adjust screen brightness, toggle modes, enable verbose debugging, and more.
- 🌐 Web-Based File Uploader: Easily upload and delete files on the device’s SPIFFS from a browser interface.
Setup & Installation 🚀🔧
Follow these steps to get Semi-Evil M5Dial up and running on your M5Dial device using PlatformIO.
Prerequisites
- PlatformIO IDE: It's recommended to use Visual Studio Code with the PlatformIO extension installed.
- USB Cable: A reliable USB cable to connect your M5Dial device to your computer.
- Git: To clone the repository. Install Git if you haven't already.
Step 1: Clone the Repository
Open your terminal or command prompt and execute:
git clone https://github.com/dagnazty/Semi-Evil-M5Dial.git
Step 2: Open the Project in PlatformIO
-
Launch Visual Studio Code (VS Code):
-
Open the Project:
- Click on File > Open Folder... and select the cloned
Semi-Evil-M5Dial directory.
-
Wait for PlatformIO to Initialize:
- PlatformIO will automatically detect the project configuration and initialize the environment.
Step 3: Install Dependencies
PlatformIO manages dependencies through the platformio.ini file. Ensure all required libraries are specified. The provided platformio.ini includes all necessary dependencies.
Step 4: Prepare the Filesystem (SPIFFS)
The firmware utilizes the SPIFFS filesystem to store configurations, SSIDs, logs, and scripts.
-
Locate the data/ Folder:
- Ensure the
data/ folder is located at the root of the project, alongside the src/ folder.
Semi-Evil-M5Dial/
├── include/
├── lib/
├── src/
│ └── main.cpp
├── data/
│ ├── index.html
│ ├── doge.html
│ ├── SSID.json
│ ├── log.txt
│ ├── logo.bmp
│ └── test.txt
├── platformio.ini
└── README.md
-
Add Required Files:
- Web Files:
index.html: The main page for the captive portal.
doge.html: An additional HTML page.
- Configuration Files:
SSID.json: Stores the list of saved SSIDs.
log.txt: Stores logs collected via the captive portal.
- BadUSB Scripts:
- Place your
.txt script files in the data/ folder. These scripts define the USB HID actions.
- Images:
logo.bmp: Displayed upon device startup.
-
Upload SPIFFS to Device:
-
In VS Code, open the PlatformIO Terminal (View > Terminal).
-
Execute the following command to upload the data/ folder to the device's SPIFFS:
pio run --target uploadfs
-
Note: Ensure your device is connected and recognized by your computer.
Step 5: Upload Firmware to Device
After uploading the filesystem, proceed to flash the firmware.
-
Ensure the Device is in Bootloader Mode:
- Automatic Entry: Most devices automatically enter bootloader mode when initiating a firmware upload.
- Manual Entry:
- Press and hold the RESET button.
- While holding RESET, plug the device in.
- Release the RESET button.
-
Upload Firmware:
- In the PlatformIO Toolbar at the bottom, click the Upload button (right arrow icon) or press
Ctrl + Alt + U.
- PlatformIO will compile the project and flash the firmware to your device.
- Progress Indicators:
- Monitor the Output panel for upload progress and any potential errors.
-
Verify Successful Upload:
- Upon completion, you should see a success message.
- The device will automatically reboot if Auto Reboot is enabled in
platformio.ini.
Usage 🛠️
Navigating the Menu
The M5Dial features a rotary encoder and a button (BtnA) for navigation:
- Rotate Encoder: Scroll through menu items.
- Press BtnA: Select the highlighted menu item.
- Long Press BtnA (1 second): Return to the main menu or perform specific actions depending on the context.
Features Overview
Upon powering up, the device displays a logo (if available) and navigates to the main menu with the following options:
-
Start Portal:
Initiates a WiFi captive portal allowing users to connect and interact via the hosted web server.
-
Saved SSID:
View and select from a list of previously saved SSIDs to configure the device's AP.
-
Start Karma:
Engages Karma attack mode to spoof SSIDs and capture probe requests.
-
BadUSB:
Execute pre-defined USB HID scripts for automated keyboard inputs.
-
About:
Displays information about the firmware version and authors.
-
Settings:
Access and modify device settings such as screen brightness, toggle modes, and enable verbose debugging.
Web-Based File Uploader
In addition to the captive portal, Semi-Evil M5Dial provides a web-based uploader for conveniently managing files on the device’s SPIFFS without needing to rebuild or re-upload via PlatformIO.
- Start the Portal (from the main menu) and connect to the device’s AP (e.g.
192.168.4.1).
- Navigate to
/upload:
For example, open http://192.168.4.1/upload in your browser.
- Use the “Device Control Panel”:
- Upload Files: Click “Upload Files” to add new scripts, images, or JSON files to SPIFFS.
- List & Delete: See a list of uploaded files and delete them at the press of a button.
Typical Workflow
- Add or replace your BadUSB scripts (
.txt files), images (.bmp), or configuration (.json) files via /upload.
- After uploading, the device automatically updates the SPIFFS file list, so you can immediately use or select new resources in the menus.
Note: If your device is connected under a different IP or captive portal, adjust the URL accordingly (e.g., http://<device-IP>/upload).
Configuration
Settings Menu
Access the Settings menu from the main menu to perform various configurations:
-
Power Off:
- Safely powers down the device.
-
Screen Brightness:
- Adjust the display brightness using the encoder.
-
Toggle BadUSB Mode:
- Switch between Normal (Debug) mode and BadUSB (HID) mode.
-
Verbose Debug:
- Enable or disable verbose debugging for more detailed logs.
-
Back:
BadUSB Scripts
To utilize the BadUSB feature:
-
Create Scripts:
- Write your BadUSB scripts in
.txt files following the defined format:
DELAY <milliseconds>
STRING <text>
ENTER
TAB
ESC
CTRL <key>
ALT <key>
-
Add Scripts to SPIFFS:
- Place your
.txt script files in the data/ folder before uploading SPIFFS.
-
Execute Scripts:
- Navigate to BadUSB in the main menu.
- Select the desired script to execute. In Debug mode, scripts can be read via Serial. In BadUSB mode, selected scripts execute upon device reset or power-on.
Troubleshooting
Contributing 🤝
We welcome contributions from the community! To ensure a smooth collaboration, please follow these guidelines:
-
Fork the Repository:
Click the Fork button at the top-right corner of this page.
-
Clone Your Fork:
git clone https://github.com/yourusername/Semi-Evil-M5Dial.git
-
Create a Feature Branch:
git checkout -b feature/your-feature-name
-
Commit Your Changes:
Ensure your code follows the existing style and includes appropriate documentation.
-
Push to Your Fork:
git push origin feature/your-feature-name
-
Open a Pull Request:
Navigate to the original repository and click New Pull Request.
License 📄
This project is licensed under the MIT License.
Credits
-
Developers:
-
Libraries:
-
Tools:
-
Original Project:
Support & Contact 📬
For any questions or support, please open an issue on the GitHub repository or reach out to us directly:
Stay updated with the latest developments by starring the repository ⭐ and following our project updates.