roro9stack/docs/milestones/F1.md

F1 — Files and Notes

Status: in progress. The Storage App (issue #3) shipped as v0.9.0 on 2026-10-06. Notes (#19) is built and checked on the device, on branch notes, not merged yet. The card as a USB drive (#1) comes after.

Goal: get at what's on the SD card from the device itself: browse it, look inside the files the firmware writes, copy, move, rename and delete, and keep notes. A side milestone, like G1 and S1; Files and Notes were M3's original second half (Q30, Q89).

The Storage App (issue #3)

Until now the card could be looked at only through the Debug Console (ls, get, put), and Settings > Storage could only delete whole categories by age.

On the card today: six top-level folders, irc, wifi, updates, gnss, gemini and captures. No notes yet; settings are in flash, not on the card.

Decisions (design round 2026-10-06)

#	Decision
Q128	An App of its own, Storage, in the Launcher. Settings > Storage goes away: its usage figures, Storage Clean-up and "Erase SD card" move into the App, under Maintenance, behind a warning that these delete things for good.
Q129	A row shows the name, then the size or "folder", then the date modified. Folders first, then by name; s cycles the sort (name, date, size). The top line shows the path and the card's free space.
Q130	Nothing is hidden. Read-only: /gemini/cache; any file the firmware has open right now (today's IRC log, a Track or Capture being recorded, a file being received); and the top-level folders themselves, which can't be renamed or deleted though their contents can. Everything else, the user's own data included, can be renamed, moved or deleted, always after a confirmation.
Q131	One item at a time, with a clipboard: Enter opens; Back goes up, and leaves the App at the top; c copy, x cut, v paste into the current folder; r rename; d delete; n new folder; i details.
Q132	Copy, move and delete work on folders too, recursively. The confirmation says what's inside: "Delete saved and its 42 files?".
Q133	A copy is a job on the storage task in 4 KB pieces, with a progress Toast; Back cancels it. It checks free space first and asks before replacing anything. Afterwards the sizes are compared, not the contents: the driver is trusted since v0.6.1 (ADR 0007). A move within the card is a rename.
Q134	Viewers by type. Text (.txt, .log, .gmi, .csv, .gpx, and anything that looks like text): read from the card as you scroll, so size doesn't matter; logs open at the end. .pcap: the LoRa Scanner's packet list. .gpx: a summary (start, duration, points, distance), Tab for the text. .ota: version, size, whether the signature is valid; Enter installs through Update from SD. Anything else: a hex dump.
Q135	No editing: that comes with Notes (#19).
Q136	A listing holds up to 256 entries, packed, about 10 KB; a bigger folder shows the first 256 by name and says how many more there are. The App refuses to open below the memory floors (Q86).
Q137	The Clock also sets the system time, so files are dated correctly with GNSS alone and not only after NTP. A file dated before 2020 shows "-".
Q138	Console: cp, mv and mkdir, next to ls and rm.
Q139	Left out, each with its issue: selecting several items (#41), finding files by name (#42), opening a .gmi in the Gemini App (#43), a table view for .csv (#44), images (#45).
Q140	Ships as v0.9.0 when done and checked.

Done when

• The Storage App lists any folder of the card with sizes and dates, sorted three ways, and says so when a folder has more than 256 entries.
• A file can be copied, moved, renamed and deleted, and a folder too; a new folder can be made. Each destructive action asks first; a copy shows progress and can be cancelled.
• The read-only rules of Q130 hold, with a reason given when something is refused.
• Each viewer of Q134 opens its type, and a 1 MB text file scrolls without loading whole.
• Maintenance shows the card's usage and does what Settings > Storage did, behind its warning; Settings no longer has a Storage row; the Storage Warning points at the Storage App.
• A file written with only a GNSS Fix (no Wi-Fi) is dated correctly.
• Free heap stays above the floors with the App open, Wi-Fi and IRC on TLS.

Work breakdown

1. Model (host-tested): paths and names, the read-only rules, the packed listing and its sorts, file types, sizes and dates for display, the GPX summary.
2. Card operations: listing a folder, copy, move, delete (recursive, counted), new folder, as storage jobs with progress and cancel; cp, mv, mkdir; the Clock sets the system time.
3. The App: browsing, the clipboard, dialogs, details.
4. Maintenance: usage, Clean-up and Erase moved in from Settings, with the warning.
5. Viewers: text, hex, .pcap, .gpx, .ota.
6. Checks on the device, recorded here.

As built

• FileOps (src/services/file_ops) does the card's work for the App and for the console alike: list, count, copy, move, delete, new folder. One operation at a time on the storage task, in turns of about 150 ms that queue themselves again, so Log lines and a Capture are written in between. The rules of Q130 are checked there, whoever asks.
• A listing reads the folder straight from FatFs. Through the Arduino File, every entry was looked up by name again for its size and again for its date: 329 entries took over two seconds. One pass now, and it's there before the screen has redrawn. Counting, copying and deleting still walk with File; they show progress and can be stopped.
• A copy shows its progress in a box in the App, not a Toast (Q133): it has a bar and says Back cancels. A cancelled or failed copy deletes what it had written. The copy gets today's date, like cp.
• The viewers (src/apps/file_viewer, models in lib/files): text through TextPager, which reads about a kilobyte around the screen and wraps at spaces, 38 columns; going back a line wraps the paragraph before again, so a file reads the same in both directions. A .pcap, a .gpx and an .ota are read through once by a storage job, in the same 150 ms turns. An Update File is fed to the installer's own parser with a sink that writes nothing, so "would it install" is the same answer an install gives.
• Tab in a viewer shows the same file as hex, or as text (not in Q134).
• Maintenance is the last row at the top of the card, and m anywhere in the App. It's the old Settings > Storage page behind a dialog.
• The Storage Warning was only ever a Toast; "selecting it opens Storage Clean-up" (CONTEXT.md) was never built. It now reads "SD card over 80% full: see Storage".
• Console: cp, mv, mkdir (Q138), and rm and du through the same code, so rm now takes folders and follows the rules; ls shows dates. Debug Builds: sd fill <folder> <count> makes test files.

Checks on the device (2026-10-06, v0.8.1-2 Debug Build)

All in a scratch folder, /f1test, removed afterwards.

Check	Result
Host tests	424 pass (411 before the viewers' models)
Browsing	Folders first, sizes and dates, the three sorts; a 300-file and a 329-file folder show "first 256 of 300" and "of 329"
New folder, rename, copy, cut and paste, delete	Each works on a file and on a folder; a copy next to its original is named (2); a name in the way asks "Replace it?"
A folder of 11 files, 8.4 MB, copied	19.4 s, 435 KB/s, the bar moving; two Log lines queued meanwhile were written
The same copy cancelled at 1.8 MB	"Cancelled: nothing was copied", and nothing was left behind
Delete	341 files in 9.7 s; the dialog had counted them first
Read-only rules	/irc, /gnss (top-level folders), /, /gemini/cache and a folder made inside it, a folder into itself, a name with :; a Capture being recorded and the folder holding it; a folder under /irc while IRC runs. Each refused with its reason; the Capture could still be copied
Text	A 1 MB log opens at its last line at once; top, pages, lines; a file without an extension that looks like text opens as text
Hex	A 5 KB binary file; Tab from any other viewer
.pcap	A LoRa Capture: 3 packets as the Scanner lists them, Enter shows the Meshtastic header and bytes
.gpx	400 points: start, 33 min 15 s, 4.68 km; Tab shows the text
.ota	A signed file: version, "intact", "older than what's running", Enter asks to install (not confirmed). A tampered one: "image corrupted (hash mismatch)"
Maintenance	The warning, then usage, Clean-up's categories and Erase (not run)
Date with GNSS only	NTP pointed at an address that doesn't answer, restart: the Clock came from the Fix, and a folder made then is dated 2026-10-06 08:39. A Track from the day before, written the same way by v0.8.1, shows "-"
Memory	IRC connected, the App open on 256 entries: 61 KB free (70 KB before opening). Lowest since boot 29.7 KB, during IRC's TLS handshake
Stacks	storage 3.1 KB free of 6 KB at worst, loopTask 1.5 KB

Not checked by hand: how the keys feel on the device itself; everything above was driven through the Debug Console's key command and screenshots.

One slip during the checks: a scripted key sequence ran in the wrong folder and renamed /gemini/saved to saved2, then copied it to the top of the card. Both were put right at once (renamed back, the copy deleted; 7 files, 53,798 bytes, as before).

Found on the way: a panic at Wi-Fi join, there since v0.7.0 (SNTP started twice, issue #46). Fixed in v0.9.0.

Notes (issue #19)

Plain text notes on the SD card, written on the device. Q30 settled the base: .txt files in /notes, created, edited and deleted from the device, never offered by Storage Clean-up.

Decisions (design round 2026-10-06)

#	Decision
Q141	A Notes App in the Launcher. One row per note: its first line as the title, then the date. Newest first; s switches to by name. n new, Enter opens, d deletes after a confirmation, r renames the file.
Q142	A new note's file name is never typed: it comes from the first line when the note is first saved (shopping-list.txt), or note-20261006-0919.txt if that line is empty. It doesn't change afterwards unless the note is renamed.
Q143	Autosave, no "discard changes?" prompt: five seconds after the last key, on leaving the note or the App, and when the screen turns off. A save writes a temporary file and renames it over the note, so a power cut loses the last few seconds at most. A temporary file left behind is offered back at the next open.
Q144	The whole note is in memory while it's edited, up to 16 KB. A bigger text file opens read-only in the Storage App's viewer. The App refuses to open below the memory floors (Q86). Editing files of any size must come in a later release: issue #47.
Q145	The editor wraps at spaces, 38 columns by 8 rows, with a line for the name and the state. Enter is a new line, Del deletes backwards, Fn+arrows move (the Text Entry rule), Ctrl+A and Ctrl+E go to the start and the end of the line, Tab types two spaces, Back saves and returns. The Compose Key works as elsewhere.
Q146	The Storage App's text viewer gets e: edit this file with the same editor, for a text file up to 16 KB that isn't read-only. That lifts Q135 without Apps opening each other (#43 stays).
Q147	The list is flat: the files directly in /notes. Sub-folders are reached through the Storage App.
Q148	UTF-8, LF line ends; a file with CRLF is saved back with LF. Characters the font lacks are kept on save.
Q149	Left out, each with its issue: editing files of any size (#47), searching inside notes (#48), undo (#49), selecting and copying text (#50).
Q150	Ships as v0.10.0 when built and checked on the device.

Done when

• A note can be started, typed with accents, left and found again in the list under its first line; renamed; deleted after a confirmation.
• What's typed is on the card five seconds after the last key, and after Back, Home, or the screen turning off, without a prompt.
• Pulling the power while typing loses a few seconds at most, and the note is never left empty or half-written.
• The cursor moves by character and by line through wrapped text, and the screen follows it; a 16 KB note edits without lag.
• A note at 16 KB refuses more text and says so; a bigger file opens read-only.
• e in the Storage App's text viewer edits a file; a read-only one is refused with its reason.
• Free heap stays above the floors with a 16 KB note open and IRC connected.

Work breakdown

1. Model (host-tested): the text buffer with its cursor, wrapping and scrolling; file names from first lines.
2. The editor on the device: loading, drawing, keys, autosave through a temporary file, recovery.
3. The Notes App: the list with titles, new, rename, delete.
4. e in the Storage App.
5. Checks on the device, recorded here.

As built

• NoteText (lib/notes, host-tested) is the text, its cursor and the screen around it. A line owns the space or the newline it ends with, so every byte is on exactly one line and the cursor has one place for each. No index of lines is kept: a note of newlines alone would need twice its own size for one. Where a line starts is worked out from the start of its paragraph.
• One buffer, 16 KB, for as long as the editor is open. It's reserved when the note is opened, the file is read straight into it, and typing never makes it grow. On this device a failed allocation is an abort, and with IRC connected the largest free block is about 31 KB whatever the total says: the first version read the file into one string and copied it into another, and opening a full note with IRC connected restarted the device. The editor now also refuses to open without a free block of 24 KB.
• NoteEditor (src/apps/note_editor) is shared by the Notes App and the Storage App's e. A save runs on the storage task while the main loop waits for it: no second copy of the note, and at 16 KB the wait is a fraction of a second at a moment when nobody has typed for five.
• A save writes <note>.tmp, checks its size, deletes the note and renames the temporary file (FAT can't rename onto a file). A cut between the last two steps leaves only the .tmp: the Notes list puts such a file back under its name. A .tmp next to its note is an unfinished save: opening the note offers it.
• Titles in the list are read from the card for the eight rows on screen, when the list moves.
• Before powering off, the firmware now leaves the foreground App (PowerService::beforePowerOff), which makes the editor save.
• Shift or Alt with Fn+Up and Fn+Down moves a page (not in Q145).

Found on the way

• The screen could go "off" for one tick after a key sent through the Debug Console, and the next key was then swallowed as a wake-up: the key command stamps the power timer from millis(), the power tick compares with its pass's older time, and the unsigned difference read as 49 days idle. The same shape as #46. Fixed in PowerPolicy::update with a test. Keys from the keyboard were never affected. It explains remote keys "lost" in earlier sessions.
• scripts/rdbg.py held back piped lines written while it was still connecting, until the next line came (a buffered readline() behind select()). Fixed.

Checks on the device (2026-10-06, Debug Build of branch notes)

Test notes were made in /notes and removed afterwards; the folder is left, empty.

Check	Result
Host tests	439 pass
A first note	"No notes yet", n, typed three lines: the top line says "typing", then "saved" five seconds after the last key, under shopping-list.txt. 63 keys in a row all arrived
Leaving	Back saves and returns to the list, which shows the note under its first line. Home in the middle of a new note saved it as ideas.txt
The cursor	Down, Right, an insertion in the middle of a line; the screen scrolls through a note of about 230 lines
A power cut	Typed, waited seven seconds, typed more and restarted the device at once (reset): the note has what was saved, whole, and not the last keys
An unfinished save	A .tmp next to its note: "Unsaved copy... Keep the note / Use the copy"; using it brings its text back and saves it. A .tmp alone was put back under its name when the list opened
16 KB	A note of exactly 16,384 bytes opens and scrolls; one more character: "This note is full: 16 KB". A file of 16,398 bytes: "Too big to edit: 16 KB at most"
Rename, delete, sort	r renamed orphan.txt to orphan2.txt; d asked, then deleted; s switched between newest first and by file name
e in the Storage App	A note opened from the text viewer, edited, saved on Back; the listing shows its new size
Memory	IRC connected, the full 16 KB note open: 55 KB free, largest block 31.7 KB (72 KB free before opening)

Not checked: accents through the Compose Key and Ctrl+A / Ctrl+E (the remote key command can't send them; the model's tests cover both), the power button's save (it needs a hand on the device), a missing card, and how typing feels on the keyboard itself.

One slip during the checks: a key sequence sent right after a restart opened IRC instead of Notes, and the test letters went into IRC's input line. Nothing was sent: the line was cleared and the App left. IRC connected to Libera as it does when opened.