{"id":23212768,"url":"https://github.com/dagnazty/semi-evil-m5dial","last_synced_at":"2025-10-26T00:31:10.685Z","repository":{"id":268555118,"uuid":"904506947","full_name":"dagnazty/Semi-Evil-M5Dial","owner":"dagnazty","description":"Advanced firmware for M5Dial devices, enabling WiFi captive portals, SSID management, Karma attack tools, and BadUSB scripting for enhanced security testing and automation.","archived":false,"fork":false,"pushed_at":"2025-01-25T20:19:28.000Z","size":162,"stargazers_count":10,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-11T04:07:23.720Z","etag":null,"topics":["automation","badusb","captive-portal","esp32","firmware","m5dial","networking","penetration-testing","security","wifi"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dagnazty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-17T03:03:25.000Z","updated_at":"2025-01-25T20:19:31.000Z","dependencies_parsed_at":"2024-12-17T14:19:07.345Z","dependency_job_id":"7dea6b8a-479b-43bb-9d47-5125b8576460","html_url":"https://github.com/dagnazty/Semi-Evil-M5Dial","commit_stats":null,"previous_names":["dagnazty/semi-evil-m5dial"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagnazty%2FSemi-Evil-M5Dial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagnazty%2FSemi-Evil-M5Dial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagnazty%2FSemi-Evil-M5Dial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dagnazty%2FSemi-Evil-M5Dial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dagnazty","download_url":"https://codeload.github.com/dagnazty/Semi-Evil-M5Dial/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238229948,"owners_count":19437724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","badusb","captive-portal","esp32","firmware","m5dial","networking","penetration-testing","security","wifi"],"created_at":"2024-12-18T19:12:55.637Z","updated_at":"2025-10-26T00:31:05.301Z","avatar_url":"https://github.com/dagnazty.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg) ![GitHub issues](https://img.shields.io/github/issues/dagnazty/Semi-Evil-M5Dial) ![GitHub stars](https://img.shields.io/github/stars/dagnazty/Semi-Evil-M5Dial?style=social) ![GitHub forks](https://img.shields.io/github/forks/dagnazty/Semi-Evil-M5Dial?style=social)\n\n![Project Banner](logo.png)\n\n# Semi-Evil M5Dial\n\n\u003c/div\u003e\n\n## Introduction 🎉\n\n\u003cdiv align=\"center\"\u003e\n\nWelcome to **Semi-Evil M5Dial**!\n\nUnlock 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!\n\n\u003c/div\u003e\n\n## Table of Contents 📚\n\n- [Introduction](#introduction)\n- [Features](#features)\n- [Setup \u0026 Installation 🚀🔧](#setup--installation-🚀🔧)\n- [Usage 🛠️](#usage-🛠️)\n- [Web-Based File Uploader](#web-based-file-uploader)\n- [Configuration](#configuration)\n- [Troubleshooting](#troubleshooting)\n- [Contributing 🤝](#contributing-🤝)\n- [License 📄](#license-📄)\n- [Credits](#credits)\n- [Support \u0026 Contact 📬](#support--contact-📬)\n\n## Features\n\n- 🔒 **WiFi Captive Portal:** Create a customizable captive portal for network interactions.\n- 📡 **SSID Management:** Save, select, and manage multiple SSIDs with ease.\n- 🕵️‍♂️ **Karma Attack Mode:** Perform Karma attacks by spoofing SSIDs and capturing probe requests.\n- 💻 **BadUSB Integration:** Execute pre-defined USB HID scripts to automate keyboard inputs.\n- ⚙️ **Settings Menu:** Adjust screen brightness, toggle modes, enable verbose debugging, and more.\n- 🌐 **Web-Based File Uploader:** Easily upload and delete files on the device’s SPIFFS from a browser interface.\n\n## Setup \u0026 Installation 🚀🔧\n\nFollow these steps to get **Semi-Evil M5Dial** up and running on your M5Dial device using **PlatformIO**.\n\n### Prerequisites\n\n- **PlatformIO IDE:** It's recommended to use [Visual Studio Code](https://code.visualstudio.com/) with the [PlatformIO extension](https://platformio.org/install/ide?install=vscode) installed.\n- **USB Cable:** A reliable USB cable to connect your M5Dial device to your computer.\n- **Git:** To clone the repository. Install [Git](https://git-scm.com/downloads) if you haven't already.\n\n### Step 1: Clone the Repository\n\nOpen your terminal or command prompt and execute:\n\n```bash\ngit clone https://github.com/dagnazty/Semi-Evil-M5Dial.git\n```\n\n### Step 2: Open the Project in PlatformIO\n\n1. **Launch Visual Studio Code (VS Code):**\n   - Ensure you have the [PlatformIO extension](https://platformio.org/install/ide?install=vscode) installed.\n\n2. **Open the Project:**\n   - Click on **File \u003e Open Folder...** and select the cloned `Semi-Evil-M5Dial` directory.\n\n3. **Wait for PlatformIO to Initialize:**\n   - PlatformIO will automatically detect the project configuration and initialize the environment.\n\n### Step 3: Install Dependencies\n\nPlatformIO manages dependencies through the `platformio.ini` file. Ensure all required libraries are specified. The provided `platformio.ini` includes all necessary dependencies.\n\n### Step 4: Prepare the Filesystem (SPIFFS)\n\nThe firmware utilizes the SPIFFS filesystem to store configurations, SSIDs, logs, and scripts.\n\n1. **Locate the `data/` Folder:**\n   - Ensure the `data/` folder is located at the **root of the project**, alongside the `src/` folder.\n\n   ```\n   Semi-Evil-M5Dial/\n   ├── include/\n   ├── lib/\n   ├── src/\n   │   └── main.cpp\n   ├── data/\n   │   ├── index.html\n   │   ├── doge.html\n   │   ├── SSID.json\n   │   ├── log.txt\n   │   ├── logo.bmp\n   │   └── test.txt\n   ├── platformio.ini\n   └── README.md\n   ```\n\n2. **Add Required Files:**\n   - **Web Files:**\n     - `index.html`: The main page for the captive portal.\n     - `doge.html`: An additional HTML page.\n   - **Configuration Files:**\n     - `SSID.json`: Stores the list of saved SSIDs.\n     - `log.txt`: Stores logs collected via the captive portal.\n   - **BadUSB Scripts:**\n     - Place your `.txt` script files in the `data/` folder. These scripts define the USB HID actions.\n   - **Images:**\n     - `logo.bmp`: Displayed upon device startup.\n\n3. **Upload SPIFFS to Device:**\n   - In VS Code, open the **PlatformIO Terminal** (`View \u003e Terminal`).\n   - Execute the following command to upload the `data/` folder to the device's SPIFFS:\n\n     ```bash\n     pio run --target uploadfs\n     ```\n\n   - **Note:** Ensure your device is connected and recognized by your computer.\n\n### Step 5: Upload Firmware to Device\n\nAfter uploading the filesystem, proceed to flash the firmware.\n\n1. **Ensure the Device is in Bootloader Mode:**\n   - **Automatic Entry:** Most devices automatically enter bootloader mode when initiating a firmware upload.\n   - **Manual Entry:**\n     - Press and hold the **RESET** button.\n     - While holding **RESET**, plug the device in.\n     - Release the **RESET** button.\n\n2. **Upload Firmware:**\n   - In the **PlatformIO Toolbar** at the bottom, click the **Upload** button (right arrow icon) or press `Ctrl + Alt + U`.\n   - PlatformIO will compile the project and flash the firmware to your device.\n   - **Progress Indicators:**\n     - Monitor the **Output** panel for upload progress and any potential errors.\n\n3. **Verify Successful Upload:**\n   - Upon completion, you should see a success message.\n   - The device will automatically reboot if **Auto Reboot** is enabled in `platformio.ini`.\n\n## Usage 🛠️\n\n### Navigating the Menu\n\nThe M5Dial features a rotary encoder and a button (**BtnA**) for navigation:\n\n- **Rotate Encoder:** Scroll through menu items.\n- **Press BtnA:** Select the highlighted menu item.\n- **Long Press BtnA (1 second):** Return to the main menu or perform specific actions depending on the context.\n\n### Features Overview\n\nUpon powering up, the device displays a logo (if available) and navigates to the main menu with the following options:\n\n1. **Start Portal:**  \n   Initiates a WiFi captive portal allowing users to connect and interact via the hosted web server.\n\n2. **Saved SSID:**  \n   View and select from a list of previously saved SSIDs to configure the device's AP.\n\n3. **Start Karma:**  \n   Engages Karma attack mode to spoof SSIDs and capture probe requests.\n\n4. **BadUSB:**  \n   Execute pre-defined USB HID scripts for automated keyboard inputs.\n\n5. **About:**  \n   Displays information about the firmware version and authors.\n\n6. **Settings:**  \n   Access and modify device settings such as screen brightness, toggle modes, and enable verbose debugging.\n\n## Web-Based File Uploader\n\nIn 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.\n\n1. **Start the Portal** (from the main menu) and connect to the device’s AP (e.g. `192.168.4.1`).\n2. **Navigate to `/upload`:**  \n   For example, open `http://192.168.4.1/upload` in your browser.\n3. **Use the “Device Control Panel”:**\n   - **Upload Files**: Click **“Upload Files”** to add new scripts, images, or JSON files to SPIFFS.\n   - **List \u0026 Delete**: See a list of uploaded files and delete them at the press of a button.\n\n### Typical Workflow\n\n- **Add** or **replace** your **BadUSB** scripts (`.txt` files), images (`.bmp`), or configuration (`.json`) files via `/upload`.\n- After uploading, the device automatically updates the SPIFFS file list, so you can immediately use or select new resources in the menus.\n\n**Note**: If your device is connected under a different IP or captive portal, adjust the URL accordingly (e.g., `http://\u003cdevice-IP\u003e/upload`).\n\n## Configuration\n\n### Settings Menu\n\nAccess the **Settings** menu from the main menu to perform various configurations:\n\n1. **Power Off:**\n   - Safely powers down the device.\n\n2. **Screen Brightness:**\n   - Adjust the display brightness using the encoder.\n\n3. **Toggle BadUSB Mode:**\n   - Switch between Normal (Debug) mode and BadUSB (HID) mode.\n\n4. **Verbose Debug:**\n   - Enable or disable verbose debugging for more detailed logs.\n\n5. **Back:**\n   - Return to the main menu.\n\n### BadUSB Scripts\n\nTo utilize the BadUSB feature:\n\n1. **Create Scripts:**\n   - Write your BadUSB scripts in `.txt` files following the defined format:\n     - `DELAY \u003cmilliseconds\u003e`\n     - `STRING \u003ctext\u003e`\n     - `ENTER`\n     - `TAB`\n     - `ESC`\n     - `CTRL \u003ckey\u003e`\n     - `ALT \u003ckey\u003e`\n\n2. **Add Scripts to SPIFFS:**\n   - Place your `.txt` script files in the `data/` folder before uploading SPIFFS.\n\n3. **Execute Scripts:**\n   - Navigate to **BadUSB** in the main menu.\n   - 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.\n\n## Troubleshooting\n\n- **SPIFFS Upload Issues:**\n  - Ensure the `data/` folder is correctly structured at the project root.\n  - Verify the **PlatformIO Core** is up-to-date and no duplicate installations exist.\n  - Check file permissions to ensure PlatformIO can access the directory and its files.\n\n- **Web Server Not Accessible:**\n  - Confirm the device's AP is active and you're connected to the correct SSID.\n  - Check firewall settings on your computer that might block access.\n\n- **BadUSB Scripts Not Executing:**\n  - Verify scripts are correctly formatted and placed in SPIFFS.\n  - Ensure the device is in BadUSB mode.\n\n- **Display Issues:**\n  - Adjust screen brightness in the Settings menu.\n  - Check for corrupted SPIFFS files.\n\n- **Device Not Responding:**\n  - Perform a reset by disconnecting and reconnecting the USB cable.\n  - Re-upload the firmware if necessary.\n\n- **PlatformIO Core Errors:**\n  - Ensure only one PlatformIO Core installation exists.\n  - Update PlatformIO Core to the latest version following the [PlatformIO Troubleshooting Guide](https://docs.platformio.org/en/latest/core/installation/troubleshooting.html).\n\n## Contributing 🤝\n\nWe welcome contributions from the community! To ensure a smooth collaboration, please follow these guidelines:\n\n1. **Fork the Repository:**  \n   Click the **Fork** button at the top-right corner of this page.\n\n2. **Clone Your Fork:**  \n   ```bash\n   git clone https://github.com/yourusername/Semi-Evil-M5Dial.git\n   ```\n\n3. **Create a Feature Branch:**  \n   ```bash\n   git checkout -b feature/your-feature-name\n   ```\n\n4. **Commit Your Changes:**  \n   Ensure your code follows the existing style and includes appropriate documentation.\n\n5. **Push to Your Fork:**  \n   ```bash\n   git push origin feature/your-feature-name\n   ```\n\n6. **Open a Pull Request:**  \n   Navigate to the original repository and click **New Pull Request**.\n\n## License 📄\n\nThis project is licensed under the [MIT License](LICENSE).  \n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)\n\n## Credits\n\n- **Developers:**\n  - [7h30th3r0n3](https://github.com/7h30th3r0n3)\n  - [dagnazty](https://github.com/dagnazty)\n\n- **Libraries:**\n  - [M5Dial](https://github.com/m5stack/M5Dial)\n  - [ArduinoJson](https://arduinojson.org/)\n  - [ESP32 Arduino](https://github.com/espressif/arduino-esp32)\n  \n- **Tools:**\n  - [ESP32 Sketch Data Upload](https://github.com/esp8266/arduino-esp8266fs-plugin)\n\n- **Original Project:**\n  - [Evil-M5Core2](https://github.com/7h30th3r0n3/Evil-M5Core2) by [7h30th3r0n3](https://github.com/7h30th3r0n3)\n\n## Support \u0026 Contact 📬\n\nFor any questions or support, please open an issue on the [GitHub repository](https://github.com/dagnazty/Semi-Evil-M5Dial/issues) or reach out to us directly:\n\n- **GitHub:** [@dagnazty](https://github.com/dagnazty)\n- **Twitter:** [@dagnazty](https://twitter.com/dagnazty)\n\nStay updated with the latest developments by starring the repository ⭐ and following our [project updates](https://github.com/dagnazty/Semi-Evil-M5Dial/releases).\n\n---","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdagnazty%2Fsemi-evil-m5dial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdagnazty%2Fsemi-evil-m5dial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdagnazty%2Fsemi-evil-m5dial/lists"}