Add README.md

README.md

@@ -0,0 +1,230 @@
+# **Kscribe (penpad) — Native Kindle Scribe Notepad**
+
+`simplenotes` is a **fully native drawing and note-taking application for the Kindle Scribe**, written in C and built directly on top of:
+
+* `/dev/input/stylus`
+* `/dev/input/touch`
+* `/dev/fb0` (8-bit grayscale framebuffer)
+* direct eInk refresh via `eips`
+* custom PBM + PNG export (LodePNG)
+
+It runs without the Kindle framework interfering by exclusively grabbing stylus and touch events.
+The code is optimized for **real-time drawing**, **fast refresh**, and **full-screen handwriting**.
+
+---
+
+## **Features**
+
+### **Drawing**
+
+* Smooth line drawing using Bresenham.
+* Adjustable stroke thickness (`STROKE_PX`).
+* Fast thick-point rasterization optimized for eInk.
+* Top-bar protected region to prevent accidental strokes.
+
+### **Input Mapping**
+
+* Fully calibrated raw stylus → pixel mapping.
+* Reversed X and inverted Y axes (matching Scribe hardware).
+* Touch and stylus suppressed from the framework using `EVIOCGRAB`.
+
+### **Saving & Loading**
+
+* **PBM Save:** 1-bit `P1` PBM file (`latest.fb`) stored at:
+  `/mnt/us/extensions/simplenotes/bin/latest.fb`
+* **PNG Export:** full-resolution PNG saved with timestamp to:
+  `/mnt/us/simplenotes/note-YYYYmmdd-HHMMSS.png`
+* **Load on startup:** pass a PBM file as `argv[1]` to restore a page on launch.
+
+### **Gesture Controls**
+
+Gestures are based on **double-tap with the stylus**:
+
+| Region       | Gesture    | Action               |
+| ------------ | ---------- | -------------------- |
+| Top-left     | double-tap | Save PBM + PNG       |
+| Top-right    | double-tap | Exit the program     |
+| Bottom-right | double-tap | Reset page (no save) |
+
+Gesture detection uses a 2-second timing window.
+
+### **UI**
+
+* Title bar drawn using `eips`.
+* PNG icons (`exit.png`, `reset.png`, `save.png`) shown via `eips -g`.
+* Automatic refresh throttling (`REFRESH_INTERVAL_MS`).
+
+---
+
+## **Directory Layout**
+
+```
+/mnt/us/extensions/simplenotes/
+│
+├── bin/
+│   ├── simplenotes (compiled binary)
+│   └── latest.fb              # always overwritten on save
+│
+├── assets/
+│   ├── exit.png
+│   ├── reset.png
+│   └── save.png
+│
+└── (other KUAL metadata)
+```
+
+User-visible notebooks (PNG exports):
+
+```
+/mnt/us/simplenotes/note-YYYYmmdd-HHMMSS.png
+```
+
+---
+
+## **Build Instructions**
+
+### Requirements
+
+* GCC for ARM (Kindle cross-compile) or KindleToolchain.
+* LodePNG included in source tree.
+* A jailbroken Kindle Scribe with:
+
+  * **KUAL**
+  * **USBNet / SSH**
+
+### Compile (on device or cross-compiled)
+
+```sh
+gcc -O2 -std=c99 penpad_fb2.c lodepng.c -o simplenotes
+```
+
+Copy into the extension directory:
+
+```sh
+scp simplenotes root@kindle:/mnt/us/extensions/simplenotes/bin/
+```
+
+Ensure executable bit:
+
+```sh
+chmod +x /mnt/us/extensions/simplenotes/bin/simplenotes
+```
+
+---
+
+## **Running**
+
+### Launch normally (clean page)
+
+```sh
+./simplenotes
+```
+
+### Launch with a PBM document restored
+
+```sh
+./simplenotes page.pbm
+```
+
+---
+
+## **Controls**
+
+### Drawing
+
+Just use the stylus.
+Drawing **stops** in:
+
+* the top gesture bar (`TOPBAR_H`)
+* the UI icon region
+
+### Gestures
+
+All gestures require **two quick pen-down events** in the target zone.
+
+| Gesture                 | Behavior                                |
+| ----------------------- | --------------------------------------- |
+| Top-left double-tap     | Save PBM + PNG, clear screen, redraw UI |
+| Top-right double-tap    | Exit program                            |
+| Bottom-right double-tap | Reset page without saving               |
+
+---
+
+## **File Formats**
+
+### PBM Export
+
+* 1-bit P1 format
+* Always stored as `/mnt/us/extensions/simplenotes/bin/latest.fb`
+* Useful for restoring a session exactly
+
+### PNG Export
+
+* Real 8-bit grayscale → 32-bit RGBA PNG conversion via LodePNG
+* Timestamped filename
+* Stored in `/mnt/us/simplenotes/`
+
+---
+
+## **Technical Overview**
+
+### Framebuffer
+
+* Reads framebuffer geometry via `FBIOGET_FSCREENINFO` + `FBIOGET_VSCREENINFO`
+* Maps `/dev/fb0` using `mmap`
+* Writes raw grayscale values directly:
+
+  * `0x00` = black
+  * `0xFF` = white
+
+### Internal Bitmap
+
+* Maintains a full-screen 1-bit buffer `g_bitmap`
+* Used for PBM and PNG export
+* Updated simultaneously with framebuffer writes
+
+### Refresh Model
+
+* Partial refresh every `REFRESH_INTERVAL_MS`
+* Full refresh on demand:
+
+  ```c
+  system("eips -r");
+  ```
+
+---
+
+## **Known Limitations**
+
+* No undo/redo (possible future enhancement).
+* No multi-page notebook support.
+* PNG rendering limited by Kindle CPU; PBM much faster.
+* `eips -g` sometimes logs a harmless “barcode missing” warning.
+
+---
+
+## **Future Extensions**
+
+These are explicitly listed in the project notes and remain possible next steps:
+
+* Undo / Redo system
+* Multi-page notebook (page stack)
+* Layer support
+* Pressure sensitivity
+* PNG import
+* fbink integration for faster partial refresh
+* UI overlay mode
+* Eraser tool
+
+---
+
+## **License**
+
+MIT License (recommended, adjust if needed).
+
+---
+
+## **Credits**
+
+Developed by **maru21**
+Testing, calibration, and optimization performed directly on Kindle Scribe hardware.