saturnus-core 0.12.1

Headless, clean-room emulator of the HP Saturn calculators (core library)
Documentation
# saturnus-core

Core library of [Saturnus](https://github.com/ractive/saturnus), a
headless emulator of the HP Saturn calculators: HP 48SX, 48GX, 49G, 38G,
39G, 40G, 42S, 27S, 17BII, 17B, 28S and 19BII. It models the Saturn CPU, the bus with its
memory-mapped modules, the display, keyboard, timers and serial port, and
the per-model machine wiring. No I/O and no threads: the crate builds for
`wasm32-unknown-unknown` and has no dependencies.

It is a clean-room implementation, written from public hardware
documentation and observed behaviour, not from the source code of other
emulators. No ROM is included: you supply the ROM file of a calculator
you own, or one HP allows to be downloaded for emulator use (the
`saturnus` command-line tool from the
[`saturnus`](https://crates.io/crates/saturnus) crate fetches
those from hpcalc.org and verifies them).

## Usage

```rust,no_run
use saturnus_core::io::Key;
use saturnus_core::{Machine, Model};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let rom = std::fs::read("gxrom-r")?;
    let mut m = Machine::new(Model::Hp48gx, &rom)?;

    // Run two seconds of machine time (the 48GX runs at 4 MHz).
    m.run_cycles(8_000_000).map_err(|h| format!("halted: {h:?}"))?;

    // Press and release a key.
    m.key_down(Key::Enter)?;
    m.run_cycles(200_000).map_err(|h| format!("halted: {h:?}"))?;
    m.key_up(Key::Enter)?;

    // The screen as text (one character per pixel)...
    println!("{}", m.lcd().to_text());

    // ...and the serial port, byte by byte.
    m.serial_push(b"\x01");
    let reply: Vec<u8> = m.serial_drain();
    println!("{} bytes from the calculator", reply.len());
    Ok(())
}
```

Related crates: [`saturnus-objects`](https://crates.io/crates/saturnus-objects)
reads RPL objects and the user memory of a paused machine;
[`saturnus-drive`](https://crates.io/crates/saturnus-drive) drives a
machine from a native host (key scripts, idle waits, screen images).

## Licence

MIT. Parts of the code were generated by AI systems under human
supervision; see the repository's `AI_NOTICE`.