palm-client: Docker toolchain, app scaffold and protocol framing

prc-tools-remix 2.3.6 + PilRC + Palm OS 3.5 SDK (pinned) in a Docker
image; make builds visormesh.prc there when the toolchain isn't local.
App has a main form whose Query button sends CMD_DEVICE_QUERY over the
Serial Manager transport. Companion framing is plain C with host tests.
make install pushes the .prc to a Pi with the USB cradle (untested).
This commit is contained in:
rich committed 2026-11-01 10:19:33 -05:00
1 parent a48a0ae90c
commit cc989cf357
13 files changed
+643 -3

No files matched your search

+5 -2
View File
@@ -20,8 +20,11 @@
- [ ] Plug stack into carrier; `CMD_DEVICE_QUERY` gets a DEVICE_INFO reply
### Palm client
- [ ] Toolchain set up (prc-tools or CodeWarrior, Palm OS 3.5 SDK, HsExt headers)
- [ ] POSE running a 3.5.2H3 Visor ROM
- [x] Toolchain set up: prc-tools-remix 2.3.6 + PilRC + Palm OS 3.5 SDK in Docker (`palm-client/Dockerfile`)
- [x] Scaffold: builds `visormesh.prc` (main form + "Query radio" → CMD_DEVICE_QUERY); protocol framing with host tests
- [ ] Pi install path: visor driver + pilot-link on the Pi, `make install` tested
- [ ] Emulator: CloudpilotEmu with a Palm OS 3.5 ROM (the Visor isn't emulated); optionally POSE + a Visor Neo ROM in a Windows VM
- [ ] Original Handspring SDK headers (Springboard `HsCard*` APIs; the PalmOne `HsExt.h` lacks them), needed for module-ROM work only
- [ ] Port springSD bus routines; SC16IS740 driver
- [ ] Companion protocol framing + minimal command set
- [ ] UI: contacts, DMs, channels
+22
View File
@@ -0,0 +1,22 @@
# Palm OS 68k build environment: prc-tools-remix (m68k-palmos-gcc), PilRC,
# and the Palm OS SDKs. The packages are amd64-only; on Apple Silicon Docker
# runs this under emulation (build/run with --platform linux/amd64), which is fine for builds this small.
FROM debian:bookworm-slim
ARG PRC_TOOLS_VER=2.3.6
ARG PILRC_TAG=2.3.91
ARG PILRC_VER=3.2.91
ARG PALM_SDK_COMMIT=1fa22066ca0f8b74949c14dd1d626294145d1c09
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates curl unzip make gcc libc6-dev \
&& curl -fsSLo /tmp/prc.deb https://github.com/jichu4n/prc-tools-remix/releases/download/v${PRC_TOOLS_VER}/prc-tools-remix_${PRC_TOOLS_VER}.bookworm_amd64.deb \
&& curl -fsSLo /tmp/pilrc.deb https://github.com/jichu4n/pilrc/releases/download/${PILRC_TAG}/pilrc_${PILRC_VER}.bookworm_amd64.deb \
&& apt-get install -y --no-install-recommends /tmp/prc.deb /tmp/pilrc.deb \
&& curl -fsSLo /tmp/sdk.zip https://github.com/jichu4n/palm-os-sdk/archive/${PALM_SDK_COMMIT}.zip \
&& unzip -q /tmp/sdk.zip -d /tmp \
&& mv /tmp/palm-os-sdk-${PALM_SDK_COMMIT} /opt/palmdev \
&& palmdev-prep -d sdk-3.5 \
&& rm -rf /tmp/*.deb /tmp/sdk.zip /var/lib/apt/lists/*
WORKDIR /src
+68
View File
@@ -0,0 +1,68 @@
# VisorMesh Palm client.
#
# make build build/visormesh.prc (in Docker if the toolchain isn't installed)
# make test run the host-side protocol tests
# make install copy the .prc to the Pi and install it over the USB cradle
# make clean
APP = visormesh
NAME = VisorMesh
CREATOR = VMsh
SRCS = src/main.c src/protocol.c src/transport_srm.c
OBJS = $(SRCS:src/%.c=build/%.o)
CC = m68k-palmos-gcc
CFLAGS = -palmos3.5 -O2 -Wall -Isrc
PILRC = pilrc
# Pi with the Visor cradle attached (see tools/pi-install.sh).
PI ?= visormesh-pi
PI_PORT ?= /dev/ttyUSB1
DOCKER_IMAGE = visormesh-palm
DOCKER_RUN = docker run --rm --platform linux/amd64 -v "$(CURDIR)":/src -w /src $(DOCKER_IMAGE)
ifeq ($(shell command -v $(CC) 2>/dev/null),)
all test: image
$(DOCKER_RUN) make $@
image:
docker build --platform linux/amd64 -q -t $(DOCKER_IMAGE) . >/dev/null
else
all: build/$(APP).prc
build/%.o: src/%.c src/*.h | build
$(CC) $(CFLAGS) -c $< -o $@
build/$(APP): $(OBJS)
$(CC) $(CFLAGS) -o $@ $(OBJS)
build/res.stamp: resources/$(APP).rcp src/resources.h | build
rm -rf build/res && mkdir -p build/res
$(PILRC) -q -I src $< build/res
touch $@
build/$(APP).prc: build/$(APP) build/res.stamp
build-prc --backup -o $@ -n "$(NAME)" -c $(CREATOR) build/$(APP) build/res/*.bin
test: | build
gcc -std=c99 -Wall -Wextra -o build/test_protocol tests/test_protocol.c src/protocol.c
build/test_protocol
build:
mkdir -p build
endif
install: build/$(APP).prc
scp -q build/$(APP).prc $(PI):/tmp/$(APP).prc
ssh -t $(PI) "bash -s -- /tmp/$(APP).prc $(PI_PORT)" < tools/pi-install.sh
clean:
rm -rf build
.PHONY: all test image install clean
+49 -1
View File
@@ -1,3 +1,51 @@
# Palm client
Not started. See [../docs/design.md](../docs/design.md#palm-client-plans) for the plan and [../docs/progress.md](../docs/progress.md) for the milestones.
The VisorMesh app for the Visor Neo (Palm OS 3.5.2H3.0). It's written in C with prc-tools-remix (GCC 2.95 for m68k) and PilRC, against the Palm OS 3.5 SDK.
## Build
```sh
make # -> build/visormesh.prc
make test # host-side tests for the protocol framing
```
If `m68k-palmos-gcc` isn't installed, `make` builds and runs the `visormesh-palm` Docker image (see `Dockerfile`) and does the build inside it. The first run takes a minute or two. The image is amd64-only, so on Apple Silicon it runs under emulation. That's fine for builds this small.
The toolchain versions and the palm-os-sdk commit are pinned in the `Dockerfile`.
Your editor's C checker can't see the Palm SDK headers, since they only exist inside the image. Errors like `'PalmOS.h' file not found` there are expected and don't affect the build.
## Code layout
| File | Layer |
|---|---|
| `src/transport.h` | Byte-stream link to the radio. One implementation per transport |
| `src/transport_srm.c` | Serial Manager transport (cradle serial port, or an emulator's serial port) |
| `src/protocol.[ch]` | MeshCore companion framing (`<`/`>` + 2-byte LE length). Pure C, so it's tested on the host |
| `src/main.c` | App startup, event loop, main form |
| `resources/visormesh.rcp` | PilRC forms and alerts. IDs are in `src/resources.h` |
| `tests/` | Host tests (`make test`) |
The SB-LoRa transport (bus-SPI into the SC16IS740) will be a second `transport_*.c` behind the same interface.
Creator ID is `VMsh`. The database has the backup bit set, so HotSync keeps a copy.
## Install on the Visor
The Visor's USB cradle is plugged into a Raspberry Pi. `make install` copies the `.prc` to the Pi and runs `tools/pi-install.sh` there, which waits for you to press the HotSync button and then runs `pilot-xfer -i`.
```sh
make install PI=user@pi-hostname # default PI is visormesh-pi
make install PI=... PI_PORT=usb: # if pilot-link uses libusb
```
The Pi needs:
- the kernel `visor` USB-serial driver (`modprobe visor`; the Visor appears as `/dev/ttyUSB1` during HotSync)
- `pilot-link` (`pilot-xfer`)
- SSH key login from your dev machine
**The Pi setup isn't done or tested yet.**
## Testing without hardware
The Visor can't be emulated on a Mac: CloudpilotEmu doesn't support Handspring devices. Use CloudpilotEmu (https://cloudpilot-emu.github.io/app) with a Palm OS 3.5 device ROM, such as a Palm IIIx or m100. The OS APIs match the Neo's. In the emulator, "Query radio" should report "No reply" or an open error, since there's no radio attached.
+23
View File
@@ -0,0 +1,23 @@
#include "resources.h"
VERSION ID 1 "0.1"
APPLICATIONICONNAME ID 1000 "VisorMesh"
FORM ID MainForm AT (0 0 160 160)
NOFRAME
USABLE
BEGIN
TITLE "VisorMesh"
LABEL "MeshCore client for the Visor" AUTOID AT (5 20)
LABEL "Radio:" AUTOID AT (5 45) FONT 1
LABEL "Not connected " ID MainStatusLabel AT (40 45)
BUTTON "Query radio" ID MainQueryButton AT (CENTER 140 AUTO AUTO)
END
ALERT ID RomIncompatibleAlert
ERROR
BEGIN
TITLE "System Incompatible"
MESSAGE "VisorMesh needs Palm OS 3.5 or later."
BUTTONS "OK"
END
+146
View File
@@ -0,0 +1,146 @@
#include <PalmOS.h>
#include "resources.h"
#include "protocol.h"
#include "transport.h"
#define VM_MIN_ROM_VERSION sysMakeROMVersion(3, 5, 0, sysROMStageRelease, 0)
#define VM_QUERY_TIMEOUT (2 * SysTicksPerSecond())
static VmFrameDecoder gDecoder;
static Err RomVersionCompatible(UInt32 required, UInt16 launchFlags)
{
UInt32 romVersion;
FtrGet(sysFtrCreator, sysFtrNumROMVersion, &romVersion);
if (romVersion >= required)
return errNone;
if ((launchFlags & (sysAppLaunchFlagNewGlobals | sysAppLaunchFlagUIApp)) ==
(sysAppLaunchFlagNewGlobals | sysAppLaunchFlagUIApp))
FrmAlert(RomIncompatibleAlert);
return sysErrRomIncompatible;
}
static void SetStatus(const Char *text)
{
FormType *form = FrmGetActiveForm();
FrmHideObject(form, FrmGetObjectIndex(form, MainStatusLabel));
FrmCopyLabel(form, MainStatusLabel, text);
FrmShowObject(form, FrmGetObjectIndex(form, MainStatusLabel));
}
/* Sends CMD_DEVICE_QUERY and waits for any '>' frame in reply. */
static void QueryRadio(void)
{
UInt8 payload[2];
UInt8 frame[VM_HEADER_LEN + 2];
UInt8 rx[32];
UInt16 frameLen, n, i;
UInt32 deadline;
Char msg[32];
Err err;
SetStatus("Opening port...");
err = TransportOpen();
if (err != errNone) {
StrPrintF(msg, "Open failed (0x%x)", err);
SetStatus(msg);
return;
}
payload[0] = VM_CMD_DEVICE_QUERY;
payload[1] = VM_APP_TARGET_VER;
frameLen = VmEncodeFrame(frame, sizeof(frame), payload, sizeof(payload));
VmDecoderReset(&gDecoder);
err = TransportSend(frame, frameLen);
if (err != errNone) {
StrPrintF(msg, "Send failed (0x%x)", err);
SetStatus(msg);
TransportClose();
return;
}
SetStatus("Waiting for reply...");
deadline = TimGetTicks() + VM_QUERY_TIMEOUT;
while (TimGetTicks() < deadline) {
n = TransportRecv(rx, sizeof(rx), deadline - TimGetTicks(), &err);
for (i = 0; i < n; i++) {
if (VmDecoderFeed(&gDecoder, rx[i])) {
StrPrintF(msg, "Reply 0x%x, %u bytes",
gDecoder.len ? gDecoder.payload[0] : 0, gDecoder.len);
SetStatus(msg);
TransportClose();
return;
}
}
}
SetStatus("No reply");
TransportClose();
}
static Boolean MainFormHandleEvent(EventType *event)
{
switch (event->eType) {
case frmOpenEvent:
FrmDrawForm(FrmGetActiveForm());
return true;
case ctlSelectEvent:
if (event->data.ctlSelect.controlID == MainQueryButton) {
QueryRadio();
return true;
}
break;
default:
break;
}
return false;
}
static Boolean AppHandleEvent(EventType *event)
{
FormType *form;
UInt16 formId;
if (event->eType != frmLoadEvent)
return false;
formId = event->data.frmLoad.formID;
form = FrmInitForm(formId);
FrmSetActiveForm(form);
if (formId == MainForm)
FrmSetEventHandler(form, MainFormHandleEvent);
return true;
}
static void AppEventLoop(void)
{
EventType event;
Err err;
do {
EvtGetEvent(&event, evtWaitForever);
if (SysHandleEvent(&event))
continue;
if (MenuHandleEvent(0, &event, &err))
continue;
if (AppHandleEvent(&event))
continue;
FrmDispatchEvent(&event);
} while (event.eType != appStopEvent);
}
UInt32 PilotMain(UInt16 cmd, MemPtr cmdPBP, UInt16 launchFlags)
{
Err err = RomVersionCompatible(VM_MIN_ROM_VERSION, launchFlags);
if (err != errNone)
return err;
if (cmd == sysAppLaunchCmdNormalLaunch) {
FrmGotoForm(MainForm);
AppEventLoop();
TransportClose();
FrmCloseAllForms();
}
return errNone;
}
+60
View File
@@ -0,0 +1,60 @@
#include "protocol.h"
enum { ST_SYNC, ST_LEN_LO, ST_LEN_HI, ST_PAYLOAD };
UInt16 VmEncodeFrame(UInt8 *out, UInt16 outSize, const UInt8 *payload, UInt16 len)
{
UInt16 i;
if (len > VM_MAX_FRAME || outSize < (UInt16)(len + VM_HEADER_LEN))
return 0;
out[0] = VM_FRAME_TO_RADIO;
out[1] = (UInt8)(len & 0xFF);
out[2] = (UInt8)(len >> 8);
for (i = 0; i < len; i++)
out[VM_HEADER_LEN + i] = payload[i];
return (UInt16)(len + VM_HEADER_LEN);
}
void VmDecoderReset(VmFrameDecoder *d)
{
d->state = ST_SYNC;
d->len = 0;
d->pos = 0;
}
Boolean VmDecoderFeed(VmFrameDecoder *d, UInt8 byte)
{
switch (d->state) {
case ST_SYNC:
if (byte == VM_FRAME_FROM_RADIO)
d->state = ST_LEN_LO;
return 0;
case ST_LEN_LO:
d->len = byte;
d->state = ST_LEN_HI;
return 0;
case ST_LEN_HI:
d->len |= (UInt16)byte << 8;
d->pos = 0;
if (d->len > VM_MAX_FRAME) {
VmDecoderReset(d);
return 0;
}
if (d->len == 0) {
d->state = ST_SYNC;
return 1;
}
d->state = ST_PAYLOAD;
return 0;
case ST_PAYLOAD:
d->payload[d->pos++] = byte;
if (d->pos == d->len) {
d->state = ST_SYNC;
return 1;
}
return 0;
}
VmDecoderReset(d);
return 0;
}
+50
View File
@@ -0,0 +1,50 @@
/*
* MeshCore companion protocol framing.
*
* App -> radio: '<' len_lo len_hi payload[len]
* Radio -> app: '>' len_lo len_hi payload[len]
*
* Plain C with no Palm OS calls, so it also builds on the host for tests.
*/
#ifndef VM_PROTOCOL_H
#define VM_PROTOCOL_H
#ifdef __palmos__
#include <PalmTypes.h>
#else
#include <stdint.h>
typedef uint8_t UInt8;
typedef uint16_t UInt16;
typedef int16_t Int16;
typedef uint8_t Boolean;
#endif
#define VM_FRAME_TO_RADIO 0x3C /* '<' */
#define VM_FRAME_FROM_RADIO 0x3E /* '>' */
#define VM_MAX_FRAME 172 /* MeshCore MAX_FRAME_SIZE (payload bytes) */
#define VM_HEADER_LEN 3
/* Commands (app -> radio). Add others as they're verified against MeshCore. */
#define VM_CMD_DEVICE_QUERY 0x16
#define VM_APP_TARGET_VER 0x03
typedef struct {
UInt8 state;
UInt16 len;
UInt16 pos;
UInt8 payload[VM_MAX_FRAME];
} VmFrameDecoder;
/* Writes a '<' frame into out. Returns total bytes written, or 0 if it won't fit. */
UInt16 VmEncodeFrame(UInt8 *out, UInt16 outSize, const UInt8 *payload, UInt16 len);
void VmDecoderReset(VmFrameDecoder *d);
/*
* Feeds one byte from the radio. Returns 1 when a complete '>' frame is in
* d->payload (length d->len); the next call starts a new frame. Bytes outside
* a frame and frames longer than VM_MAX_FRAME are dropped.
*/
Boolean VmDecoderFeed(VmFrameDecoder *d, UInt8 byte);
#endif
+10
View File
@@ -0,0 +1,10 @@
#ifndef VM_RESOURCES_H
#define VM_RESOURCES_H
#define MainForm 1000
#define MainStatusLabel 1001
#define MainQueryButton 1002
#define RomIncompatibleAlert 2000
#endif
+22
View File
@@ -0,0 +1,22 @@
/*
* Byte-stream link to the companion radio. One implementation per transport:
* transport_srm.c Serial Manager (cradle serial port, or an emulator's
* serial port bridged to a radio on the host)
* (later) SB-LoRa Springboard module via the SC16IS740
*/
#ifndef VM_TRANSPORT_H
#define VM_TRANSPORT_H
#include <PalmOS.h>
Err TransportOpen(void);
void TransportClose(void);
Err TransportSend(const UInt8 *buf, UInt16 len);
/*
* Waits up to timeoutTicks for data, then returns whatever is available,
* up to max bytes. Returns 0 on timeout.
*/
UInt16 TransportRecv(UInt8 *buf, UInt16 max, Int32 timeoutTicks, Err *errP);
#endif
+67
View File
@@ -0,0 +1,67 @@
#include <PalmOS.h>
#include "transport.h"
#define VM_BAUD 115200
static UInt16 gPortId;
static Boolean gPortOpen = false;
Err TransportOpen(void)
{
Err err;
if (gPortOpen)
return errNone;
err = SrmOpen(serPortCradlePort, VM_BAUD, &gPortId);
if (err == errNone)
gPortOpen = true;
return err;
}
void TransportClose(void)
{
if (!gPortOpen)
return;
SrmClose(gPortId);
gPortOpen = false;
}
Err TransportSend(const UInt8 *buf, UInt16 len)
{
Err err = errNone;
if (!gPortOpen)
return serErrNotOpen;
SrmSend(gPortId, (void *)buf, len, &err);
if (err == errNone)
err = SrmSendWait(gPortId);
return err;
}
UInt16 TransportRecv(UInt8 *buf, UInt16 max, Int32 timeoutTicks, Err *errP)
{
UInt32 avail = 0;
UInt32 n;
*errP = errNone;
if (!gPortOpen) {
*errP = serErrNotOpen;
return 0;
}
/* Block for the first byte, then take whatever else is already buffered. */
n = SrmReceive(gPortId, buf, 1, timeoutTicks, errP);
if (n == 0) {
if (*errP == serErrLineErr)
SrmClearErr(gPortId);
return 0;
}
if (SrmReceiveCheck(gPortId, &avail) == errNone && avail > 0) {
if (avail > (UInt32)(max - 1))
avail = max - 1;
n += SrmReceive(gPortId, buf + 1, avail, 0, errP);
}
if (*errP == serErrLineErr)
SrmClearErr(gPortId);
return (UInt16)n;
}
+89
View File
@@ -0,0 +1,89 @@
/* Host-side tests for the companion framing. Run with `make test`. */
#include <stdio.h>
#include <string.h>
#include "../src/protocol.h"
static int failures;
#define CHECK(cond) do { \
if (!(cond)) { printf("FAIL %s:%d: %s\n", __FILE__, __LINE__, #cond); failures++; } \
} while (0)
static int feed(VmFrameDecoder *d, const UInt8 *bytes, int n)
{
int i, frames = 0;
for (i = 0; i < n; i++)
frames += VmDecoderFeed(d, bytes[i]);
return frames;
}
static void test_encode_device_query(void)
{
UInt8 payload[] = { VM_CMD_DEVICE_QUERY, VM_APP_TARGET_VER };
UInt8 out[8];
UInt8 expect[] = { '<', 0x02, 0x00, 0x16, 0x03 };
CHECK(VmEncodeFrame(out, sizeof(out), payload, 2) == 5);
CHECK(memcmp(out, expect, 5) == 0);
CHECK(VmEncodeFrame(out, 4, payload, 2) == 0);
}
static void test_decode_with_leading_junk(void)
{
VmFrameDecoder d;
UInt8 in[] = { 0x00, '<', 0xFF, '>', 0x03, 0x00, 0x0D, 0xAA, 0xBB };
VmDecoderReset(&d);
CHECK(feed(&d, in, sizeof(in)) == 1);
CHECK(d.len == 3);
CHECK(d.payload[0] == 0x0D && d.payload[2] == 0xBB);
}
static void test_decode_back_to_back(void)
{
VmFrameDecoder d;
UInt8 in[] = { '>', 0x01, 0x00, 0x83, '>', 0x02, 0x00, 0x05, 0x06 };
VmDecoderReset(&d);
CHECK(feed(&d, in, 4) == 1 && d.len == 1 && d.payload[0] == 0x83);
CHECK(feed(&d, in + 4, 5) == 1 && d.len == 2 && d.payload[1] == 0x06);
}
static void test_decode_oversize_resyncs(void)
{
VmFrameDecoder d;
UInt8 bad[] = { '>', 0xFF, 0x00 };
UInt8 good[] = { '>', 0x01, 0x00, 0x42 };
VmDecoderReset(&d);
CHECK(feed(&d, bad, sizeof(bad)) == 0);
CHECK(feed(&d, good, sizeof(good)) == 1 && d.payload[0] == 0x42);
}
static void test_decode_max_frame(void)
{
VmFrameDecoder d;
UInt8 hdr[] = { '>', VM_MAX_FRAME & 0xFF, VM_MAX_FRAME >> 8 };
int i, frames;
VmDecoderReset(&d);
frames = feed(&d, hdr, 3);
for (i = 0; i < VM_MAX_FRAME; i++)
frames += VmDecoderFeed(&d, (UInt8)i);
CHECK(frames == 1 && d.len == VM_MAX_FRAME && d.payload[VM_MAX_FRAME - 1] == (VM_MAX_FRAME - 1));
}
int main(void)
{
test_encode_device_query();
test_decode_with_leading_junk();
test_decode_back_to_back();
test_decode_oversize_resyncs();
test_decode_max_frame();
if (failures) {
printf("%d failure(s)\n", failures);
return 1;
}
printf("all protocol tests passed\n");
return 0;
}
+32
View File
@@ -0,0 +1,32 @@
#!/bin/bash
# Runs on the Pi (piped over ssh by `make install`): installs a .prc onto the
# Visor through its USB cradle using pilot-link.
#
# Usage: pi-install.sh FILE.prc [PORT]
# PORT defaults to /dev/ttyUSB1 (the kernel visor driver's HotSync port).
# Use "usb:" instead if pilot-link was built with libusb.
set -euo pipefail
prc="$1"
port="${2:-/dev/ttyUSB1}"
if ! command -v pilot-xfer >/dev/null; then
echo "pilot-xfer not found on $(hostname). Install pilot-link first (see palm-client/README.md)." >&2
exit 1
fi
echo "Press the HotSync button on the Visor cradle..."
if [[ "$port" == /dev/* ]]; then
# The visor driver only creates the tty once HotSync starts.
for _ in $(seq 60); do
[[ -e "$port" ]] && break
sleep 1
done
if [[ ! -e "$port" ]]; then
echo "Timed out waiting for $port. Is the visor kernel module loaded? (lsmod | grep visor)" >&2
exit 1
fi
fi
pilot-xfer -p "$port" -i "$prc"