A fork of pulp-os for the xteink4 adding custom apps
readme update
+39
-101
+39
-101
README.txt
+39
-101
README.txt
···
1
1
ABOUT
2
-
pulp-os - bare-metal e-reader firmware for the XTEink X4
2
+
pulp-os is a bare-metal e-reader firmware for the XTEink X4
3
3
4
4
Embedded e-reader operating system targeting the XTEink X4 board
5
-
(ESP32-C3 + SSD1677 e-paper). Written in Rust. No OS, no std,
6
-
no framebuffer. Async runtime provided by Embassy via esp-rtos.
5
+
(ESP32-C3 + SSD1677 e-paper). Written in Rust. No std no framebuffer.
6
+
Async runtime provided by Embassy via esp-rtos.
7
7
8
8
HARDWARE
9
9
MCU ESP32-C3, single-core RISC-V RV32IMC, 160 MHz
···
23
23
24
24
BUILDING
25
25
Requires stable Rust >= 1.88 and the riscv32imc-unknown-none-elf
26
-
target. rust-toolchain.toml handles both automatically.
26
+
target. rust-toolchain.toml handles both automatically.
27
27
28
28
cargo build --release
29
-
cargo espflash flash --release --monitor
29
+
espflash flash --monitor --chip esp32c3 /path/to/target/image
30
+
31
+
or
32
+
33
+
cargo run --release
30
34
31
35
FEATURES
32
36
txt reader lazy page-indexed, read-ahead prefetch
···
53
57
Power (short) open quick-action menu
54
58
Power (long) deep sleep
55
59
56
-
SD CARD LAYOUT
57
-
/ root; place .txt and .epub files here
58
-
/_PULP/ app data (created at boot)
59
-
/_PULP/SETTINGS.TXT settings (key=value text, editable)
60
-
/_PULP/BKMK.BIN bookmarks (16 slots x 48 bytes)
61
-
/_PULP/TITLES.BIN title index (append-only, tab-separated)
62
-
/_PULP/RECENT.BIN last opened filename
63
-
/_PULP/<hash>/ epub chapter cache directories
64
-
65
-
SETTINGS.TXT format (lines starting with # are ignored):
66
-
sleep_timeout=10 minutes idle before sleep; 0 = never
67
-
ghost_clear=10 partial refreshes before full GC
68
-
book_font=1 0=Small 1=Medium 2=Large
69
-
ui_font=1 0=Small 1=Medium 2=Large
70
-
wifi_ssid=MyNetwork SSID for upload mode
71
-
wifi_pass=secret password for upload mode
72
-
73
-
Bookmark slot layout (48 bytes each):
74
-
0:4 name_hash FNV-1a of filename
75
-
4:4 byte_offset file/chapter position
76
-
8:2 chapter epub chapter; 0 for txt
77
-
10:2 flags bit 0 = valid
78
-
12:2 generation LRU counter
79
-
14:1 name_len
80
-
15:1 pad
81
-
16:32 filename
82
-
83
-
SOURCE LAYOUT
84
-
src/
85
-
bin/main.rs async entry point, event loop, rendering
86
-
lib.rs crate root
87
-
kernel/
88
-
tasks.rs spawned tasks (input, housekeeping, idle)
89
-
wake.rs uptime helper
90
-
board/
91
-
mod.rs SPI/DMA init, peripheral wiring
92
-
action.rs semantic actions, button-to-action mapper
93
-
button.rs button enum, ADC ladder decode
94
-
raw_gpio.rs register-level GPIO for unmapped pins
95
-
drivers/
96
-
ssd1677.rs e-paper controller driver
97
-
strip.rs 4 KB strip render buffer (no framebuffer)
98
-
input.rs debounced ADC + GPIO input, long press, repeat
99
-
sdcard.rs SD card over SPI, FAT volume manager
100
-
storage.rs file ops, directory cache, _PULP helpers
101
-
battery.rs ADC-to-mV, discharge curve LUT
102
-
fonts/
103
-
mod.rs font selection, FontSet (regular/bold/italic)
104
-
bitmap.rs 1-bit glyph blit, string measurement
105
-
ui/
106
-
widget.rs Region, Alignment, wrap helpers
107
-
bitmap_label.rs proportional-font label widgets
108
-
statusbar.rs top bar, stack painting, heap stats
109
-
quick_menu.rs overlay menu (cycle + trigger actions)
110
-
button_feedback.rs edge button labels
111
-
apps/
112
-
mod.rs App trait, Launcher nav stack, Services
113
-
home.rs launcher menu + bookmark browser
114
-
files.rs paginated SD file browser
115
-
reader.rs txt + epub reader
116
-
settings.rs persistent settings editor
117
-
upload.rs wifi HTTP upload server
118
-
bookmarks.rs RAM-resident bookmark cache
119
-
120
-
smol-epub/ no_std epub parser crate
121
-
src/
122
-
zip.rs ZIP central directory, streaming DEFLATE
123
-
xml.rs minimal XML tag/attribute scanner
124
-
css.rs CSS property parser
125
-
epub.rs container.xml, OPF spine, NCX/NAV TOC
126
-
html_strip.rs streaming HTML-to-styled-text converter
127
-
cache.rs chapter decompress + strip pipeline
128
-
png.rs PNG decoder, Floyd-Steinberg dither
129
-
jpeg.rs JPEG decoder, Floyd-Steinberg dither
130
-
131
-
build.rs TTF rasterisation, linker config
132
-
assets/fonts/ source TTFs (Regular, Bold, Italic)
133
-
134
60
RUNTIME ARCHITECTURE
135
61
Embassy async executor on esp-rtos. Four concurrent tasks:
136
62
···
141
67
142
68
CPU sleeps (WFI) whenever all tasks are waiting.
143
69
144
-
DESIGN NOTES
145
-
No dyn dispatch. The with_app!() macro statically dispatches to
146
-
each concrete app struct. No vtable, no heap indirection.
70
+
NOTES
71
+
No dyn dispatch. with_app!() macro matches AppId, expands to
72
+
concrete calls per app struct. All monomorphised; no vtable.
147
73
148
-
Apps never touch hardware. All I/O goes through the Services
149
-
handle passed to on_work(). Clean syscall boundary.
74
+
Apps never touch hardware. Services mediates all I/O (SD, dir
75
+
cache, bookmarks) and is only passed in via on_work().
150
76
151
-
Strip-buffered rendering. The display is driven in 4 KB horizontal
152
-
strips (40 rows each, 12 strips total) instead of a 48 KB
153
-
framebuffer. Widgets draw to logical coordinates; the strip
154
-
buffer handles rotation and clipping.
77
+
Dirty-region tracking. Apps call ctx.mark_dirty(region); regions
78
+
are unioned per frame. Partial DU or full GC issued accordingly.
79
+
80
+
Strip rendering. 12 x 40-row strips (4 KB each) instead of a
81
+
48 KB framebuffer. Draw callback fires per strip during DMA.
82
+
Windowed mode for partial refresh; widgets use logical coords.
83
+
84
+
Heavy statics. Large structs live in ConstStaticCell / StaticCell
85
+
so the async future stays ~200 B. Taken once, passed as &'static mut.
86
+
87
+
Nav stack. Launcher holds a 4-deep AppId stack. Transitions
88
+
(Push/Pop/Replace/Home) drive on_suspend / on_enter lifecycle.
89
+
90
+
Quick menu. Power button opens a per-app overlay; drawn inline
91
+
during the strip pass. Refresh and go-home always available.
92
+
93
+
Heap budget. 140 KB heap; used only for epub chapter text and
94
+
image decode (alloc::vec). Peak ~79 KB. Rest is stack/static.
155
95
156
-
Heavy statics in .bss. Large structs (ReaderApp, StripBuffer,
157
-
BookmarkCache) are placed in static storage via ConstStaticCell
158
-
so the async future stays small (~200 B).
96
+
smol-epub. Companion no_std crate: ZIP/DEFLATE, OPF spine,
97
+
streaming HTML strip, 1-bit Floyd-Steinberg PNG/JPEG decoders.
98
+
All I/O via generic read closure; storage-agnostic.
159
99
160
-
Partial refresh owns the render path. Apps call mark_dirty(region)
161
-
for targeted updates. Full GC refresh is forced periodically and
162
-
on screen transitions. DU waveform runs concurrently with input
163
-
processing and page prefetch.
100
+
Input. ADC ladders sampled at 100 Hz, debounced, long-press and
101
+
repeat detected in driver. ButtonMapper maps to semantic actions.
164
102
165
-
Heap is used only for EPUB chapter text and image decode buffers
166
-
(alloc::vec). Everything else is stack or static.
103
+
Fonts. build.rs rasterises TTFs via fontdue into 1-bit bitmaps
104
+
at three sizes. Book and UI sizes independently hot-swappable.
167
105
168
106
LICENSE
169
107
MIT