saturnus 0.11.0

The saturnus emulator of HP calculators on the command line: run ROMs, play key scripts, save screens, serve the serial port and the control API
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

# saturnus

The `saturnus` command: an emulator of the HP Saturn calculators (HP 48SX,
48GX, 49G, 38G, 39G, 40G, 42S, 27S, 17BII, 17B, 28S and 19BII) for the
command line, built on
[`saturnus-core`](https://crates.io/crates/saturnus-core). Part of
[saturnus](https://github.com/ractive/saturnus), which also runs in the
browser (<https://ractive.ch/saturnus/>) and as a desktop app.

```sh
cargo install saturnus
```

Prebuilt binaries for Linux, macOS and Windows are on the
[releases page](https://github.com/ractive/saturnus/releases).

## ROMs

No ROM is included. `saturnus rom fetch` downloads the ROM files HP
allows for emulator use (48SX, 48GX, 38G, 49G, 39G/40G) from hpcalc.org
after asking, and checks their size and SHA-256:

```sh
saturnus rom fetch --model 48gx --dir roms
```

The 42S, 27S, 17BII, 17B and 28S ROMs were never released: read the ROM
out of your own calculator. The 19BII cannot read out its own ROM; use a
ROM file you already have.

## What it does

```sh
# Start, play a key script, save the screen (text or PNG) and the state.
saturnus run --model 48gx --rom roms/gxrom-r --keys keys.txt \
    --screen out.png --save boot.state

# Serve the serial port (tcp:4841, for Kermit clients) and the control
# API (HTTP + JSON on 127.0.0.1:4840) until Ctrl-C.
saturnus run --model 48gx --rom roms/gxrom-r --serve

# Control the running calculator: keys, screen, stack.
saturnus ctl --help

# Look up a built-in command (48SX, 48GX, 49G, 28S): description, stack
# effect, menu, examples run in saturnus, manual pages. A function of
# the 42S, 27S, 17BII, 17B, 19BII, 38G, 39G or 40G with --model: its
# keys instead of a menu.
saturnus ref "->LIST"
saturnus ref "->POL" --model 42s
saturnus ref COMB --model 39g

# Disassemble ROM code.
saturnus disasm --rom roms/gxrom-r --at 0 --count 20
```

A key script is one action per line:

```text
# boot, answer "Try To Recover Memory?" with NO
wait-idle 60000
press f
press 2
press enter
```

The full documentation (options, the control API and its token, key
names per model, the serial bridge) is in the
[repository's README](https://github.com/ractive/saturnus#readme).

## Clean room

saturnus is written from public hardware documentation and observed
behaviour, not from the source code of other emulators. Parts of the code
were generated by AI systems under human supervision (see `AI_NOTICE` in
the repository).

## Licence

MIT.