PuterOS is a compact, modular firmware for the M5Stack Cardputer (ESP32-S3). It provides a screen-driven UI and a set of tools that demonstrate and leverage the hardware capabilities of the device.

• Purpose: provide a small, extensible platform that exposes WiFi/BLE/NFC, hardware modules, and utilities through a simple menu-and-screen interface.
• Target: M5Stack Cardputer (ESP32-S3) running under PlatformIO / Arduino environment.
• Design: modular screens (one feature = one screen), lightweight utilities, and optional hardware module support.

• WiFi

  • Scanning and analyzing nearby networks.
  • Packet capture/monitoring and small demo attacks (deauth, beacon spam).
  • Network utilities such as IP scanning and status info.
  • ESP-NOW chat demo for device-to-device messaging.

• BLE

  • BLE scanning and advertisement analysis.
  • BLE HID keyboard (duckyscript runner / shortcuts) to send keystrokes to a host.

• Modules

  • NFC MFRC522 (using I2C and and for now only able to read and check default keys)
  • PN5322 Killer (using uart and for now only able to read and check default keys)

• File manager

  • Browse files on SD card.

• Utilities

  • QR code generator and renderer on the screen.
  • I2C bus scanner to detect connected sensors/modules.

• Games

  • Decoding Number, small game to guess random generated number.

• src/ — implementation files (screens are under src/os/screens/).
• include/ — public headers and shared interfaces.
• lib/ — external libraries and helpers.
• platformio.ini — build configuration.

Here is how to manually compile and upload to your M5Stack Cardputer.

1. Install PlatformIO (VSCode or CLI).
2. Clone this repository
3. Connect your M5Stack Cardputer
4. Build and upload:

   pio run -t upload
   

Thanks to some of the following projects, their code and community helped me a lot to get this far:

• Bruce Firmware
• Evil M5
• ESP32 BLE Combo
• ESP Web Flasher

This project is open source. See LICENSE for details.