4.0 KiB
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 with0x3C(<). 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 the0x8xpush 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
- 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.
- Raw IR (SIR):
SrmOpen(serPortIrPort, ...)paired with an MCP2120 and a TFDU transceiver on the radio. Needs line of sight. - 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.
- 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. UseSrmReceiveWindowOpen/Closefor zero-copy parsing, andSrmSetWakeupHandler+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_MESSAGEuntil 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.prcon 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.