Evil-M5Project — Installation and Flashing

Installing Evil-M5Project has two halves that are easy to conflate and equally required. The firmware image is written into the ESP32’s internal flash; the runtime assets — UI images, captive-portal pages, configuration and logs — live in an evil/ folder on a microSD card. Flashing the firmware without preparing the card leaves many features non-functional, and the project’s documentation states an SD card with the required files is mandatory in essentially all cases.

3.1 Method 1 — M5Burner (recommended)

M5Burner is M5Stack’s official flashing utility, and it carries prebuilt Evil-* images in its online catalogue. This is the path most operators use.

1. Install M5Burner from the M5Stack download center on a host computer.
2. Connect the M5Stack device over USB.
3. In M5Burner, search for evil- and pick the build that matches the device (for example Evil-Cardputer for a Cardputer, Evil-M5Core2 for a Core2).
4. Download the image, then Flash it to the connected device.
5. Prepare the microSD card (see “The microSD evil/ folder” below) and insert it before first boot.

M5Burner handles the partitioning and the correct flash offsets, which is why it is the recommended route — it removes the most common source of a bricked or boot-looping flash.

3.2 Method 2 — Manual build (Arduino IDE)

Building from source is the route for developers, for a board M5Burner does not list, or to run a specific commit. The upstream project documents an Arduino IDE build with a specific, unforgiving set of settings.

Libraries (install all of these in the Arduino Library Manager): Adafruit_NeoPixel, ArduinoJson, ESPping, IniFile, M5GFX, M5Unified, TinyGPSPlus, and esp8266audio.

Board settings (values shown for the Cardputer; other devices differ):

Table 1 — Board settings (values shown for the Cardputer; other devices differ)

Setting	Value
Flash Size	8 MB
Partition Scheme	8M with spiffs (3 MB app / 1.5 MB SPIFFS)
PSRAM	Disabled
Upload baud rate	115200
ESP32 board package	2.1.4 or below

The ESP32 board-package version is a genuine footgun: the project documents build failures on the 3.0.0-alpha packages for non-M5Stack devices, so pinning the Arduino-ESP32 core to a 2.x release (2.1.4 or below is the documented guidance) avoids a class of compile errors. The upstream repository also ships a preparatory step (a script under utilities/deauth_prerequisites) that patches a limitation in the stock ESP32 Wi-Fi library so the deauth transmit path compiles; run it before uploading if the build needs the deauth feature.

3.3 The microSD evil/ folder

Regardless of which flashing method is used, the card must carry an evil/ folder at its root. The card should be FAT32 and, per the project’s guidance, 16 GB or smaller for best compatibility. The folder holds the runtime assets the firmware expects, along the lines of:

/ (SD root)
└── evil/
    ├── IMG/       ← boot and UI images
    ├── sites/     ← captive-portal HTML pages
    ├── NTLM/      ← hash / wordlist data
    ├── config/    ← settings and logs
    └── …          ← DeadDrop, GPS/WiGLE output, further per-feature folders

The exact folder set tracks the upstream release; the simplest way to get a correct one is to copy the evil/ directory shipped in the repository or the release archive onto the card unchanged, then customize the portal pages in sites/ afterward. Without these files the project notes that many features — the UI, the captive portals, NTLM capture, logging, DeadDrop — will not work.

3.4 First boot

On first boot the firmware reads its assets from the card and presents the main menu. If the card is missing or the evil/ folder is absent or incomplete, the device may boot to a degraded menu or show missing-asset behavior rather than failing outright, which is a common source of “the flash worked but half the features are gone” confusion. The fix is almost always the card, not the flash: confirm the card is FAT32, that evil/ is at the root, and that its contents match the installed firmware version.

3.5 Recovering a bad flash

Because M5Burner writes the correct partition table, the reliable recovery from a boot loop or a bad manual build is to reflash a known-good image with M5Burner. A fully unresponsive device can be recovered with the standard esptool erase-and-reflash procedure over USB, after which M5Burner’s image can be written again.

Continue to Volume 4 for the supported hardware and the version map.