ESP32 Cleaner 1.2.0

CCleaner for your SD card, running on the Cardputer itself. It scans the card, groups what it
found by pack, and removes only what you tick.

One image runs on the Cardputer ADV and the original Cardputer. The firmware detects
the board at runtime.

Install

From a computer, flash esp32-cleaner-1.2.0-cardputer-factory.bin at offset 0x0:

esptool.py --chip esp32s3 write_flash 0x0 esp32-cleaner-1.2.0-cardputer-factory.bin

From M5Launcher, copy esp32-cleaner-1.2.0-cardputer.bin onto the SD card and start it from
the launcher.

From source, run pio run -e cardputer -t upload.

Your pack settings from 1.1 carry over on the first boot.

Rules

• New Android junk pack, on by default. It matches LOST.DIR, .trashed-* and
  .pending-*.
• New NAS junk pack, on by default. It matches @eaDir, #recycle, .@__thumb,
  .AppleDouble and .AppleDB.
• New Dev caches pack, off by default. It matches __pycache__, *.pyc, .pytest_cache,
  .mypy_cache and .ruff_cache.
• New Empty folders and Empty files packs, both off and marked risky. They match on
  content, not on a name, and apply only to items no other rule matched. An empty .DS_Store
  still counts as macOS junk.
• The confirm screen names the risky packs in the clean. It used to say "logs and temp files"
  whatever the pack.
• The firmware saves each pack's switch under the pack's name. It used to keep one bitmask
  indexed by position, which any new pack would have shifted. The first boot of 1.2 carries
  your 1.1 settings over.

Fixes

• Cleaning a folder with thousands of files could run out of memory. The firmware listed
  the whole folder into RAM before deleting anything. It now clears folders 64 entries at a
  time, and esc stops the clean inside a large folder instead of after it.
• A full card was reported as "Out of memory". The scan now tells a failed write to the
  card apart from a full heap, and says the card is full only when it is.
• Editing rules on the device threw away the file's comments. It also dropped every line
  the parser skipped, including rules past the 64th. The firmware now copies the file line by
  line and changes only the rule you added or deleted.
• Saving rules was not power-safe. The firmware removed the old file before writing the
  new one. It now writes the new file in full first, and finishes an interrupted save on the
  next boot.
• The confirm screen could hide "Press Enter again to delete." under the footer in the
  normal text size. The screen now sizes the warning and that line first, and shows fewer pack
  rows when space is short.
• Only f, d and a count as target letters in /sdcleaner.rules. The line x y used to
  become the pattern y.
• A line longer than the read buffer no longer spills into the next rule.
• A UTF-8 byte-order mark from Windows Notepad no longer breaks the first rule.

Project

• The rules-file line parser is a separate module, rulefile, and pio test -e native
  covers it.
• tools/seed-test-card.sh adds Android, NAS and dev junk, an empty folder, zero-byte files, a
  folder holding only junk, which must not count as empty, and a junk folder with 5000 files.

Full changelog: v1.1.0...v1.2.0

ESP32 Cleaner 1.1.0

CCleaner for your SD card, running on the Cardputer itself. Scans the card,
shows what it found grouped by category, and removes only what you tick.

Works on the Cardputer ADV and the original Cardputer — one image, the
board is detected at runtime.

Install

From a computer — flash esp32-cleaner-1.1.0-cardputer-factory.bin at offset 0x0:

esptool.py --chip esp32s3 write_flash 0x0 esp32-cleaner-1.1.0-cardputer-factory.bin

From M5Launcher — copy esp32-cleaner-1.1.0-cardputer.bin onto the SD card and pick it
from the launcher.

From source — pio run -e cardputer -t upload

Interface

• The highlighted path in the per-item list now scrolls. Every row used to be squeezed
  through a tail-preserving ellipsis, which on a 240x135 panel leaves about eighteen
  characters — enough to read ...cache/thumb.db, not enough to tell which of five cache
  directories it came from. The selected row now holds at the head, scrolls left at seven
  glyphs a second, holds with the tail visible, and starts over. Rows that fit do not move,
  and unselected rows keep the static ellipsis.

Project

• ui::marquee is a general widget, and the phase arithmetic behind it (ui::marqueeOffset)
  lives in layout.cpp with the rest of the host-testable geometry — covered by
  pio test -e native for the end holds, the ramp, the cycle wrap and degenerate input.
  Drawing is clipped to the column and copies only the glyphs that can land inside it, so a
  440-character path costs the same per frame as a short one.

Full changelog: v1.0.0...v1.1.0

ESP32 Cleaner 1.0.0

CCleaner for your SD card, running on the Cardputer itself. Scans the card,
shows what it found grouped by category, and removes only what you tick.

Works on the Cardputer ADV and the original Cardputer — one image, the
board is detected at runtime.

Install

From a computer — flash esp32-cleaner-1.0.0-cardputer-factory.bin at offset 0x0:

esptool.py --chip esp32s3 write_flash 0x0 esp32-cleaner-1.0.0-cardputer-factory.bin

From M5Launcher — copy esp32-cleaner-1.0.0-cardputer.bin onto the SD card and pick it
from the launcher.

From source — pio run -e cardputer -t upload

Rules

• Junk is described by glob patterns (*, ?, [a-z], [!abc]) instead of the previous
  exact-match / prefix-match pair. Matching is case-insensitive by default, since FAT volumes
  are; there is a switch in Settings for the strict reading.
• Patterns are grouped into packs: macOS, Windows and Linux junk are enabled by default;
  Logs & temp (*.log, *.tmp, *.bak, …) ships disabled, because unlike the rest it
  can delete real user data. When it does contribute to a clean, the confirmation says so and
  asks a second time.
• Custom rules live in /sdcleaner.rules on the card — plain text, editable on a computer,
  so a board with no keyboard can still be configured. Devices that can type get an on-device
  editor. A pattern of only * and ? is refused; it would match the whole card.
• Pack toggles, dry run, case sensitivity and text size persist in NVS.

Interface

• Layout is derived from the display at runtime rather than hardcoded for one 240×135
  panel, and text size scales with the ratio of glyph size to panel size.
• Results open as a summary grouped by pack — the fix for scrolling a flat list of
  thousands — and drill into a filtered per-item list showing each item's size.
• New: rules browser, per-pack pattern lists, on-device rule editor.
• Scans and cleans can be cancelled while running.
• Higher-contrast palette; the previous mid-grey secondary text and near-invisible selection
  bar were both hard to read on a small panel.
• Key hints use each board's own key names via hal::Caps, and arrows are drawn as glyphs so
  they render whatever font is loaded.

Fixes

• Rule indices past 9 corrupted the scan manifest. The index was written with %d but read
  back as a single digit, so the tenth rule silently broke every line. Now parsed properly —
  this was what capped the rule table at nine entries.
• A failed offset push could delete an unticked file. runClean walks the manifest
  sequentially and indexes the selection bitmap by line ordinal, so a line written without a
  matching offset shifted every later item's selection by one. Partial lines are now rolled
  back.
• A single over-long path aborted the whole scan with a misleading out-of-memory message.
  Such entries are now skipped, counted, and reported.
• Key presses were dropped unless a modifier was held. The keyboard driver's change
  detection compares only how many keys are down and only updates on the calls it receives, so
  the same single key pressed twice looked unchanged. Edge detection is now done over the set
  of keys actually held.
• Held keys did not repeat, which made a long result list unusable. Movement keys now
  auto-repeat; actions deliberately do not.
• Reloading rules with no file present wiped the rules already in memory.
• /sdcleaner.rules could be listed and deleted by a scan.
• Footer text, the card usage label, wrapped paragraphs and list columns all overflowed the
  panel edge in various screens.
• The scan screen reported PSRAM 0K on boards that have no PSRAM.

Project

• Split from a single 949-line main.cpp into focused modules: rules, scanner, ui,
  layout, glob, manifest.
• Host tests (pio test -e native) for the glob matcher, the manifest record format and the
  layout arithmetic.
• tools/seed-test-card.sh writes a card with one of everything, including deliberate
  near-misses that must survive and a path too long to list.
• tools/grab-screenshots.py collects the README images from a running device; the same build
  checks scan and selection invariants on hardware.

---

Docs and screenshots: https://github.com/therezor/esp32-cleaner#readme