palm-sync

palm-sync is a modern, cross-platform toolkit for HotSync with Palm OS devices, built with TypeScript.

palm-sync provides a new implementation of Palm HotSync protocols in TypeScript, and supports Node.js and browser environments. It aspires to be the foundation for a new generation of Palm OS synchronization tools for modern operating systems.

Supported platforms and features

OS	Node.js 18+			Browser (Chromium)
	Serial	USB	Network	Serial	USB
Windows	Y	Y	Y	Y	Y
macOS	Y	Y	Y	Y	Y
Linux	Y	Y	Y	Y	Y
ChromeOS	Y	Y	Y	Y	Y
Android	N/A	N/A	N/A	N	Y

Not supported:

• Operating systems: iOS, iPadOS
• Connections: Bluetooth, IR

For more information, please see Connecting Palm OS Devices.

Web demo

You can try out palm-sync right in your browser! The web demo allows you to do a simple HotSync with a Palm OS device via USB or serial.

👉 jichu4n.github.io/palm-sync/web-demo

Requirements:

• Palm OS device connected via USB or serial, including via serial-to-USB adapter.
• A Chromium-based browser such as Google Chrome or Microsoft Edge, running on Windows, macOS, Linux, ChromeOS, or Android (USB only). See Connecting Palm OS Devices for OS-specific setup.

Quickstart

Installation

npm install --save palm-sync

Create a conduit

Example conduit to list the databases on a Palm device:

// ./src/list-dbs.ts
import {
  DlpConnection,
  DlpReadDBListFlags,
  DlpReadDBListReqType,
} from 'palm-sync';

export async function run(dlpConnection: DlpConnection) {
  const readDbListResp = await dlpConnection.execute(
    DlpReadDBListReqType.with({
      srchFlags: DlpReadDBListFlags.with({ram: true, multiple: true}),
    })
  );
  const dbNames = readDbListResp.dbInfo.map(({name}) => name);
  console.log(dbNames.join('\n'));
}

Run conduit with CLI

# Run tsc to produce ./dist/list-dbs.js
npm run build

# Wait for HotSync connection over USB and run specified conduit.
#   - For serial, use `--serial /dev/ttyXXX` (`--serial COMn` on Windows)
#   - For network HotSync (port 14238), use `--net`
#   - For serial-over-network (POSE and other emulators), use `--serial:net`
#     to listen on port 6416
./node_modules/.bin/palm-sync run --usb ./dist/list-dbs.js

Now connect and initiate HotSync on the Palm OS device! See Connecting Palm OS Devices for OS-specific setup.

API

Overview

For a general introduction to HotSync's architecture, please first read 👉 How Palm OS HotSync Works. This will help provide context for the APIs discussed below.

palm-sync's API is organized into the following main components:

• Sync servers - Interfacing with OS / hardware and managing the sync process.
• Protocols - Implements the various communication protocols in the HotSync protocol stack.
• Sync utils - Common sync logic and helpers.
• Conduits - General purpose conduits.

Additionally, palm-sync depends on the following sister projects:

• palm-pdb - Manipulating Palm OS databases and related data structures.
• serio - Serializing / deserializing binary data.

Sync servers

The SyncServer class represents a daemon that listens for incoming HotSync connections. A SyncServer is responsible for interfacing with the underlying hardware, setting up a transport protocol stack and passing control to the configured conduit. The various subclasses of SyncServer correspond to different types of connections.

Connection type	Node.js	Browser (Chromium)
UsbSyncServer	Yes - usb	Yes - WebUSB API
SerialSyncServer	Yes - serialport	No
WebSerialSyncServer	No	Yes - Web Serial API
NetworkSyncServer	Yes - net	No
SerialOverNetworkSyncServer	Yes - net	No

To create a SyncServer:

• createSyncServer() - Main entrypoint to create a SyncServer instance. The caller can use start() and stop() to manage the server lifecycle, and subscribe to its connect and disconnect events.
• createSyncServerAndRunSync() - Convenience function to run a single HotSync operation - create and start a SyncServer instance, run a conduit, and stop the server.

A SyncServers doesn't perform conduit logic (i.e. business logic for data synchronization) itself. Instead, it takes in a SyncFn to be invoked when a HotSync connection is established. The SyncFn is responsible for performing the desired conduit logic over the DLP protocol. This provides a clean layer of abstraction between conduit logic and the various types of connections.

Protocols

The DlpConnection class represents a connection to a Palm device over the DLP protocol. It provides a high-level API for executing DLP commands, which is the primary way conduits interact with a connected Palm device.

For the full list of supported DLP commands, see the list of subclasses of DlpRequest. palm-sync provides request and response type definitions for all DLP commands up to DLP version 1.2 (Palm OS 3.0). It does not currently support commands introduced in DLP version 1.3 (Palm OS 4.0) and later.

Under the hood, a DlpConnection wraps one of two possible transport protocol stacks, which themselves are implemented as transform streams wrapping the underlying raw data streams. The SyncServer subclass for each connection type is responsible for setting up the appropriate transport stack and constructing DlpConnections. Conduit logic generally does not need to directly interact with the transport protocol stacks.

Sync utils

palm-sync provides a collection of utility functions to help with common conduit tasks. Some key utilities include:

Databases and PDB / PRC files

• readDbList()
• readRawDb() and readDb()
• writeRawDb() and writeDb()

Two-way sync

These functions provide a generic implementation of Palm OS's two-way synchronization logic.

• fastSync() and fastSyncDb()
• slowSync() and slowSyncDb()

Conduits

TODO

Logs

TODO

Reference

• 👉 How Palm OS HotSync Works
• 👉 API reference

Contributors

• Chuan Ji (@jichu4n)
• Otávio Pinheiro (@Tavisco)