satx_core/lib.rs
1//! HP calculator layer on top of `kermit-proto` and `xmodem-proto`:
2//! transports, the Kermit and XModem driver loops, server commands, the HP
3//! object format and GROBs.
4//!
5//! # Two faces, one protocol core
6//!
7//! The protocol logic (Kermit session, calculator operations, XModem) never
8//! reads a clock, sleeps or touches a port. It runs behind either face:
9//!
10//! - **Blocking**: [`Calculator`], [`Session`], [`XmodemSession`] and
11//! [`XservSession`] over a
12//! [`transport::Transport`] (serial port, TCP, the in-process Saturnus
13//! emulator, memory), with the system clock. This is what the satx CLI
14//! uses.
15//! - **Sans-I/O**: [`Machine`] is fed bytes and the caller's time and hands
16//! out bytes to write, progress events and the [`Reply`] of each
17//! [`Op`]. Nothing blocks, so it runs where bytes arrive by callback: a
18//! browser with Web Serial on `wasm32-unknown-unknown`, an event loop, a
19//! GUI thread. See [`machine`] for the calling convention and a host loop.
20//!
21//! # Features
22//!
23//! - `native` (default): serial ports (`serialport`) and TCP, opened by
24//! [`transport::open`].
25//! - `saturnus` (opt-in; satx turns it on): the Saturnus emulator
26//! in-process (`saturnus://[MODEL@]ROM` addresses), through
27//! `saturnus-core` and `saturnus-drive`.
28//!
29//! Without either the crate does no OS I/O and builds for
30//! `wasm32-unknown-unknown`:
31//! `satx-core = { version = "0.2", default-features = false }`. There the
32//! blocking face ([`Calculator`], [`Session`], [`XmodemSession`],
33//! `transport::MemoryTransport`, `transport::drain`) is left out: it
34//! sleeps and blocks, which that target cannot.
35//!
36//! The clock type is [`time::Instant`]: `std::time::Instant` on native
37//! targets, `web_time::Instant` on wasm32.
38//!
39//! # Modules
40//!
41//! - [`machine`]: the sans-I/O face ([`Machine`], [`Op`], [`Reply`],
42//! [`Progress`]).
43//! - [`transport`]: blocking links ([`transport::open`]).
44//! - [`session`]: drives a [`kermit_proto::Client`] ([`Session`]).
45//! - [`calc`]: what a user does with a calculator: list, get, put, run host
46//! commands, PICT, backup and restore ([`Calculator`]).
47//! - [`reply`]: parsers for the server's text replies (`G D` listings and the
48//! stack text returned for a `C` host command).
49//! - [`object`]: `HPHP48-x` / `HPHP49-x` binary files, prologs, object
50//! length walk, `%%HP:` ASCII headers.
51//! - [`names`]: variable names to file names and back (`NAME.hp`,
52//! `NAME.txt`, `%XX` for what a file system refuses), and what a file
53//! holds ([`names::FileKind`]).
54//! - [`grob`]: GROB decoding and PNG export.
55//! - [`charset`]: the HP character set and its ASCII trigraphs.
56//! - [`xmodem`]: XModem transfers with `XRECV`/`XSEND` started on the
57//! calculator ([`XmodemSession`]).
58//! - [`xserv`]: XSERV (49g+/50g, the 49G): framing, the detection probe and
59//! a client ([`XservSession`]); tested on a real 49G and the emulated one.
60//! - `filer` (not on wasm32): the HP 100LX/200LX palmtops' Filer server
61//! over a transport, on `filer-proto` (`Palmtop`).
62//!
63//! Wiki references (calculator-knowledgebase,
64//! <https://github.com/ractive/calculator-knowledgebase>): `protocols/server-commands`,
65//! `protocols/hp-object-format`, `protocols/iopar`, `hardware/uart`,
66//! `protocols/xmodem-hp`, `protocols/xserv`, `protocols/filer-hplx`.
67
68pub mod calc;
69pub mod charset;
70mod error;
71// Blocking, like `Calculator`: not in the wasm32 build, where
72// `filer_proto::Session` itself is the face.
73#[cfg(not(target_arch = "wasm32"))]
74pub mod filer;
75pub mod grob;
76mod link;
77pub mod machine;
78pub mod names;
79pub mod object;
80pub mod reply;
81pub mod session;
82pub mod transport;
83mod watchdog;
84pub mod xmodem;
85pub mod xserv;
86
87/// The clock types of the whole crate: those of
88/// [`kermit_proto::time`] (`std::time` on native targets, `web_time` on
89/// wasm32, where `std::time::Instant::now()` panics).
90pub mod time {
91 pub use kermit_proto::time::{Duration, Instant};
92}
93
94// The blocking face waits by sleeping or by blocking reads, which
95// wasm32-unknown-unknown cannot do (`std::thread::sleep` panics there): it
96// is left out of that build, where `Machine` is the face.
97#[cfg(not(target_arch = "wasm32"))]
98pub use calc::Calculator;
99pub use calc::{Model, TransferMode};
100pub use error::{Error, Result, SerialError};
101pub use filer_proto;
102pub use machine::{Machine, Op, Progress, Reply};
103pub use session::Options;
104#[cfg(not(target_arch = "wasm32"))]
105pub use session::Session;
106pub use xmodem::XmodemOptions;
107#[cfg(not(target_arch = "wasm32"))]
108pub use xmodem::XmodemSession;
109pub use xmodem_proto;
110pub use xserv::XservOptions;
111#[cfg(not(target_arch = "wasm32"))]
112pub use xserv::XservSession;