Skip to content

SESSION_LOG.md

Latest commit

 

History

History
136 lines (111 loc) · 8.21 KB

SESSION_LOG.md

File metadata and controls

136 lines (111 loc) · 8.21 KB

OpenPager Session Log

Session 1c — 2026-03-28 (display confirmed)

Goal

Correct display specs and rebuild simulator to match real hardware.

Key Finding

Display is NOT a 240x240 TFT. It's a 0.96" SSD1306 128x64 OLED with yellow-blue split and 4 built-in buttons (K1-K4). Brand: Great Bobot. I2C interface (GND, VCC, SCL, SDA).

Design Implications

  • Text budget drops from ~200 chars (240x240) to ~105 chars (128x64 at 6x8 font)
  • Yellow zone (top 16px) = natural status bar (time, signal, battery)
  • Blue zone (bottom 48px) = content (5 lines of text max)
  • U8g2 replaces LVGL — LVGL is overkill for monochrome, U8g2 is purpose-built
  • Inverted pixels (black-on-white) for selection instead of colored highlights
  • Every pixel matters — no padding, no decoration, no borders
  • Claude condensed output target: ~150 chars max (fits in 2 screen pages)
  • Message list: 1 line per message (direction + time + ~12 chars preview)
  • Paging with [1/3] indicator, not scrollbars

Work Done

  • Identified correct display from AliExpress listing screenshot
  • Rewrote simulator: 128x64 monochrome framebuffer, yellow-blue color zones, 5x7 bitmap font, 4x scale
  • Redesigned all screens for 128x64: Home, Message List, Message Detail, Capture, Sending, Error
  • Updated README.md and ARCHITECTURE.md with correct hardware specs
  • Simulator working: _prototype/pager-sim/pager_sim (make && ./pager_sim)

Decisions Changed

  • LVGL → U8g2 for display library
  • 240x240 color TFT → 128x64 monochrome OLED
  • Scroll indicators → Page numbers [1/3]
  • Multi-line message previews → Single line per message in list
  • 4 buttons are built into the OLED module PCB (K1-K4) — no separate button wiring needed

Session 1b — 2026-03-28 (continued)

Goal

Deep dive into existing pager projects, UI frameworks, and prototyping setup.

Work Done

  • Created OpenPager project folder with README.md, SESSION_LOG.md
  • Cloned Sentry Alert TX-1 ("Beeper OS") to _reference/ — full architectural analysis
  • Analyzed Sentry codebase: ScreenManager (push/pop stack), Screen lifecycle (enter/update/draw/exit), Component system (dirty tracking), InputRouter (long-press-back, auto-repeat, select-on-release), ThemeManager (PROGMEM), PowerManager (3-state sleep), RenderManager (dirty rects)
  • Researched LVGL for button-only nav: groups, keypad input, lv_menu with built-in back stack, lv_list + gridnav, lv_label word wrap modes
  • Surveyed all ESP32 pager projects: Sentry Alert TX-1 (best fork), Meshtastic device-ui (LVGL chat), MeshCore-Cardputer-ADV (chat bubbles), PCBWay Telegram Beeper (proven Telegram->OLED pattern)
  • Researched prototyping tools: Wokwi (browser ESP32 sim), LVGL PC Simulator (SDL on Mac), EEZ Studio (visual designer), sim.lvgl.io (browser LVGL)
  • Created ARCHITECTURE.md with full Sentry analysis and reuse/replace mapping

Key Findings — Sentry Alert TX-1

  • Uses custom framework on TFT_eSPI, NOT LVGL
  • Stack-based navigation (max depth 8) with push/pop/switch
  • 3 buttons: A=Up, B=Down, C=Select. Long-press any = Back.
  • Screen has STATIC draw regions (drawn once) + DYNAMIC regions (on data change) — smart rendering optimization
  • MenuContainer component handles scrollable menus with auto-layout
  • AlertNotificationScreen is a popup overlay pushed on top of any screen — good pattern for incoming messages
  • Power: ACTIVE → IDLE_DIM (10s) → DEEP_SLEEP. USB detection. Timer + button wake.
  • Clean, well-documented, ~10 files for core UI framework

Decision

LVGL is the better path for us — the message display and scrolling requirements are the hard part, and LVGL has lv_menu (nav stack), lv_list (scrollable), lv_label (word wrap), keypad groups all built in. Sentry's framework would require building all text handling from scratch.

However, Sentry's InputRouter pattern (long-press-back, auto-repeat, select-on-release) and PowerManager (3-state sleep) are worth studying and possibly porting.

Next Steps

  • Set up LVGL PC simulator on Mac (SDL) for rapid prototyping
  • Prototype message list → message detail navigation with keyboard
  • Try Wokwi with ESP32 + ST7789 240x240 + LVGL
  • Confirm exact hardware specs

Session 1 — 2026-03-28

Goal

Initial research and design exploration for the OpenPager device.

Assumptions

  • Display is a TFT (likely 240x240 ST7789) — UNCONFIRMED, need to check physical unit
  • ESP32 variant has camera + mic — need to confirm exact board model
  • OpenClaw is the AI backend, connected via Telegram bot
  • 4 physical buttons available for all navigation
  • Battery powered — capacity and runtime unknown
  • WiFi is the only connectivity (no BLE to phone, no cellular)

Work Done

  • Read and analyzed OpenCharm repo (https://github.com/kickingkeys/opencharm) — BLE bridge, Claude bridge, transcriber, feedback system
  • Researched display options: 128x64 OLED vs 240x240 TFT — text budgets, libraries, refresh characteristics
  • Researched Soberton WT-1209T buzzer — passive piezo transducer, ESP32 can drive directly via PWM, variable tones possible
  • Researched OpenClaw architecture — massive open-source AI gateway, native Telegram integration
  • Researched ESP32-to-Telegram communication — long polling, AsyncTelegram2 / raw ESP-IDF HTTP client
  • Designed button mapping: UP, DOWN, CAPTURE (press=photo, hold=record), SELECT/BACK
  • Designed dual output system: full response to Telegram chat, condensed version to pager display
  • Designed UI screens: Home, Message List, Message Detail, Capturing, Loading, Error
  • Researched LVGL for button-only navigation — groups, keypad input, lv_menu with built-in nav stack, lv_list + gridnav
  • Researched existing pager OS projects — Sentry Alert TX-1 (best fork candidate), Meshtastic, MeshCore-Cardputer-ADV
  • Researched alternative UI frameworks — GUIslice, OpenMenuOS, bare TFT_eSPI + state machine
  • Studied Pebble watch window stack pattern — best architectural reference for push/pop screen navigation
  • Identified prototyping tools — Wokwi (browser simulator), LVGL PC Simulator, EEZ Studio

Decisions Made

  • No voice activation — tried previously, didn't work. Push-to-talk only.
  • Flat chat view > nested folders — 2 levels (list -> detail) not 3 levels (date -> direction -> messages). Less button presses, more intuitive.
  • Dual output approach — don't try to fit full Claude responses on tiny screen. Condense separately.
  • LVGL is the leading UI framework choice — has everything needed built in (nav stack, lists, keypad input, scrolling text)
  • Sentry Alert TX-1 is the best fork candidate for the non-UI plumbing (ESP32+TFT setup, buttons, buzzer, sleep)

Open Questions

  • What exact TFT display do we have? (resolution, controller IC, interface)
  • What exact ESP32 board? (ESP32-S3? which variant? PSRAM?)
  • How does OpenClaw handle the dual-output routing? Skill/hook? Post-processing?
  • Two Telegram bots/channels vs one? (to avoid getUpdates conflict between OpenClaw and ESP32)
  • Battery capacity and target runtime?
  • Camera resolution and what image size to send via Telegram?

Learnings

  • 128x64 OLED = ~64 readable chars per screen. 240x240 TFT = ~200 chars. Screen choice is the single biggest design constraint.
  • LVGL lv_menu has a built-in back stack — no need to build custom navigation from scratch.
  • Pebble's window stack (push/pop with load/appear/disappear/unload lifecycle) is the cleanest architecture for this class of device.
  • Sentry Alert TX-1 already solved the "pager OS on ESP32 + TFT + buttons" problem — don't reinvent.
  • Voice activation failed in prior attempt. Push-to-talk is the path forward.
  • Two consumers on one Telegram bot token will fight over getUpdates offsets — need separate channels or webhook/polling split.

Next Steps

  • Confirm exact hardware specs (display, ESP32 board, battery)
  • Clone and study Sentry Alert TX-1 code in detail
  • Try Wokwi browser simulator with LVGL + 240x240 ST7789
  • Try LVGL PC simulator on Mac
  • Prototype the message list -> message detail navigation flow
  • Research OpenClaw skill/hook system for dual-output routing