Files
visormesh/docs/design.md
T

4.0 KiB

Design notes

Decisions and background carried over from the original planning conversation (claude.ai, October 2026).

Target device

  • Handspring Visor Neo, Palm OS 3.5.2H3.0 (Handspring 3.5 build), DragonBall VZ at 33 MHz, 8 MB RAM, runs on 2x AAA. USB HotSync cradle (no serial cradle).
  • No BLE or WiFi. The radio is never powered from the AAAs: an SX1262 at 22 dBm TX draws over 100 mA.

Architecture

The Visor is a dumb terminal for a MeshCore companion radio. Running Ed25519/X25519 on a 16 to 33 MHz DragonBall would be painfully slow. The companion protocol is simple byte framing, which the Visor handles easily.

Companion protocol (serial)

  • 115200 8N1. The radio is the server and the Visor app is the client.
  • Radio → app frames start with 0x3E (>). App → radio frames start with 0x3C (<). Each is followed by a 2-byte little-endian length.
  • MAX_FRAME_SIZE = 172 bytes.
  • Minimal client command set: APP_START, GET_CONTACTS, SYNC_NEXT_MESSAGE, SEND_TXT_MSG, the channel-message equivalents, and handling of the 0x8x push codes.
  • First bring-up probe: CMD_DEVICE_QUERY = < + len + 0x16 0x03, expect a >-framed DEVICE_INFO reply.
  • Reference: Companion Radio Protocol page on the eastmesh wiki.

Transport options considered

  1. Cradle-connector serial: 3.3 V TTL UART, no level shifter needed. Requires companion firmware on a hardware UART instead of USB-CDC, since the Visor can't be a USB host. Verify the pinout with a scope first, because sources disagree. Don't wire the HotSync line.
  2. Raw IR (SIR): SrmOpen(serPortIrPort, ...) paired with an MCP2120 and a TFDU transceiver on the radio. Needs line of sight.
  3. Intel/Xircom SpringPort Wireless Ethernet (802.11b) to a WiFi companion on TCP 4000. Rare module and WEP-era, so a stunt rather than a daily driver.
  4. Custom Springboard LoRa module: chosen, now the SB-LoRa board. The Palm-side protocol code is the same as option 1. Only the transport routines differ.

SB-LoRa module (hardware/sb-lora)

  • XIAO nRF52840 + Wio-SX1262 stack on 1x7 pin headers, running MeshCore companion firmware with the UART on D6 (TX) / D7 (RX). See firmware/.
  • The Visor reaches it through bus-SPI (springSD-style CS0/CS1 latch trick) into an SC16IS740 SPI-UART bridge. A 14.7456 MHz crystal gives 115200 baud (DLL=8).
  • Power is isolated: only the SN74LVC1T45s span the Visor and XIAO supplies. The LiPo is soldered to the XIAO BAT pads and charged by the XIAO over USB-C.
  • VDOCK charging sits behind JP1, which is left open.
  • There's no module ROM in v0.1, so the client installs to RAM.
  • The springSD v1.1 connector footprint and bus routines (Dmitry Grinberg) are the basis for J1 and the 68k bus code.

Palm client plans

  • Toolchain: prc-tools (m68k gcc) or CodeWarrior, Palm OS 3.5 SDK, plus Handspring HsExt headers for Springboard notifications.
  • Use the New Serial Manager (Srm*) for cradle and IR. Use SrmReceiveWindowOpen/Close for zero-copy parsing, and SrmSetWakeupHandler + SrmPrimeWakeupHandler(portId, 3) to wake on the frame header.
  • On SB-LoRa, the transport is the bus-SPI routines driving the SC16IS740 (IRQ* on the Springboard interrupt line). Put the SC16IS740 to sleep (IER bit 4) when idle to stay under the 100 µA standby limit.
  • Power model: let the Visor sleep. The companion queues messages, and on wake the client drains with SYNC_NEXT_MESSAGE until NO_MORE_MESSAGES.
  • Store contacts and messages in Palm databases, not the heap. Set the backup bit so HotSync keeps a copy.
  • Develop in POSE with a Visor ROM matching 3.5.2H3 (Platinum/Prism or Neo/Pro profile matching the unit). POSE can bridge its serial port to a real companion board, but it can't emulate the Springboard module.
  • Install: HotSync (Palm Desktop 4.x in an XP VM, or pilot-xfer -p /dev/ttyUSB1 -i visormesh.prc on Linux), or the user's Springboard CF adapter if its ROM has an installer. The CF adapter and SB-LoRa share the single slot.

Future (v0.2 ideas)

  • Small flash on CS0 with a module ROM header, so the client auto-launches on insert with no install step.