Pineapple PicoPager

A dedicated hardware terminal companion for the Hak5 WiFi Pineapple Pager.

This project converts a ClockworkPi Pico-Calc into a permanent console and logging interface for the Pineapple Pager over USB.

Instead of using a phone or browser, the Pico-Calc becomes a physical SOC-style terminal:

• Live alert monitor
• Root shell access
• Scrollback history
• Persistent logging
• Field deployment console
• Offline operation (no internet required)

The Pager becomes the sensor. The Pico-Calc becomes the operator interface.

---

What It Does

After flashing:

1. Power Pico-Calc
2. Plug USB into Pineapple Pager
3. Instantly opens terminal session
4. Automatically logs activity to SD card

No menus. No apps. No distractions.

It behaves like a classic hardware console terminal.

---

Features

Persistent Screen

• VT100-compatible framebuffer preserves display state across reconnections
• Status bar shows link state, uptime, RX bytes, history count, and log entries
• Full screen restore after cable disconnect/reconnect without losing visible context
• Header banner, scrollable content region, and dedicated status line

Keyboard

• Full key mapping with escape sequence decoding for arrow keys, Home, End, PgUp, PgDn
• Single-line editor with cursor movement (left/right, Home/End)
• Ctrl-A (home), Ctrl-E (end), Ctrl-U (clear line), Ctrl-K (kill to end of line)
• Ctrl-C sends interrupt to Pager, Ctrl-D quits console, Ctrl-L clears screen
• Non-blocking input polling compatible with MicroPython on RP2040

History

• Persistent command history saved to SD card across power cycles
• Up/Down arrow recall through previous commands
• Ctrl-R reverse incremental search with live preview
• Duplicate suppression and configurable max entries (default 500)
• History file (/history.txt) is human-readable plain text

Reliable Cable

• USB UART watchdog with configurable heartbeat interval and timeout
• Automatic reconnection with exponential backoff (1s, 2s, 4s, 8s, 16s, 30s)
• Connection state machine: disconnected, connecting, connected, error
• Session statistics tracking: bytes RX/TX, disconnect count, uptime
• Status bar integration shows real-time link health

Long-term Logs

• Structured log entries with ISO timestamps and severity levels (INFO, WARN, ERROR, DATA, SESSION)
• Automatic daily log file rotation with sequence numbering
• Configurable max file size (512 KB default) triggers rotation
• Old file pruning keeps disk usage bounded (50 files default)
• Session index file for quick lookup of session start/end times
• All terminal data logged separately from system events

---

Why This Exists

The Pager UI is intentionally minimal.

For real monitoring, you want:

• Persistent screen
• Keyboard
• History
• Reliable cable
• Long-term logs

This turns the Pager into a field deployable wireless IDS appliance.

---

Hardware

Component	Description
ClockworkPi Pico-Calc	Operator terminal interface
Hak5 WiFi Pineapple Pager	Wireless sensor / scanner
USB-C cable	Connection between devices
MicroSD card	Log storage (any size)

---

Quick Start

See INSTALL.md

---

Keyboard Shortcuts

Key	Action
Up / Down	Recall command history
Left / Right	Move cursor in line editor
Home / Ctrl-A	Jump to beginning of line
End / Ctrl-E	Jump to end of line
Ctrl-U	Clear entire line
Ctrl-K	Kill from cursor to end of line
Ctrl-R	Reverse search command history
Ctrl-L	Clear screen and redraw
Ctrl-C	Send interrupt to Pager
Ctrl-D	Quit PicoPager console
PgUp	Scroll back through output
PgDn	Scroll forward through output

---

File Layout

sd/
├── boot.py              Boot-time directory setup
├── main.py              Main console application
├── lib/
│   ├── __init__.py
│   ├── screen.py        Persistent screen / framebuffer
│   ├── keyboard.py      Key input and line editor
│   ├── history.py       Command history with persistence
│   ├── connection.py    USB cable watchdog and reconnect
│   └── logger.py        Structured long-term logging
├── logs/
│   ├── index.txt        Session index
│   └── picopager_*.log  Daily log files
└── history.txt          Persistent command history

---

Result

You now have a portable RF monitoring console.

• Pager = radio intelligence
• Pico-Calc = human interface

RF Environment → Pager → USB → Pico-Calc → Human

---

Architecture

See ARCHITECTURE.md for design details.

---

License

This project is provided as-is for educational and research purposes.