====== PicoShell — RP2350 SSH Terminal Cyberdeck ======

A pocket SSH terminal built on the Raspberry Pi Pico 2 W. Native 80-column color display via DVI, USB keyboard, WiFi SSH client. Under €50. Runs for 15+ hours on a LiPo.

Think: cyberdeck disguised as a modern GameBoy with too many keys.

===== Concept =====

<code>
USB Keyboard → Pico 2 W (RP2350) → WiFi → SSH → your servers
                    ↓
              HSTX DVI → 80x30 color terminal
              (core 1, no PIO needed)
</code>

Two-phase approach:
  - **Phase 1 (thin client):** Pico does keyboard + VT100 display. SSH runs on a Pi Zero 2W or any Linux box, connected via WiFi TCP. Also doubles as a serial terminal for headless boards.
  - **Phase 2 (native SSH):** wolfSSH client runs directly on the Pico. No companion needed. Full standalone operation.

===== Parts List =====

^ Part ^ Approx. Price ^ Link ^ Notes ^
| Pimoroni Pico Plus 2 W | €15 | [[https://shop.pimoroni.com/en-us/products/pimoroni-pico-plus-2-w|Pimoroni]] | RP2350B, **8MB PSRAM**, 16MB flash, WiFi/BT, USB-C |
| Adafruit PiCowbell DVI for Pico 2 | €8 | [[https://www.adafruit.com/product/6055|Adafruit]] | HSTX DVI breakout, no PIO needed |
| 5" 800x480 HDMI IPS panel | €20 | Search AliExpress/Amazon for "5 inch HDMI LCD 800x480" | 100x30 chars at 8x16 font. TFP401-based boards work well |
| USB OTG adapter | €2 | Any USB-C OTG cable | For USB HID keyboard |
| SD card breakout (SPI) | €3 | [[https://www.adafruit.com/product/254|Adafruit]] or any SPI SD module | SSH keys, config, logs |
| 3.7V LiPo 3000mAh + TP4056 charger | €5 | AliExpress | ~15h WiFi active, days in serial-only mode |
| **Total** | **~€50** | | |

===== Key Technologies =====

=== HSTX DVI (RP2350 native) ===

The RP2350 has a dedicated high-speed serial transmitter (HSTX) that outputs DVI directly. No PIO state machines consumed, no overclocking needed.

  * 640x480 @ 60Hz — 80x30 text with 8x16 font
  * 800x600 @ 60Hz — 100x37 text
  * **16-color text mode** built into DispHSTX library (CGA palette, enough for xterm-16color: vim, htop, tmux)
  * 256-color or 65K-color graphics modes for full xterm-256color rendering
  * Framebuffer in PSRAM (~300-480KB), SRAM stays free for SSH/networking
  * Library: [[https://github.com/Panda381/DispHSTX|DispHSTX]] ([[https://www.breatharian.eu/hw/disphstx/index_en.html|docs]])

=== PSRAM on RP2350 ===

8MB PSRAM on the Pimoroni board. Enough for framebuffer + scrollback + SSH buffers.

^ Use ^ Size ^
| Framebuffer (800x600 8bpp) | 480 KB |
| Scrollback (80x1000 lines + attributes) | 240 KB |
| SSH buffers (wolfSSH) | 100 KB |
| Heap / misc | ~7 MB free |

Gotchas (documented, workarounds exist):
  * Flash operations clobber PSRAM config — save/restore QMI registers ([[https://github.com/raspberrypi/pico-sdk/issues/1983|SDK issue]])
  * Cache coherency bug on clean — use clean+invalidate ([[https://forums.raspberrypi.com/viewtopic.php?t=378249|forum thread]])
  * DMA to PSRAM is slow — double-buffer through SRAM ([[https://forums.raspberrypi.com/viewtopic.php?t=388282|forum thread]])
  * Analysis: [[https://dmitry.gr/?r=06.+Thoughts&proj=11.+RP2350|Dmitry.GR RP2350 review]]

=== SSH on Pico ===

  * **wolfSSH** — lightweight SSHv2 library, client + server, ANSI C. [[https://github.com/wolfSSL/wolfssh|GitHub]]
  * **pico-sshd** — SSH **server** running on Pico W, proves wolfSSH+lwIP works on this hardware. [[https://github.com/tjko/pico-sshd|GitHub]]
  * wolfSSL crypto has explicit RP2350 support (incl. hardware TRNG)
  * Key exchange (RSA/ECDH): ~2-5 sec on Cortex-M33. Session crypto (AES-GCM/ChaCha20): fast.
  * No existing SSH **client** project on Pico — this would be a first.

===== Existing Projects / References =====

  * [[https://github.com/RC2014Z80/picoterm|PicoTerm]] — VGA terminal emulator on Pico (serial, 80x30)
  * [[https://www.clockworkpi.com/picocalc|PicoCalc]] — ClockworkPi handheld ($75 kit, 320x320 display, QWERTY keyboard, 8MB PSRAM, but only 40 columns)
  * [[https://github.com/Wren6991/PicoDVI|PicoDVI]] — DVI output for RP2040 (predecessor to HSTX approach)
  * [[https://github.com/tvlad1234/pico-window|pico-window]] — Text windowing system with FreeRTOS
  * [[https://github.com/filipforsstrom/pico-serial-to-wifi-bridge|pico-serial-to-wifi-bridge]] — UART↔TCP bridge for thin-client approach
  * [[https://shop.pimoroni.com/products/picovision|PicoVision]] — Dual-RP2040 HDMI board (overkill but reference design)

===== vs Alternatives =====

^ ^ PicoShell ^ uConsole ^ PicoCalc ^
| Price | ~€50 | ~€200+ | ~€75 |
| Wait | Next-day shipping | Months | Weeks |
| 80 columns | Yes (DVI 640x480+) | Yes (Linux FB) | No (320x320) |
| Color | 16/256 color | Full 24-bit | Mono/limited |
| SSH | wolfSSH / thin client | Native Linux | No WiFi in base |
| Battery | 15+ hours | 2-4 hours | Hours (2x 18650) |
| Weight | ~100g | ~300g | ~200g |
| Hackability | Bare metal, full control | Linux, CM4 | MicroPython/C |
| Display | External HDMI panel | Built-in 5" | Built-in 4" |

===== Status =====

**Phase:** Planning. Repository: ''%%https://git.reauktion.de/marfrit/picoshell%%'' (once created).