Expand description
Sans-IO XModem for talking to HP calculators: 128-byte and 1k blocks, checksum and CRC-16, both roles.
The crate never touches a port, a clock or a file. The caller owns all
three: it reads and writes the link, supplies the current Instant
(time::Instant) and loads or stores file contents. Transfer is a
pure state machine in between, with the same seam as kermit-proto.
- Sender (
Command::Send): the calculator runsXRECV. We wait for its start character, NAK (checksum),C(CRC-16) orD(HP’s CRC,Check::HpCrc), and use whichever it asks for. The 49G asks withD, the 48GX with NAK. - Receiver (
Command::Receive): the calculator runsXSEND. We sendD(by default; seeConfig::check)Config::crc_attemptstimes, then fall back to NAK (checksum). The 49G answersD, the 48GX only NAK; neither answersC.
HP specifics live in the caller: starting XRECV/XSEND on the
calculator, and stripping the padding of the last block (the receiver hands
back every byte it received; Event::FileEnd says how much padding there
can be).
§Starting a transfer on the calculator
XRECV and XSEND do not run inside the Kermit server: sent as a Kermit
C packet, both fail with “Port Not Available” on the 49G and the 48GX,
even after CLOSEIO. The server answers the C packet with its usual
reply (S, X, D packets carrying the error and the stack, which still holds
the name) and stays in server mode. The calculator must leave the server
(Kermit FINISH, or ON) and run the command itself, e.g. typed on the
keyboard. The machine tolerates a Kermit packet in the pipe before the
first start character or block. Verified on the emulated 49G and 48GX
(traces 49g-server-xrecv, 48gx-server-xsend).
§The seam
Transfer::startbegins a transfer. A receiver’s first start character is queued at once; a sender waits for the receiver.Transfer::handle_inputfeeds bytes read from the link, in any chunking. Bytes of a Kermit packet (SOH .. CR) that arrive before the transfer starts are skipped.Transfer::handle_timeouttells the machine that time has passed; call it whenTransfer::next_timeoutis reached (it does nothing early).Transfer::poll_outputhands out the next write: one whole block, one control byte, or the CAN sequence. The transport must put each on the wire as one unit, without inter-byte gaps, because gaps overrun the HP’s receiver.write_allalone does not promise that (it may issue several writes); it is enough where one write of a buffer this size is not split, as on a TCP socket to an emulator or a serial port with a large enough output buffer.Transfer::poll_eventyieldsEvents:Started,Progress, a receiver’sFileEnd, and finally exactly oneDoneorError.Transfer::next_timeoutis the earliest instant at which the machine wants to be called again (reply deadline, start-character interval, inter-byte timeout, quiet line before a NAK, end of the linger). Use it as the read timeout.
Every call that can queue output takes now, so retransmit deadlines are
computed from the caller’s clock. After Done or Error keep calling
poll_output until it returns None: the final ACK or the CANs may still
be queued. A receiver then lingers for Config::linger to re-ACK a
retransmitted EOT in case the final ACK was lost; keep driving it until
Transfer::next_timeout is None, or Transfer::start the next
transfer, which ends the linger.
§Time and WebAssembly
The state machine never reads a clock: every call that needs the time
takes now from the caller. The type is time::Instant, which is
std::time::Instant on every target except wasm32, where it is
web_time::Instant from the web-time crate
(std::time::Instant::now() panics on wasm32-unknown-unknown). A wasm
caller names it as xmodem_proto::time::Instant and creates it with
Instant::now(), which web-time backs with performance.now() in the
browser. time::Duration is core::time::Duration everywhere.
§Driver loop
use std::io::{ErrorKind, Read, Write};
use std::net::TcpStream;
use std::time::{Duration, Instant};
use xmodem_proto::{Command, Config, Event, Transfer};
fn main() -> std::io::Result<()> {
let mut link = TcpStream::connect("localhost:4848")?;
let mut xfer = Transfer::new(Config::default());
xfer.start(Instant::now(), Command::Receive)
.map_err(std::io::Error::other)?;
let mut finished = false;
let mut buf = [0u8; 2048];
loop {
let now = Instant::now();
while let Some(bytes) = xfer.poll_output(now) {
// A whole block per call; the link must not split it.
link.write_all(&bytes)?;
}
while let Some(event) = xfer.poll_event() {
match event {
Event::FileEnd { data, .. } => std::fs::write("file.hp", data)?,
Event::Done | Event::Error(_) => finished = true,
_ => {}
}
}
let wait = match xfer.next_timeout() {
Some(t) => t.saturating_duration_since(now),
None if finished => break, // idle and nothing left to write
None => Duration::from_millis(100),
};
link.set_read_timeout(Some(wait.max(Duration::from_millis(10))))?;
match link.read(&mut buf) {
Ok(0) => break,
Ok(n) => xfer.handle_input(Instant::now(), &buf[..n]),
Err(e) if matches!(e.kind(), ErrorKind::WouldBlock | ErrorKind::TimedOut) => {
xfer.handle_timeout(Instant::now())
}
Err(e) => return Err(e),
}
}
Ok(())
}The block layer is public for tools and tests: codec (control bytes,
framing, checksum and CRC-16).
Re-exports§
Modules§
- codec
- XModem block framing and block checks.
- time
- The clock types of the seam:
std::timeeverywhere exceptwasm32, where they come fromweb-time(see the crate docs, “Time and WebAssembly”).
Structs§
- Config
- Tunables of a
Transfer. - Transfer
- Sans-IO XModem transfer, sender or receiver. See the crate documentation for the driver loop.
Enums§
- Command
- One transfer.
- Error
- Why a transfer failed.
- Event
- Something that happened during a transfer.
- Start
Error - Why
Transfer::startrefused a command.