cypher-puter-os

Name: cypher-puter-os
Author: dkyazzentwatwa

Multi-purpose View the repo

23 stars · 3 forksGitHub repo · as of 2026-11-11 19:07 UTC

Maintainer: dkyazzentwatwa
Chip families: esp32-s3

Boards with a recipe, by trust tier

Unverified

CardputerUnverifiedM5Stack
Flash Cardputerguided
Unverified esp-atlas asserts this board↔firmware link at the shown trust tier — it does not guarantee your specific unit or the current firmware version. Flashing can erase keys/config and can brick the device. At your own risk.

README

Cypher OS

A local-first app deck for the M5Stack Cardputer ADV.

Install · Apps · Build · Controls · Docs

Cypher OS turns the M5Stack Cardputer ADV into a pocket-sized launcher for real Cardputer apps. Flash the launcher once, copy a release SD bundle, then swap between tools, games, music, chat, storage, and field utilities without doing a USB reflash every time you want to change what the device does.

It feels like a tiny handheld OS, but it stays honest about the hardware: ESP32 apps do not execute directly from SD. Cypher OS keeps a small launcher in the primary app slot, installs the selected app .bin from the SD catalog into the app partition, then reboots into that app. When the app supports return, you come back to the launcher and pick the next thing.

At A Glance

| You Get | Details | | --- | --- | | Flash once, swap often | Install app binaries from SD instead of reflashing over USB for every app change. | | Public release bundle | Each GitHub release ships the launcher .bin, SD card zip, generated catalog, and build report. | | Local catalog | No cloud feed, no online OTA, no account, no remote dependency. | | Return-to-launcher flow | Supported apps can reboot back into Cypher OS when you are done. | | Diagnostics screen | See SD mount state, app count, installed app, app slot size, selected binary size, and last install error. | | Arduino CLI only | Small, scriptable, and intentionally scoped to Cardputer ADV. |

Why It Rules

One Cardputer, many personalities. Carry a launcher, groovebox, secure chat tool, offline desk kit, arcade catalog, tarot journal, detector build, and bench utility on one SD card.
No cloud catalog. No online dependency. The whole flow is local: build apps, package the SD card, boot the launcher, pick what you want.
Made for repeat use. Apps can return to Cypher OS instead of turning the workflow into flash-once-and-done firmware.
Small launcher, big catalog. The launcher stays focused on browsing, installing, launching, diagnostics, and recovering from the SD app catalog.
Purpose-built for Cardputer ADV. No generic board matrix, no stretched scope, no pretending this is a multi-platform firmware framework.

Current App Lineup

These are the supported Cardputer app targets in the current catalog flow:

| App | What It Adds | | --- | --- | | Cypher Drive | Cardputer ADV HID payload launcher build. | | ESP32 BT HID | BLE-HID payload deck with SD-backed DuckyScript payloads and a Wi-Fi editor. | | ESP32 Pokedex | Offline Pokemon GO field guide that uses your existing SD data and sprites. | | Cypher Chat | Secure-only mesh chat build using protocol 0x02 with AES-256-GCM. | | Cardputer Games | Standalone Cardputer arcade catalog. | | Cardputer MPC | MPC-style groovebox with SD-loaded samples and sequencing. | | Cardputer Tarot | Offline tarot pull, journal, history, and study deck app. | | Cypher PN532 | PN532 NFC toolkit for the Cardputer ADV EXT I2C header. | | Cypher Desk | Offline utility suite with notes, calculator, checklist, converters, and scratchpad. | | Flock You | Cardputer ADV WiFi/BLE detector build with return-to-launcher support. | | WireTap-32 Cardputer | Cardputer ADV EXT bench build with return-to-launcher support. | | Drone Mesh Mapper | Cardputer ADV passive Remote ID scanner with SD field logs. | | Cypher AirTag | Cardputer ADV passive Apple Find My / AirTag detector with following alerts and locate beeps. | | Bitcoin Card Wallet | Offline Bitcoin wallet utility from the Cardputer App Bundle. | | Cardputer Game Station Emulators | Emulator launcher from the Cardputer App Bundle. | | | hardware bus and protocol toolkit from the Cardputer App Bundle. | | | Cardputer USB mass-storage SD bridge from the Cardputer App Bundle. | | | Guardian-backed Wi-Fi news reader from the Cardputer App Bundle. | | | Open-network scanner from the Cardputer App Bundle. | | | Offline Cardputer password vault from the Cardputer App Bundle. | | | remote-control utility from the Cardputer App Bundle. | | | Individual game files imported from the sibling repo when present and built successfully. |

starbeam_v2 is not part of the Cypher OS app catalog.

App Docs

For deeper notes on each app, controls, SD paths, return behavior, and imported game manuals, see docs/README.md.

How Launching Works

Cypher OS uses a compact local OTA-slot model:

The launcher lives in ota_0.
SD app binaries live under /cypher-puter/apps.
Choosing an app copies that app .bin into ota_1.
The device restarts into the installed app.
Supported apps can set a one-shot return flag and restart back to the launcher menu.

Use sketch app .bin files, not merged flash images. The launcher checks for oversized binaries and rejects merged images before writing.

Hardware

M5Stack Cardputer ADV
FAT32 SD card, preferably 32 GB or smaller (16GB MicroSD is great)
Apps stored under /cypher-puter/apps

Responsible Use

Cypher OS is for local, authorized hardware, NFC, wireless, and embedded-device work. Use the apps only with devices, cards, networks, and systems you own or have clear permission to test. The SD catalog is intentionally local-first and does not include an online payload or OTA feed.

Install With Codex Or Claude Code

If you use Codex or Claude Code on the machine connected to your Cardputer ADV, you can hand the agent this repo and ask it to perform the release install. The agent should use this repo's Arduino CLI workflow, keep the target hardware as Cardputer ADV, and avoid adding PlatformIO, ESP-IDF project files, online OTA, or multi-board scope.

Copy/paste prompt:

Install Cypher OS on my M5Stack Cardputer ADV from the latest GitHub release.
Use the release launcher bin and SD card zip, flash the launcher through the
repo helper when a /dev/cu.usbmodem* port is present, and tell me exactly what
you copied to the SD card. Do not change firmware or rebuild unless the release
assets are unavailable.

For a local source build instead, use:

Build and package this exact Cypher OS checkout for the M5Stack Cardputer ADV.
Run arduino-cli compile --profile adv ., then ./tools/build-apps.sh and
./tools/package-sd.sh. Use ./tools/flash-launcher.sh /dev/cu.usbmodemXXXX for
flashing. Keep the repo Arduino CLI only.

Install From A Release

Official public builds are shipped through GitHub Releases. Grab the newest v* release when you want the stable public bundle.

Each tagged release publishes exactly four public assets:

| Asset | Use It For | | --- | --- | | cypher-os-launcher.bin | Flash this one-file merged launcher image to the Cardputer ADV. | | cypher-os-sd-card.zip | Unzip this directly to the root of a FAT32 SD card. | | apps.json | Inspect the generated public catalog without opening the SD zip. | | BUILD_REPORT.md | Check app build status, binary sizes, source commits, and packaging notes. |

Quick install flow:

1. Flash cypher-os-launcher.bin
2. Unzip cypher-os-sd-card.zip to a FAT32 SD card
3. Insert SD card
4. Boot Cardputer
5. Pick an app from the Cypher OS catalog

Release asset names:

cypher-os-launcher.bin
cypher-os-sd-card.zip
apps.json
BUILD_REPORT.md

The SD zip is packaged so its contents land directly at the SD root:

/cypher-puter/apps/apps.json
/cypher-puter/apps/*.bin
/cardputer-mpc/
/cypher-drive/
/cardputer-game-os/saves/

ESP32 Pokedex ships as an app binary in the Cypher OS release bundle, but its larger data, sprite, and optional audio folders still live at the app's documented SD paths: /pokemon, /audio, and /config.

Catalog Model

config/apps.json is the human source of truth for the public catalog: app names, slugs, binary names, public repo URLs, local default paths, build profiles, SD paths, return behavior, and release flags.

Generated manifests live under dist/:

dist/apps/apps.json
dist/sd-card/cypher-puter/apps/apps.json
dist/BUILD_REPORT.md

dist/ is intentionally kept visible in the repo so users can inspect the latest prepared launcher, SD bundle, catalog, and build report. Do not edit generated manifests by hand. Update config/apps.json, rebuild the apps, and let the tools regenerate release output.

Build And Flash The Launcher Locally

Build with the Cardputer ADV profile:

cd cypher-puter-os
arduino-cli compile --profile adv .

Or use the helper:

./tools/build-launcher.sh

The canonical profile is in sketch.yaml:

m5stack:esp32:m5stack_cardputer:FlashSize=8M,PartitionScheme=custom,CDCOnBoot=cdc,USBMode=hwcdc

Flash with the local helper:

arduino-cli board list
./tools/flash-launcher.sh /dev/cu.usbmodemXXXX

If you omit the port, the script uses the first /dev/cu.usbmodem* port it finds, touches it at 1200 baud, waits for re-enumeration, then uploads with the adv profile.

Build And Package SD Apps Locally

Build the app binaries and package the SD card folder:

./tools/build-apps.sh
./tools/package-sd.sh

Build just one app while developing:

./tools/build-apps.sh --app cypher-chat
./tools/build-apps.sh --app esp32-pokedex
./tools/build-apps.sh --app cypher-desk
./tools/build-apps.sh --app news-reader
./tools/build-apps.sh --app ultimate-remote

Prepare the same artifact set used by official releases:

./tools/prepare-release.sh v0.1.0

Official GitHub releases are created by pushing a version tag:

git tag v0.1.0
git push origin v0.1.0

Then copy the contents of:

dist/sd-card

to the root of a FAT32 SD card.

Expected SD layout:

/cypher-puter/apps/apps.json
/cypher-puter/apps/cardputer-games.bin
/cypher-puter/apps/cardputer-mpc.bin
/cypher-puter/apps/cardputer-tarot.bin
/cypher-puter/apps/cypher-pn532.bin
/cypher-puter/apps/cypher-desk.bin
/cypher-puter/apps/cypher-chat.bin
/cypher-puter/apps/cypher-drive.bin
/cypher-puter/apps/esp32-bt-hid.bin
/cypher-puter/apps/esp32-pokedex.bin
/cypher-puter/apps/flock-you.bin
/cypher-puter/apps/wiretap-32-cardputer.bin
/cypher-puter/apps/drone-mesh-mapper.bin
/cypher-puter/apps/bitcoin-card-wallet.bin
/cypher-puter/apps/cardputer-game-station-emulators.bin
/cypher-puter/apps/esp32-bit-pirate.bin
/cypher-puter/apps/esp32-usb-stick.bin
/cypher-puter/apps/news-reader.bin
/cypher-puter/apps/open-wifi-scanner.bin
/cypher-puter/apps/password-manager.bin
/cypher-puter/apps/ultimate-remote.bin
/cypher-puter/apps/<cardputer-game-os-game>.bin
/cardputer-mpc/
/cypher-drive/payloads/
/drone/
/news-reader/config.example.txt
/cardputer-game-os/saves/

ESP32 Pokedex uses SD data already stored at /pokemon, /audio, and /config; the Cypher OS package only includes the app .bin and catalog entry.

The Cardputer App Bundle apps are built from the sibling new-cardputer-apps repo. Some of those apps expect their own user-provided SD data, such as /vaults/, /roms/, /gbc_saves/, or /card-wallets.txt; the Cypher OS package includes the app .bin files, catalog entries, and the News Reader example config.

The catalog imports individual game .bin files from the sibling cardputer-game-os repo. The nested Game OS launcher itself is not packaged because Cypher OS already owns the launcher partition.

Cypher Chat is built from the sibling cypher-chat/cypher-chat-firmware sketch with BOARD_PROFILE_CARDPUTER_ADV. Its mesh protocol is secure-only 0x02, so all fleet devices need matching firmware.

Workspace Layout

The app scripts default to sibling repos beside this checkout:

Source repositories: Cardputer MPC, Cypher Chat, Cardputer Games, Cypher Drive, Cardputer Tarot, ESP32 BT HID, ESP32 Pokedex, Cypher PN532, Cypher Desk, Cypher Flock, WireTap-32, Drone Mesh Mapper, Cypher AirTag, Cardputer App Bundle, and Cardputer Game OS.

GitHub/
  cypher-puter-os/
  cardputer-games/
  cardputer-mpc/
  cardputer-tarot/
  cypher-pn532/
  cardputer-game-os/
  cypher-chat/
  cypher-drive/
  ESP32_BT_HID/
  esp32-pokedex/
  cypher-desk/
  flock-you/
  WireTap-32/
  drone-mesh-mapper/
  new-cardputer-apps/

For a different layout, set a workspace root:

CYPHER_OS_WORKSPACE_ROOT=/path/to/repos ./tools/build-apps.sh

You can also override individual app paths:

CYPHER_OS_CARDPUTER_MPC_DIR=/path/to/cardputer-mpc ./tools/package-sd.sh
CYPHER_OS_CARDPUTER_TAROT_DIR=/path/to/cardputer-tarot ./tools/build-apps.sh
CYPHER_OS_CYPHER_PN532_DIR=/path/to/cypher-pn532 ./tools/build-apps.sh
CYPHER_OS_CYPHER_CHAT_DIR=/path/to/cypher-chat/cypher-chat-firmware ./tools/build-apps.sh
CYPHER_OS_CYPHER_DRIVE_DIR=/path/to/cypher-drive ./tools/build-apps.sh
CYPHER_OS_ESP32_BT_HID_DIR=/path/to/ESP32_BT_HID ./tools/build-apps.sh
CYPHER_OS_ESP32_POKEDEX_DIR=/path/to/esp32-pokedex ./tools/build-apps.sh
CYPHER_OS_CYPHER_DESK_DIR=/path/to/cypher-desk ./tools/build-apps.sh
CYPHER_OS_FLOCK_YOU_DIR=/path/to/flock-you ./tools/build-apps.sh
CYPHER_OS_WIRETAP_DIR=/path/to/WireTap-32 ./tools/build-apps.sh
CYPHER_OS_DRONE_MESH_MAPPER_DIR=/path/to/drone-mesh-mapper ./tools/build-apps.sh
CYPHER_OS_CYPHER_AIRTAG_DIR=/path/to/cypher-airtag ./tools/build-apps.sh
CYPHER_OS_CARDPUTER_APP_BUNDLE_DIR=/path/to/new-cardputer-apps ./tools/build-apps.sh
CYPHER_OS_GAME_OS_DIR=/path/to/cardputer-game-os ./tools/build-apps.sh

Controls

, or ;: up
. or /: down
W/S and K/J: up/down alternatives
Enter or BtnA: select
Backtick, Del, Tab, or Q: back
R: reload SD catalog
The launcher plays short procedural cues for movement, select, back, toggles, and warnings. Use Settings -> Sound effects to turn them on or off.
Settings includes Boot behavior, Brightness, Sound effects, Theme, and Reload SD catalog.
The Theme setting cycles through built-in launcher themes stored in firmware: Neon Grid, Terminal, Amber CRT, Synthwave, and Ice. The selected theme is saved in Preferences and does not require an SD theme file.
In packaged apps, use the app's Return to Launcher item or Del/Q where shown. The app restarts, sets a one-shot return flag, and the launcher stays on the menu instead of auto-launching again.
Cardputer MPC: use Shift+Q to return to Cypher OS. Lowercase q remains an MPC pad trigger.
Cypher PN532: use the Return to Cypher OS main-menu item or press Del, Tab, backtick, or Q from the main menu.
ESP32 BT HID: press backtick, Esc, or Del from the top-level device list to return to Cypher OS.
ESP32 Pokedex: choose Return to Cypher OS from the home menu.
Flock You: open the mini menu, cycle to HOME, then press up/down to return.
WireTap-32: choose Launcher from the main menu, or type launcher / return over serial.
Drone Mesh Mapper: open the Launcher page, then press BtnA, Enter, or Space.
Cypher AirTag: press Back (Del) from the Home screen and confirm with Enter, or type return over serial.
Cardputer App Bundle apps: use the documented app menu item or Fn+Del where shown in the catalog. News Reader reads Wi-Fi and Guardian API settings from /news-reader/config.txt on SD.

Serial Commands

help
status
apps
reload
launch
erase
install <slug>

Technical Notes

This repo is Arduino CLI only.
Target hardware is the M5Stack Cardputer ADV.
The supported launch model is local SD catalog install into the app partition, then reboot.
Keep the launcher small and local: no online OTA catalog, WebUI, USB mass storage, multi-board ports, PlatformIO, or ESP-IDF project files.
The shared data partition is LittleFS so Cypher Drive can mount its log/config storage when launched from this OS.
Boot behavior can auto-try the installed app on power-up or always stop at the launcher menu.
Cypher PN532 expects a PN532 module in I2C mode on the Cardputer ADV EXT header: VCC to pin 6 5VOUT, GND to pin 4 GND, SDA to pin 8 G8, and SCL to pin 10 G9; leave PN532 RESET, INT, and BUSY unconnected for this build.

Read the full README on GitHub

source github.com/dkyazzentwatwa/cypher-puter-os