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,SessionandXmodemSessionover atransport::Transportwith the system clock. ThesatxCLI uses these. - Sans-I/O:
Machineis 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 onwasm32-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:
= { = "0.2", = 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 ;
use Instant;
use ;
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 ;
let mut calc = open?; // or tcp://localhost:4848
let data = calc.get?;
calc.put?;
# Ok::
Licence
MIT, see AI_NOTICE and LICENSE in the repository.