Saturnus docs
Open the app

How Saturnus is built

Saturnus is an emulator of twelve HP calculators, written in Rust (opens in a new tab). One core runs in the browser as WebAssembly (opens in a new tab), natively in a desktop app and in two command-line tools. It was written from documentation and from the behaviour of the calculators' own ROMs, not from the code of other emulators. This page says how it is put together and where its limits are. The code is on GitHub (opens in a new tab) under the MIT licence.

One core, several hosts

The coreThe crate saturnus-core: the Saturn CPU, the bus with its memory controllers, the display, the keyboard, the timers, the serial port and each model's wiring. No I/O, no threads, no dependencies.
The host codesaturnus-host: what every front end shares, as one state machine. Commands and a clock go in; replies, events and a deadline come out.
In the browserThe core compiled to WebAssembly, in a Web Worker behind a static page.
On the desktopA Tauri (opens in a new tab) app: the same page, with the core linked natively on a thread of its own.
On the command linesaturnus runs a calculator without a window; satx moves files to and from real calculators.

The core knows nothing about its host. It takes a ROM, runs a number of CPU cycles, takes key presses and serial bytes, and hands back the display:

use saturnus_core::io::Key;
use saturnus_core::{Machine, Model};

let rom = std::fs::read("gxrom-r")?;
let mut m = Machine::new(Model::Hp48gx, &rom)?;

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

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());

Because the core does no I/O and starts no threads, the same code builds for wasm32 and for native targets.

What the hosts must agree on sits one layer up. The page talks to the calculator in one protocol of commands and events, and the pacing (how long to run before the next frame, when to sleep) is part of the same state machine, which has no clock, timer or thread of its own. The Web Worker and the desktop app's thread are thin drivers around it. One test script runs through the state machine with a fake clock, through the native runner and through the Worker with the real WebAssembly, and all three must produce the same transcript.

What is emulated

The emulator is the hardware; the calculator is HP's ROM. Saturnus models the Saturn CPU with its 4-bit nibbles and 64-bit registers, the memory controllers that map ROM, RAM and the card ports, the display, the key matrix, the timers and the interrupt and the serial port. Everything else is the ROM's own code: every command, menu and error message.

The target is what the ROM needs, not cycle exactness. Each instruction is charged the cycle count that HP's assembler manual gives, or on the 48GX and the later models the counts published for the 48G's processor, plus a 13% stall for the display refresh. On top of that comes a factor per model, between 1.20 and 1.34, fitted to a benchmark timed on real calculators (opens in a new tab). The cause of that factor is not known.

ModelReal calculatorSaturnus
HP 48SX, a sum of 1,000 terms95.5 s95.5 s
HP 48GX, a sum of 100 terms5.9 s5.9 s
HP 49G with ROM 2.10, 100 terms in a FOR loop5.5 s5.4 s

The 38G takes the 48GX's factor and the 39G and 40G the 49G's. The 42S, 27S, 17B, 17BII, 28S and 19BII run at 1 MHz with no factor, because none of them has been timed against a real calculator. The CPU has more on the clocks.

Some hardware is left out. The infrared port is not modelled on any model, so nothing is beamed or printed. In the app the 48SX and 48GX have no memory cards; the saturnus command takes RAM card files.

In the browser

The app is a static page: plain HTML, CSS and JavaScript modules, with no framework, no bundler and no server code. The core runs in a Web Worker at the calculator's speed (or 2×, 4×, Max), sleeps while the calculator's CPU sleeps, and sends the display to the page when it changes. Its two views, Calculator and Files, share one running calculator per model.

On the desktop

The desktop app is a Tauri 2 app with the same page as its front end. The core is linked natively and runs on its own thread, so the calculator keeps running while the window is hidden. It speaks the page's protocol, so the page does not know which host it runs on. Files gets native serial ports and the computer's folders. Installers are built for macOS on Apple silicon and for Windows and Linux on x86_64 and ARM. The macOS app is signed and notarised; the Windows installers are not signed yet.

On the command line

saturnus runs a calculator from its ROM without a window. It presses the keys listed in a script, saves the screen as text or as a PNG, saves and loads states, opens the calculator's serial port on a TCP port and serves a local control API. It is made for automated tests and scripts, not for using a calculator by hand.

satx moves files between a computer and a real HP 48 or 49G by Kermit and XModem. Its protocol code is in crates of its own, kermit-proto and xmodem-proto, which do no I/O either: they take bytes and return bytes, and so also run in the browser.

The clean-room method

Other emulators of these calculators exist, most of them under the GPL. Their source code is off limits to anyone writing Saturnus's code, human or AI, even to look up one fact. Only a reviewer who checks that Saturnus is independent of them may compare the two. Facts come from what is published: HP's manuals and journal articles, the hardware literature, the documentation and change logs of other emulators, forum posts by their authors, and runs of the ROMs themselves.

Each fact is first written down with its source in a public knowledge base, calculator-knowledgebase (opens in a new tab), and the code is written from there. A comment in the code names the page it relies on. Where the sources disagree, the comment says so and which one was followed.

One other emulator is used, as a black box: saturnng (opens in a new tab) runs in a container with the same ROM and the same keys, and the two screens are compared pixel by pixel. That comparison found a real bug: the status bits of the 48SX's card ports pair with the chip-select lines, not with the port numbers one document gives.

Some answers were in no document. The 39G and the 40G share one ROM, which tells them apart by a single input line. Which line, and how a 40G holds it, was found by running the ROM, and the 40G's page says so.

Saturnus ships no ROM: the ROMs are HP's software. saturnus rom fetch and the desktop app download a ROM from hpcalc.org (opens in a new tab) after asking, and check its size and SHA-256.

Tests

The other nine models have no other emulator to be compared with here. The 38G, 39G and 40G are tested against recorded screens, and the 38G against a real one where a result looked wrong; the 42S, 27S, 17B, 17BII, 28S and 19BII by starting, taking keys and passing their own self-tests. There is no fuzzing and there are no property tests yet.

How it was written

Parts of the code were generated by AI under human supervision; the repository's AI_NOTICE (opens in a new tab) says so. The plans of each step and the decisions taken, with their reasons, are in the repository's kb/ folder. The decision log (opens in a new tab) is the place to look for why something is the way it is.

Using the crates

The libraries are on crates.io (opens in a new tab), with their documentation on docs.rs:

cargo install saturnus satx installs the two command-line tools. The repository's README (opens in a new tab) covers building the app and the desktop app from source.

Sources