Files

52 lines
4.0 KiB
Markdown

# 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.