satx-core 0.12.1

HP 48/49 calculator layer of satx: Kermit and XModem driver loops, calculator operations, HP objects; blocking or sans-I/O (wasm32)
Documentation

satx-core

The HP calculator layer of satx on top of kermit-proto and xmodem-proto: the Kermit and XModem driver loops, the calculator operations (list, get, put, host commands, PICT, backup, restore, XModem preparation), the HP object format, GROBs and the HP character set. It also drives filer-proto for the HP 100LX/200LX palmtops (filer::Palmtop: drives, list, get, put, rename, delete, mkdir, rmdir; blocking, not in the wasm32 build, where filer_proto::Session is the face).

The protocol logic never reads a clock, sleeps or touches a port. Two faces run it:

  • Blocking: Calculator, Session and XmodemSession over a transport::Transport with the system clock. The satx CLI uses these.
  • Sans-I/O: Machine is fed bytes and the caller's time and hands out bytes to write, progress events and the result of each operation. It never blocks, so it runs where bytes arrive by callback, such as a browser with Web Serial on wasm32-unknown-unknown.

Features

Feature Default What it adds
native yes Serial ports (serialport) and TCP in transport::open
saturnus no The Saturnus emulator in-process, saturnus://[MODEL@]ROM (saturnus-core, saturnus-drive)

For the browser, or for any crate that brings its own I/O:

satx-core = { version = "0.2", default-features = false }

That build has no OS I/O, pulls in neither serialport nor saturnus-core, and builds with cargo check -p satx-core --no-default-features --target wasm32-unknown-unknown (a CI step). On wasm32 the clock type satx_core::time::Instant is web_time::Instant (performance.now()); elsewhere it is std::time::Instant.

The sans-I/O API

Machine follows the calling convention of kermit_proto::Client, one level up: a whole operation instead of one Kermit transaction.

Call What it does
Machine::new(now, options, seed) A machine for a newly opened link. seed should be random (crypto.getRandomValues): it picks the sync markers.
start(now, op) -> Result<(), Busy> Begin an Op; its first bytes are ready at once. One operation at a time.
handle_input(now, bytes) Bytes read from the link, any chunking.
handle_timeout(now) The time; call it at next_timeout() (early calls do nothing).
handle_link_error(now, &io::Error) The port failed or closed: the running operation fails.
poll_transmit() -> Option<Vec<u8>> The next chunk to write, as one write (the HP overruns on inter-byte gaps).
poll_event() -> Option<Progress> Kermit or XModem progress (set_events(false) drops them).
poll_result() -> Option<Result<Reply>> The result once the operation is over.
next_timeout() -> Option<Instant> When to call handle_timeout at the latest.
abort(now) Drop the running operation without telling the calculator.

The operations (Op) are those of Calculator and XmodemSession: Connect (drain stale input, then Sync), Sync, Run, List, Path, Cd, Updir, Mkdir, Remove, Rename, Mem, Version, Model, Iopar, SetIopar, TransferMode, SetTransferMode, Get, Put, Pict, Backup, Restore, PurgeRestoreLeftover, Finish, PrepareXmodem, XmodemSend, XmodemReceive, and Transact for one raw Kermit transaction. Each names its Reply variant.

After every start and handle_* call the host writes everything poll_transmit hands out, takes the events and the result, and arms one timer for next_timeout.

A browser host

A wasm-bindgen wrapper owns one Machine per opened Web Serial port. A sketch of a GET (Rust in the wasm module, JS glue in comments):

use satx_core::machine::{Machine, Op, Reply};
use satx_core::time::Instant;
use satx_core::{Options, TransferMode};

struct Link {
    machine: Machine,
}

impl Link {
    // JS: `port.open({ baudRate: 9600 })`, then `new Link(seed)` with a
    // seed from crypto.getRandomValues, then `link.start_connect()`.
    fn new(seed: u64) -> Self {
        Link { machine: Machine::new(Instant::now(), Options::default(), seed) }
    }

    fn start_connect(&mut self) {
        let _ = self.machine.start(Instant::now(), Op::Connect);
        self.flush();
    }

    fn start_get(&mut self, name: &str) {
        let op = Op::Get { name: name.into(), mode: TransferMode::Binary };
        let _ = self.machine.start(Instant::now(), op);
        self.flush();
    }

    // JS: the reader loop calls this with every chunk of `reader.read()`.
    fn on_bytes(&mut self, bytes: &[u8]) {
        self.machine.handle_input(Instant::now(), bytes);
        self.flush();
    }

    // JS: the timer armed in `flush` calls this.
    fn on_timer(&mut self) {
        self.machine.handle_timeout(Instant::now());
        self.flush();
    }

    fn flush(&mut self) {
        while let Some(chunk) = self.machine.poll_transmit() {
            // JS: `await writer.write(chunk)`, one write per chunk.
            let _ = chunk;
        }
        while let Some(_event) = self.machine.poll_event() {
            // Progress bar: Kermit FileStart / Progress, XModem Progress.
        }
        if let Some(result) = self.machine.poll_result() {
            match result {
                Ok(Reply::Data(_file)) => { /* hand the file to JS */ }
                Ok(_) => { /* Connect: ready for the next operation */ }
                Err(_error) => { /* show it */ }
            }
        }
        if let Some(deadline) = self.machine.next_timeout() {
            // JS: clearTimeout(t); t = setTimeout(on_timer, ms), where ms
            // is the time until `deadline`.
            let _ms = deadline.saturating_duration_since(Instant::now()).as_millis();
        }
    }
}

A PUT is the same with Op::Put { name, data, mode } and Reply::Stored(name). An XModem transfer is Op::PrepareXmodem (the program « 'NAME' XRECV » goes on the stack, the calculator leaves server mode and the reply says which key runs it: EVAL, right-shift SYMB on the 49G), then Op::XmodemSend or Op::XmodemReceive on the same machine; afterwards the user starts SERVER again and the next operation starts with Op::Connect.

The blocking API

use satx_core::{Calculator, TransferMode};

let mut calc = Calculator::open("/dev/ttyUSB0")?; // or tcp://localhost:4848
let data = calc.get("ALLB", TransferMode::Binary)?;
calc.put("COPY", &data, TransferMode::Binary)?;
# Ok::<(), satx_core::Error>(())

Licence

MIT, see AI_NOTICE and LICENSE in the repository.