Skip to main content

Crate satx_core

Crate satx_core 

Source
Expand description

HP calculator layer on top of kermit-proto and xmodem-proto: transports, the Kermit and XModem driver loops, server commands, the HP object format and GROBs.

§Two faces, one protocol core

The protocol logic (Kermit session, calculator operations, XModem) never reads a clock, sleeps or touches a port. It runs behind either face:

  • Blocking: Calculator, Session, XmodemSession and XservSession over a transport::Transport (serial port, TCP, the in-process Saturnus emulator, memory), with the system clock. This is what the satx CLI uses.
  • Sans-I/O: Machine is fed bytes and the caller’s time and hands out bytes to write, progress events and the Reply of each Op. Nothing blocks, so it runs where bytes arrive by callback: a browser with Web Serial on wasm32-unknown-unknown, an event loop, a GUI thread. See machine for the calling convention and a host loop.

§Features

  • native (default): serial ports (serialport) and TCP, opened by transport::open.
  • saturnus (opt-in; satx turns it on): the Saturnus emulator in-process (saturnus://[MODEL@]ROM addresses), through saturnus-core and saturnus-drive.

Without either the crate does no OS I/O and builds for wasm32-unknown-unknown: satx-core = { version = "0.2", default-features = false }. There the blocking face (Calculator, Session, XmodemSession, transport::MemoryTransport, transport::drain) is left out: it sleeps and blocks, which that target cannot.

The clock type is time::Instant: std::time::Instant on native targets, web_time::Instant on wasm32.

§Modules

  • machine: the sans-I/O face (Machine, Op, Reply, Progress).
  • transport: blocking links (transport::open).
  • session: drives a kermit_proto::Client (Session).
  • calc: what a user does with a calculator: list, get, put, run host commands, PICT, backup and restore (Calculator).
  • reply: parsers for the server’s text replies (G D listings and the stack text returned for a C host command).
  • object: HPHP48-x / HPHP49-x binary files, prologs, object length walk, %%HP: ASCII headers.
  • names: variable names to file names and back (NAME.hp, NAME.txt, %XX for what a file system refuses), and what a file holds (names::FileKind).
  • grob: GROB decoding and PNG export.
  • charset: the HP character set and its ASCII trigraphs.
  • xmodem: XModem transfers with XRECV/XSEND started on the calculator (XmodemSession).
  • xserv: XSERV (49g+/50g, the 49G): framing, the detection probe and a client (XservSession); tested on a real 49G and the emulated one.
  • filer (not on wasm32): the HP 100LX/200LX palmtops’ Filer server over a transport, on filer-proto (Palmtop).

Wiki references (calculator-knowledgebase, https://github.com/ractive/calculator-knowledgebase): protocols/server-commands, protocols/hp-object-format, protocols/iopar, hardware/uart, protocols/xmodem-hp, protocols/xserv, protocols/filer-hplx.

Re-exports§

pub use calc::Calculator;
pub use calc::Model;
pub use calc::TransferMode;
pub use machine::Machine;
pub use machine::Op;
pub use machine::Progress;
pub use machine::Reply;
pub use session::Options;
pub use session::Session;
pub use xmodem::XmodemOptions;
pub use xmodem::XmodemSession;
pub use xserv::XservOptions;
pub use xserv::XservSession;
pub use filer_proto;
pub use xmodem_proto;

Modules§

calc
What a user does with a calculator in Kermit server mode: list, change directory, get, put, run host commands, fetch PICT, backup and restore.
charset
The HP 48/49 character set and the ASCII trigraphs of the transfer translation modes: saturnus-objects’ table, with this crate’s Error on the encoding side.
filer
The HP 100LX/200LX palmtops: their Filer in server mode over a Transport, blocking, on the system clock (Palmtop). The protocol is filer-proto’s; this module only drives its Session (wiki: protocols/filer-hplx).
grob
GROB (graphic object) decoding, encoding and PNG export.
machine
The sans-I/O face of satx-core: a Machine is fed bytes, time and link errors, and hands out bytes to write, progress events and the result of each operation. It never reads a clock, sleeps, blocks or touches a port, so it runs where the bytes arrive by callback: a browser with Web Serial (WebAssembly), an event loop, a GUI thread.
names
Variable names to file names and back, and what a file holds (kb/docs/saturnus-tx.md, “File names”). The satx CLI and saturnus-tx (the web page, the desktop app) name files the same way.
object
The HP object format: HPHP48-x / HPHP49-x binary transfer files, nibble packing, prologs, the object length walk and %%HP: ASCII headers.
reply
Parsers for the text a calculator in Kermit server mode returns: the stack display of a host command (C) and the directory listing (G D).
session
Drives a kermit_proto::Client over a byte link.
time
The clock types of the whole crate: those of kermit_proto::time (std::time on native targets, web_time on wasm32, where std::time::Instant::now() panics).
transport
Blocking links to a calculator: serial port and TCP (emulator) with the native feature (default), the Saturnus emulator in-process (HP 48SX, 48GX or 49G, chosen in the saturnus://MODEL@ROM address) with the saturnus feature, and in-memory (tests).
xmodem
Drives an xmodem_proto::Transfer over a byte link: XModem transfers with the calculator’s XRECV and XSEND.
xserv
XSERV: the command server on top of XModem (49g+/50g, the 49G after ROM 1.10, and the XSrvr48 library on the 48): packet framing, commands, the directory listing, the detection probe, and a client over the link.

Structs§

SerialError
The serial port’s error inside Error::Serial: a serialport::Error with the native feature; without it no value exists.

Enums§

Error
Everything that can go wrong talking to a calculator.

Type Aliases§

Result
Result with Error.