kermit-proto
A sans-IO Kermit client and server for HP calculators. The client (user
Kermit) talks to the Kermit server of an HP 48 or 49 series calculator: send
and get files, run host commands, list the directory, end server mode. The
server (Server) is the "disk drive" that the 38G, 39G and 40G send aplets
to and get them from. Both share the codec, the prefixing and the Send-Init
negotiation; this page describes the client, and the Server docs say
where the server differs.
The crate never touches a port, a clock or a file. The caller owns all three:
it reads and writes the link (a serial port, a TCP bridge to an emulator),
supplies the current Instant (see below) and loads or stores file contents.
Client is a pure state machine in between, so it runs unchanged on any
transport and is tested by replaying byte traces recorded against real
calculator ROMs.
Supported: short packets (up to 94 bytes), block checks 1, 2 and 3, control
prefixing, 8th-bit prefixing and repeat compression as negotiated in the
Send-Init exchange, and the server commands R (get), S (send), C (host
command), G D (directory), G F (finish), G L (logout) and I (info).
Not supported: long packets and sliding windows (the HP calculators use
neither); attribute packets are acknowledged and ignored.
The seam
Client::start(now, command)begins a transaction; the first packet is queued at once.Client::handle_input(now, bytes)feeds bytes read from the link, in any chunking.Client::handle_timeout(now)tells the client time has passed; call it whenClient::next_timeout()is reached (it does nothing early).Client::poll_output(now)hands out the next packet to write: exactly one packet including padding and EOL. The transport must put it on the wire as one unit, without inter-byte gaps (see the HP notes below).Client::poll_event()yields events:FileStart,Data,Progress,FileEnd,ServerTextand finally exactly oneDoneorError.Client::next_timeout()is when the client wants to be called again; use it as the read timeout.
After Done or Error keep calling poll_output until it returns None: the
final ACK or an E packet may still be queued. After a receive the client
lingers briefly (Config::linger) to re-ACK a retransmitted B packet, in
case its final ACK was lost; keep driving it until next_timeout() is None,
or start the next command.
Time and WebAssembly
The state machine never reads a clock; every call that needs the time takes
now from the caller. The type is kermit_proto::time::Instant: std::time::Instant
on every target except wasm32, where it is web_time::Instant from the
web-time crate, because
std::time::Instant::now() panics on wasm32-unknown-unknown. A wasm caller
creates it with Instant::now() from web-time (or kermit_proto::time::Instant::now()),
which reads performance.now() in the browser. kermit_proto::time::Duration is
core::time::Duration everywhere. Native callers use std::time as before.
Driver loop
use ;
use TcpStream;
use ;
use ;
HP calculator notes
- Each packet must reach the wire as one unit: inter-byte gaps overrun the
HP's receiver. This is a requirement on the transport, not something
write_allguarantees (it may split the buffer into several writes). On a TCP socket to an emulator, or a serial port whose driver buffers a whole packet, onewrite_allper packet is enough; otherwise buffer the packet and hand it to the port in one call. - In server mode the HP periodically NAKs packet 0 while idle, so a stale NAK
can be waiting right after connecting. Discard input for about 0.5 s after
opening the link; the client also tolerates a stale NAK that slips through
(
Config::nak_grace). - The HP drops a command packet that arrives right after the final ACK of the previous transaction; leave a short pause (about 200 ms) between transactions.
- Commands go out before any parameter exchange, so their data must fit in one
packet under the default MAXL of 80 with block check 1;
Client::startrefuses longer ones. - The HP runs a host command (
C) when it receives it and cannot tell a resend from a new command:Config::first_packet_retries = Some(0)sends it once. The HP also NAKs aCit rejects, right after it arrives (11 ms on a 48SX), and that NAK looks exactly like the periodic idle one. Since 0.1.1,Config::first_packet_nak_window(the packet's time on the wire plus slack),Config::first_packet_nak_graceandConfig::first_packet_nak_byte_time(lower bound: a NAK sooner than the packet's wire time is stale) let a NAK inside the window allow one resend if no answer follows within the grace. - A host command's reply arrives either in the ACK (short reply) or as a
text transfer (
X,D..,Z,B); both end up asEvent::ServerText.
Lower layers
codec (framing, block checks, the deframer), prefix (control, 8th-bit and
repeat prefixing), params (Send-Init negotiation) and trace (a text format
for byte traces) are public for tools and tests.
License
MIT