Getting Started

0•X — BCH prototype. You are aboard a small ship. It is a real machine: its power, cooling, air, and propulsion are simulated systems that genuinely work and genuinely fail, and the computer that runs it is a real emulated 16-bit processor you can program. Power it on, learn it, break it, fix it.

This is the BCH prototype — a proof of the core systems. There is no flight, saving, or story yet; the ship holds station while you operate and diagnose it. See the manual sections below for the full computer and ship references.

Running it

• Windows (x64). Double-click 0X-BCH.exe. It is self-contained — nothing to install.
• Graphics: needs a GPU with Vulkan or DX12 (any reasonably modern card). Runs windowed.
• Nothing is written to disk during normal play.

Controls

First five minutes

1. Power up. Walk to the console and click the boot button (it glows amber; it turns green). The ship energizes and the CRT runs its self-test → BOOT OK → the AOS> prompt.
2. Use the computer. Click the CRT to sit. Type a sum: 2 3 + . → 5 ok. Define your own word: : SQUARE DUP * ; then 5 SQUARE . → 25. Type WORDS to see the vocabulary, HELP for help.
3. Read the ship. Try STATUS, or a subsystem summary: PWR, ENV, PROP, DOCK. Watch the analog gauges on the walls — they read the physics directly.
4. Break something, then fix it. The prototype ships with authored failure scenarios (a docking fault, a failed coolant pump, a stuck thruster, a cabin leak). Each is solvable two distinct ways — one at the terminal, one by hand (breakers, switches, hatches). See Diagnostic Scenarios below for the walkthroughs.
5. Start over. The dockside console (three buttons) resets the ship to run a scenario again — even if you've crashed the computer.

Where to find things

• AeturnisOS Operator's Quickstart / Reference — the full command vocabulary and the machine monitor. Start with the Quickstart.
• A16 Programmer's Quickstart / Reference — the processor itself, if you want to write in assembly or understand the machine underneath.
• Diagnostic Scenarios — the failures and the two ways to fix each.
• Ship Components — datasheets for the hardware aboard.
• In the running system: HELP and WORDS are always there at the prompt.

AeturnisOS — Operator's Quickstart

AETURNIS DEVELOPMENT LABORATORIES · ADL‑AOS‑QS · Rev. AeturnisOS 0.3 For the operator at the terminal. No prior training assumed. Companion volume: AeturnisOS Operator's Reference (ADL‑AOS‑REF).

This will take you from a dark screen to teaching the machine your own commands. Work through it at the terminal, typing each line and pressing RETURN. You cannot break anything from here that a restart will not fix.

1. Waking the machine

Apply power. The terminal runs its power-on self test and reports:

AETURNIS SYSTEMS
AOS 0.3  1199 AW

MEM ........ OK
CPU ........ A16/01
DEV 00 ..... DISPLAY
DEV 01 ..... KEYBOARD
DEV 02 ..... CLOCK

BOOT OK  (FORTH; MON for monitor)

Below BOOT OK the machine is waiting for you. There is no prompt symbol — the cursor simply sits there. This is normal. Type a line and press RETURN; the machine does the work and answers with ok when the line is done.

If nothing you type appears, you are not at the terminal — in a vessel that means you are in piloting control. Press Tab to sit down at the terminal.

2. The one idea: the stack

AeturnisOS works a way that looks backwards for about five minutes and then never looks backwards again. You put values down, then you act on them. Values wait on a pile called the stack. The most recent value sits on top.

To add two and three, you put down 2, put down 3, then say "add":

2 3 +

2 and 3 go on the stack; + takes the top two, adds them, and leaves 5. Nothing has been shown yet — the 5 is just sitting on the stack. To print the top value, use . (a full stop):

2 3 + .

The machine answers:

5  ok

That is the whole model. Numbers go on the stack; words act on what is there. Words come after the values they work on. (If you have used a desk calculator with an "enter" key, you already know this.)

3. Arithmetic

All five basic operations work the same way — values first, then the word:

10 3 - .      ->  7
6 7 * .       ->  42
20 4 / .      ->  5
17 5 MOD .    ->  2     (the remainder)

Numbers are whole numbers and may be negative — write a leading minus with no space:

-5 .          ->  -5
3 10 - .      ->  -7

Careful: dividing by zero is a genuine fault. The machine will stop what it is doing and drop you into the monitor (see §8). Nothing is damaged; type FORTH and RETURN to come back.

4. Showing things

• . prints the top value (and removes it), followed by a space.
• CR starts a new line.
• EMIT prints a single character by its code. For example 65 EMIT prints A.

65 EMIT 66 EMIT 67 EMIT     ->  ABC

5. Moving values around

You will often need to rearrange the stack. These five words are your hands:

A worked example — double a number by duplicating it and adding:

7 DUP + .     ->  14

7 is on the stack; DUP makes it 7 7; + adds them to 14; . prints it.

6. Teaching the machine a word

This is the step that matters. You are not using a fixed set of commands — you are growing the set. To define a new word, open with :, give it a name, list what it does, and close with ;.

Define SQUARE to mean "duplicate, then multiply" (a number times itself):

: SQUARE DUP * ;

The machine answers ok. SQUARE is now a word like any other:

5 SQUARE .    ->  25
9 SQUARE .    ->  81

Your new word can be used inside the next one. Define CUBE using SQUARE:

: CUBE DUP SQUARE * ;
7 CUBE .      ->  343

Words you define stay defined until the power drops. This is how the machine becomes your machine: a vocabulary of exactly the operations your work needs.

7. Decisions and repetition

Inside a definition you can choose and repeat.

Choosing — IF … THEN, or IF … ELSE … THEN. The word IF acts on the top of the stack: anything non-zero means "yes." A test like < (less-than) leaves -1 for true and 0 for false.

: SIGN?  DUP 0 < IF  DROP -1  ELSE  0 > IF 1 ELSE 0 THEN  THEN ;
-4 SIGN? .    ->  -1
 9 SIGN? .    ->  1

Repeating — BEGIN … UNTIL runs the middle until the top of the stack is non-zero (true). This counts down from a number, printing each step:

: COUNTDOWN  BEGIN  DUP .  1 -  DUP 0 =  UNTIL  DROP ;
3 COUNTDOWN   ->  3 2 1

Don't worry if the loop reads strangely at first; the Reference walks through it.

8. Finding your way, and getting unstuck

• WORDS lists every word the machine currently knows — the built-ins and the ones you have taught it.
• HELP prints a one-line reminder.
• If you type a word the machine does not know, it echoes the word and a ?:

FOOBAR ?

Check your spelling (the machine does not care about upper or lower case) and that the word is defined.

• The machine monitor is the floor beneath AeturnisOS — a bare tool for looking directly at memory. Enter it with MON; it shows an AOS> prompt. To return to normal operation, type FORTH. You will also land here automatically if something faults (a divide-by-zero, say); the same FORTH brings you back.

Where to go next

Looking at the ship

AeturnisOS 0.2 knows the ship around you. Type STATUS for a whole-ship dashboard — one line per subsystem (power, environment, propulsion, dock) with its alarm state. For a single reading, the ship's sensors have plain names:

COOLANT.TEMP .1      \ coolant temperature, one decimal:  31.8
CABIN.PRESS .1       \ cabin pressure in kPa

A reading can be stale or faulted, and you never want to act on a bad number. The ? form gives you the value and its quality together — stock words use it, and so can you. To command the ship, conservative words like 200 PUMP! ask a controller for a setpoint and report whether it was accepted; you then read the telemetry to see the ship actually respond. The complete device vocabulary is in the Reference, §7.

If a program you start never stops, press the stop key: a BEGIN … AGAIN loop halts and the prompt returns, with your definitions intact.

You now know enough to do real work: arithmetic, printing, rearranging the stack, defining your own words, and reading the ship. When you want the complete vocabulary, the monitor commands, and a map of the machine's memory, open the AeturnisOS Operator's Reference.

When you are ready to write for the processor underneath AeturnisOS — your own instructions, in the A16's own language — that is the Programmer's track.

The machine is small on purpose. You can learn all of it. Most operators do.

AeturnisOS — Operator's Reference

AETURNIS DEVELOPMENT LABORATORIES · ADL‑AOS‑REF · Rev. AeturnisOS 0.3 (A16/01) The complete operating vocabulary, the machine monitor, and the memory of the system. New operators should read the Quickstart first.

1. The system at a glance

AeturnisOS is the resident software of the Aeturnis A16 computer. It presents a Forth environment: an interactive language in which the command line and the programming language are the same thing. You type words; the machine runs them; you define new words out of old ones. Everything you teach it persists until power is lost.

The machine keeps two stacks:

• the data stack, which holds the values you are working on; and
• the return stack, which the machine uses internally to keep its place while running a definition. Operators rarely touch it directly.

When you talk about "the stack," you mean the data stack. Its top is the most recently added value.

On power-up the system runs a self test (the POST — banner, memory check, device inventory), prints BOOT OK, and hands control to you. There is no prompt character: type a line, press RETURN, and the system runs it and prints ok.

2. Conventions

Stack-effect notation. Each word below is annotated ( before -- after ), showing the stack from bottom to top on the right. So ( a b -- b a ) means the word takes two values and leaves them swapped.

3. The word vocabulary

3.1 Stack manipulation

3.2 Arithmetic

/ and MOD with a divisor of zero raise a fault and drop you into the monitor (§6, §10). Guard against it, or be ready to type FORTH to return.

3.3 Comparison and logic

Comparisons leave a truth value (-1 or 0). Comparisons are signed.

AND/OR/XOR operate bit by bit. Because true is -1 (all bits set) and false is 0 (no bits set), they also serve as logical connectives on truth values.

3.4 Memory

The A16 addresses memory in words (16-bit cells), not bytes. An address is just a number.

Example — write 1234 into cell 0x1500 and read it back (decimally, 5376 and 4660):

4660 5376 !        ( store 4660 at address 5376 )
5376 @ .           ->  4660

The memory map is §7. You can read or write any address, including the screen (§8) — that is a feature, and occasionally a foot-gun.

3.5 Output and input

KEY waits: the processor sleeps until a key is pressed (it does not burn effort spinning). It returns the key's code — 10 for RETURN, 8 for BACKSPACE, otherwise the character's code.

3.6 Dictionary and system

3.7 Defining and control (compile-time)

These words are used while building a definition (between : and ;). See §4 and §5.

4. Defining words

A colon definition teaches the machine a new word:

: NAME  words that make up the word  ;

: reads the next token as the new name and switches the machine into compile mode — from here, words are recorded rather than run. ; closes the definition, records a return, and publishes the word so it can be used.

: DOUBLE  DUP + ;
: QUAD    DOUBLE DOUBLE ;
5 QUAD .      ->  20

A definition may use any word already defined, including ones you defined moments ago. It may not refer to itself by name while being compiled (the name is not published until ;).

EXIT returns from a definition before its end — useful inside a conditional:

: SAFE/  DUP 0 = IF DROP DROP 0 EXIT THEN  / ;
10 2 SAFE/ .   ->  5
10 0 SAFE/ .   ->  0     ( guarded: no divide-by-zero )

Numbers inside definitions are handled for you: a literal you write between : and ; is compiled so that it pushes itself at run time. (Internally this uses LITERAL; you rarely name it directly.)

HERE and , expose the compile pointer for building data. HERE gives the current address; , lays a value there and advances. Together they let a definition build tables in memory. New definitions begin compiling at address 0x4000 and grow upward (§7).

5. Control structures

Control words are used inside definitions. (They work by laying down branches as the definition compiles, so they have no useful effect typed on their own.)

Conditional — IF … THEN / IF … ELSE … THEN

At run time, IF removes the top of the stack. If it is non-zero (true), the words up to ELSE (or THEN) run; otherwise they are skipped, and the ELSE words (if any) run instead.

: EVEN?  ( n -- )  2 MOD 0 = IF 1 . ELSE 0 . THEN ;
4 EVEN?    ->  1
7 EVEN?    ->  0

4 2 MOD is 0, so 0 = is true and the IF branch prints 1; 7 2 MOD is 1, so the ELSE branch prints 0. (A flag of -1/0 is what IF consumes.)

Loop — BEGIN … UNTIL

BEGIN marks the top of the loop. The words run, then UNTIL removes the top of the stack: if it is false (0) the loop repeats; if true it ends.

: COUNTDOWN  ( n -- )
   BEGIN
     DUP .            ( show the counter )
     1 -              ( decrement )
     DUP 0 =          ( reached zero? )
   UNTIL
   DROP ;
5 COUNTDOWN    ->  5 4 3 2 1

Build loops so the test is reached and eventually true. A loop whose test never becomes true runs forever — recover with a restart, or set a breakpoint (§6) if you are debugging one.

6. The machine monitor

Beneath AeturnisOS is the monitor: a small, always-available tool for inspecting and altering memory directly. It is the recovery floor — you reach it deliberately with MON, and you are dropped into it automatically by a fault. It shows an AOS> prompt.

All monitor numbers are hexadecimal, written without a prefix (8000, not 0x8000).

Anything the monitor does not recognise is echoed with ?.

AOS> POKE 1500 BEEF
AOS> PEEK 1500
1500: BEEF
AOS> DUMP 1500
1500: BEEF 0000 0000 0000 0000 0000 0000 0000
AOS> FORTH

Breakpoints. BP <addr> plants a breakpoint instruction at an address and remembers what was there. When execution reaches it, the processor traps and the monitor reports BRK @ <addr>, leaving you in control to inspect memory before continuing. This is how you debug a program that has gone wrong — including one running on the bare processor.

7. Memory map

The A16 has 65,536 words of memory. AeturnisOS uses it as follows:

* The system image ends a little above 07BF; the figure is approximate and grows as the OS does. The large free span between the compile area (4000, growing up) and the data stack (7000, growing down) is shared working memory — a definition-heavy session and a deep stack eat into the same region.

8. The display (ATDC/1)

The screen is an Aeturnis Text Display Controller, type 1 — a text grid of 40 columns by 20 rows, 800 cells, mapped to memory at 0x8000. The cell for column c, row r is at address 0x8000 + r*40 + c.

Each cell is one word, laid out:

 bit 15 : blink
 bits 14-12 : background colour (0-7)
 bits 11-8  : foreground colour (0-15)
 bits 7-0   : glyph (character code 0-255)

The system's default attribute is green on black (foreground colour 10). To place a character by hand from the monitor, combine the attribute 0A00 with the character code — for example, 0A41 is a green A (code 41 hex):

AOS> POKE 8000 0A41        ( green 'A' in the top-left cell )

Colours are a 16-entry palette; low indices are dim primaries (0 black, 1 blue, 2 green, 4 red, …) and indices 8–15 are their bright variants. Background uses the low 8.

9. The keyboard

Keystrokes arrive in a 16-slot ring at 0x9000; a slot of 0 is empty. The system reads from it for you — you will normally use KEY (§3.5) rather than the ring directly. Two codes are special to line editing: RETURN is 10, BACKSPACE is 8. Input is line-oriented: type, correct with BACKSPACE, and commit with RETURN.

When no key is waiting, a program blocked on KEY (and the command line itself) puts the processor to sleep until a key arrives — the keyboard signals the processor to wake it. The machine is idle, not spinning.

10. Faults and recovery

Some conditions are faults — the processor stops the offending work immediately rather than continue with a wrong result. AeturnisOS catches them and drops you into the monitor with a report, so nothing is silently corrupted:

From either, type FORTH and RETURN to resume normal operation. A fault does not damage the machine; it protects you from a result you cannot trust. If faults recur, note the address reported and inspect that region with DUMP.

11. The ship, and the rest of 0.2 / 0.3

AeturnisOS 0.2 adds the vocabulary for talking to the ship around you, and the few language pieces that support it; 0.3 adds the operator remedy words a crew uses to answer a fault (SHED, DOCK-ON, BACKUP!, THR-ISO/THR-ARM) and the CTRL.PRESS cockpit readout. Everything here is ordinary Forth — you can read it, and you can redefine it.

11.1 Comments and text

• \ … — everything to the end of the line is a comment.
• ( … ) — an inline comment, up to the next ). Both work while defining.
• ." text" — inside a definition, prints text when the word runs: : HELLO ." ALL STATIONS READY" CR ;.

11.2 Naming values and storage

A definition that runs out of dictionary room is a clean error (FULL) that leaves no half-built word behind — your earlier definitions are untouched.

11.3 Time

The clock counts milliseconds on the ship's own timeline (it keeps running while the processor waits). It is 16 bits, so it wraps about every 65 s — always compare differences, never absolute readings.

• TICKS ( -- ms ) — read the clock.
• MS ( ms -- ) — wait that many milliseconds (0 … 32767; a negative value is an error). MS keeps servicing background work and honours a stop while it waits; compose longer waits from several calls.

11.4 Bigger arithmetic & instrument readouts

Scaling a sensor value (28.00 V is stored as 2800) can overflow a single 16-bit multiply. The double-cell words carry a 32-bit intermediate: UM* M* UM/MOD */ */MOD. The rescale idiom is */: 2800 150 100 */ → 4200. Divide-by-zero and results that do not fit are clean errors.

Print scaled values with .1 (one decimal) and .2 (two): 283 .1 → 28.3.

11.5 Talking to devices

The low-level words reach any ABUS device by its window base (DEV# resolves a base, and returns 0 when the device is absent — never D@/D! a base of 0):

Discovery words print the platform inventory to the screen:

11.6 The stock ship vocabulary

Named in human terms and bound to the ship's devices by role at boot:

• Readings — COOLANT.TEMP, COOLANT.FLOW, CABIN.PRESS, CABIN.O2 leave the raw value (use .1 to print). Each has a ? form (COOLANT.TEMP?) that leaves value and quality together, so a stale or faulted reading is never mistaken for a real one. CTRL.PRESS reads the sealable cockpit's pressure — so after you dog the hatch to contain a cabin leak, CABIN.PRESS keeps falling while CTRL.PRESS holds.
• STATUS — the whole-ship dashboard: one line per subsystem with its alarm state.
• PWR · ENV · PROP · DOCK — that subsystem's detail.
• Control — conservative words that write setpoints and report acceptance; you read the telemetry to confirm the ship actually moved. The ship controls:
• n PUMP! primary coolant-pump speed · n SCRUB! scrubber/makeup level
• n SHED load-shed level (0…1000) · DOCK-ON reconnect shore power
• n BACKUP! the standby coolant pump (1000 BACKUP! brings it online)
• THR-ISO / THR-ARM isolate / re-arm the thruster

11.7 Running programs, interrupts, and stopping them

Ordinary Forth runs in the foreground. Short interrupt handlers only latch work (a key, a reset, a controller alarm); the foreground picks it up at defined service points — the keyboard wait, MS, between commands, and the top of a BEGIN … AGAIN loop. A stop (the operator's abort key) is honoured at those points, so you can halt a runaway BEGIN … AGAIN and get the prompt back without losing your definitions.

If a program faults, or you type MON, you drop to the recovery monitor (§6), which runs with interrupts off and its own input — usable even when the fault was in interrupt handling itself. FORTH restores normal operation. A dock reset notifies the running system; a monitor can watch the reset generation and restart its own logic when it changes.

Appendix — word index

Stack effect ( before -- after ), top on the right. * marks words used inside definitions (compile-time).

DUP    ( n -- n n )          DROP  ( n -- )
SWAP   ( a b -- b a )        OVER  ( a b -- a b a )
ROT    ( a b c -- b c a )    NIP   ( a b -- b )
2DUP   ( a b -- a b a b )

+      ( a b -- a+b )        -     ( a b -- a-b )
*      ( a b -- a*b )        /     ( a b -- a/b )      MOD ( a b -- rem )

=      ( a b -- flag )       <     ( a b -- flag )     >   ( a b -- flag )
AND    ( a b -- a&b )        OR    ( a b -- a|b )      XOR ( a b -- a^b )

@      ( addr -- n )         !     ( n addr -- )

.      ( n -- )              CR    ( -- )
EMIT   ( ch -- )             KEY   ( -- ch )

WORDS  ( -- )                HELP  ( -- )
MON    ( -- )                EXIT  ( -- )

:  *   ( "name" -- )         ;  *  ( -- )
IF *  ELSE *  THEN *         BEGIN *  UNTIL *   AGAIN *
LITERAL *                    HERE  ( -- addr )   , * ( n -- )

\ --- 0.2 (§11) ---
VARIABLE ( "name" -- )       CONSTANT ( n "name" -- )
CREATE   ( "name" -- )       ALLOT   ( n -- )
TICKS  ( -- ms )             MS      ( ms -- )
UM*  ( u u -- ud )           M*   ( n n -- d )    UM/MOD ( ud u -- ur uq )
*/   ( n n n -- n )          */MOD ( n n n -- r q )
.1   ( n -- )                .2    ( n -- )
D@ ( base off -- n )         D! ( n base off -- )
DEV.STATUS ( base -- n )     DEV.CTRL! ( val base -- )
DEV.SET ( mask base -- )     DEV.CLR  ( mask base -- )
DEV.RESULT ( base -- code )  V@? ( base -- value quality )
DEVICES ( -- )               DESCRIBE ( class inst -- )  ROLES ( -- )
STATUS ( -- )                PWR/ENV/PROP/DOCK ( -- )
COOLANT.TEMP ( -- n )        COOLANT.TEMP? ( -- n q )   ( …FLOW …PRESS …O2 )
PUMP! ( n -- res )           SCRUB! ( n -- res )

\ --- 0.3 (§11) — ship-operator remedy vocabulary ---
CTRL.PRESS ( -- n )          SHED ( n -- )        DOCK-ON ( -- )
BACKUP! ( n -- )             THR-ISO ( -- )       THR-ARM ( -- )

Revision A16/01 · AeturnisOS 0.3. This manual describes the running system exactly; where they disagree, trust the machine and report the discrepancy.

Aeturnis A16 — Programmer's Quickstart

AETURNIS DEVELOPMENT LABORATORIES · ADL‑A16‑QS · Rev. A16/01 For the programmer writing directly for the processor. Assumes you can already operate the terminal (AeturnisOS Operator's Quickstart). Companion volume: A16 Architecture & Instruction Reference (ADL‑A16‑REF).

AeturnisOS is written in the A16's own language, and so can you be. This takes you from the shape of the machine to a program that runs on the bare processor.

1. The shape of the machine

The A16 is a 16-bit processor. Everything it touches — every register, every memory cell, every value — is a 16-bit word. Memory is addressed by the word, not by the byte: address 0, address 1, address 2 are successive 16-bit cells. There are 65,536 of them.

It has sixteen general registers, R0 through R15, all equal, all 16-bit. A handful carry conventions (below), but the hardware plays no favourites.

Three registers are special and live outside the sixteen:

• PC — the program counter: the address of the next instruction. You never write it directly; the flow-control instructions do.
• SR — the status register: the condition flags (below) plus mode bits.
• IVB — the interrupt vector base: where the table of fault/interrupt handlers lives.

Two of the general registers carry hardware-relevant conventions:

• R14 is the return-stack pointer — CALL, RET, and interrupt entry use it.
• R13 is the data-stack pointer by software convention.

Both stacks grow downward: to push, you pre-decrement; to pop, you post-increment. The addressing modes (below) make that a single instruction.

2. Moving values: load, store, and immediates

The A16 is a load/store machine. Arithmetic happens only in registers; memory is touched only by LOAD and STORE. To get a constant into a register, use LDIMM ("load immediate"):

LDIMM R2, 0x8000      ; R2 <- 0x8000
LDIMM R3, 65          ; R3 <- 65

LOAD reads memory into a register; STORE writes a register to memory. The memory address is given by a base register and a mode:

LOAD  R4, [R2]        ; R4 <- memory[R2]
STORE R3, [R2]        ; memory[R2] <- R3

The four modes are where the A16 earns its keep:

Post-increment and pre-decrement are exactly a stack pop and push:

STORE R3, [--R13]     ; push R3 onto the data stack
LOAD  R4, [R13++]     ; pop the data stack into R4

3. Arithmetic and the flags

Register arithmetic takes two registers; the result replaces the first:

ADD R2, R3            ; R2 <- R2 + R3
SUB R2, R3            ; R2 <- R2 - R3
MUL R2, R3            ; R2 <- R2 * R3  (low 16 bits)

There is a small-constant form for the common cases (the constant is 0–15):

ADDI R2, 1            ; R2 <- R2 + 1
SHL  R2, 4            ; shift R2 left by 4

Every arithmetic instruction also sets the condition flags in SR:

• Z — the result was zero
• N — the result was negative
• C — a carry/borrow occurred
• V — signed overflow

You don't read the flags directly; you branch on them. CMP R2, R3 subtracts without storing the result — it exists only to set the flags for a branch:

CMP R2, R3
BEQ equal             ; branch if R2 == R3 (Z set)

TST R2, R2 sets the flags from a single register (handy for "is it zero?").

4. Control flow

Branches are short, PC-relative, and conditional — this is how you make decisions and loops. Each tests the flags left by the last CMP/TST/arithmetic:

Jumps and calls are longer-range and unconditional. JMP sets PC; CALL saves a return address on R14 and RET pops it:

CALL putc             ; call a subroutine
RET                   ; return to the caller
JMP  loop             ; go to a label

A short, counted loop — count R2 down to zero:

loop:   ADDI R3, 1        ; (do some work)
        SUBI R2, 1        ; R2 = R2 - 1
        TST  R2, R2
        BNE  loop         ; repeat until R2 hits zero

5. Your first program

This writes a character to the screen and stops. The screen is memory at 0x8000 (see the operator reference); a cell is attribute | character, and 0x0A00 is the default green attribute. So 0x0A41 is a green A.

        LDIMM R2, 0x8000      ; R2 = screen address
        LDIMM R3, 0x0A41      ; R3 = green 'A'
        STORE R3, [R2++]      ; write it; advance the cursor
        LDIMM R3, 0x0A31      ; green '1'
        STORE R3, [R2++]
        LDIMM R3, 0x0A36      ; green '6'
        STORE R3, [R2]
        HALT                  ; stop

Assemble it to a memory image and it prints A16 in the top-left corner.

Running it. A program is a block of instruction words in memory. You start it with the monitor's GO <addr> (it sets PC and runs), or — for something this small — you can plant the words by hand with POKE and then GO. When it's larger, you assemble source like the above into an image and load it. Either way, GO hands the processor to your code; HALT, a fault, or a breakpoint hands it back.

6. The idea that makes a language

AeturnisOS is a Forth, and the whole language rests on a two-instruction loop called NEXT. A Forth program is a list of addresses; NEXT reads the next one and jumps to it:

next:   LOAD R1, [R0++]       ; R1 <- next word in the list; advance R0
        JMP  [R1]             ; jump to the code it points at

R0 is the list pointer (the "instruction pointer"); R1 is scratch. Post-increment advances the pointer as it reads; the indirect JMP dispatches. That is the entire inner interpreter — two instructions, because the auto-increment addressing and the indirect jump were designed for exactly this. When you read the AeturnisOS source, this is the heartbeat you'll see everywhere.

Where to go next

You've seen the registers, the load/store model, the flags and branches, calls, and a running program. For the complete instruction set — every opcode and its syntax, all the addressing modes and conditions, interrupts and faults, the assembler's directives, and instruction timing — open the A16 Architecture & Instruction Reference.

Sixteen registers, a handful of instruction shapes, four addressing modes. You can hold the whole processor in your head — which is the point.

Aeturnis A16 — Architecture & Instruction Reference

AETURNIS DEVELOPMENT LABORATORIES · ADL‑A16‑REF · Rev. A16/01 The complete processor: registers, memory, flags, the instruction set, interrupts and faults, assembly language, and timing. New programmers should read the Quickstart first.

1. Machine model

• Word size: 16 bits. Every register and memory cell holds one 16-bit word.
• Memory: word-addressed, 65,536 words. Address n names the n-th 16-bit cell; there is no byte addressing. All address arithmetic wraps within 16 bits.
• General registers: sixteen, R0–R15, all 16-bit and general-purpose. Two carry hardware-relevant conventions:
• R14 = return-stack pointer (RSP). CALL/RET and interrupt entry use it.
• R13 = data-stack pointer (DSP), by software convention.
• Special registers (outside R0–R15):
• PC — program counter. Written only by flow-control instructions and GETPC reads it. Not an instruction operand.
• SR — status register (§2).
• IVB — interrupt vector base (§7).
• Stacks grow downward: push = pre-decrement ([--Rb]), pop = post-increment ([Rb++]).

AeturnisOS register conventions (software, not hardware): R0 is the Forth instruction pointer, R1 its scratch word, R13/R14 the two stacks. When you write code that AeturnisOS will call, preserve what it expects (see the operator reference).

2. Status register and flags

SR holds four condition flags, set by arithmetic and logic, plus two mode bits:

Only ALU and ALUI instructions update the condition flags. Which flags each touches is listed with the instruction. You test flags by branching (§5.5), not by reading them — though GETSR/PUTSR move the whole register to and from a general register.

3. Instruction format

Every instruction is a 16-bit word. An instruction is one or two words: a second word follows only when the operation needs a full 16-bit immediate or offset (LDIMM, an absolute JMP/CALL, or an offset LOAD/STORE).

The top four bits (bits 15–12) select the class:

4. Addressing modes (LOAD / STORE)

The low four bits of a LOAD/STORE select the mode; the base is a register Rb:

Arithmetic instructions never address memory — only LOAD/STORE do. (If a program both loads into and advances the same base register in one instruction, the loaded value wins; the increment is discarded. Write what you mean.)

5. The instruction set

5.1 Memory — LOAD, STORE, LDIMM

LOAD  Rd, <mem>        ; Rd  <- memory[addr]      (modes §4)
STORE Rs, <mem>        ; memory[addr] <- Rs
LDIMM Rd, value        ; Rd  <- value             (16-bit; two words)

None of these change the flags.

5.2 Register arithmetic & logic — ALU (OP Rd, Rs)

Rd ← Rd OP Rs, with the flags shown. (NOT, NEG, MOV write Rd from Rs; CMP and TST set flags only and write no register.)

DIV/MOD by zero raise a divide-by-zero fault (§7). For a full 32-bit product use MUL then MULH. (Unsigned and double-width variants are reserved for a later revision.)

5.3 Small-immediate & shifts — ALUI (OP Rd, imm)

The immediate is 0–15. Rd ← Rd OP imm. Flags as noted.

For constants larger than 15, use LDIMM into a register and an ALU op.

5.4 Jumps, calls, returns — CTRL

None change the flags.

5.5 Conditional branches — BRANCH

Bcc target tests the flags and, if the condition holds, continues at target. Branches are PC-relative and short: the target must be within −128 … +127 words of the branch. For longer or unconditional range, use JMP.

Signed comparisons (BGE/BLT/BGT/BLE) and unsigned ones (BHS/BLO/BHI/BLS) are both provided — pick the pair that matches how you're treating the values.

5.6 System operations — SYSTEM

6. Stacks, push, pop, call

There are no dedicated push/pop opcodes — they are addressing-mode idioms, which is the whole reason the modes exist:

STORE Rs, [--R13]      ; push Rs onto the data stack
LOAD  Rd, [R13++]      ; pop into Rd
STORE Rs, [--R14]      ; push onto the return stack
LOAD  Rd, [R14++]      ; pop from the return stack

CALL pushes its return address onto R14; RET pops it. Interrupt and fault entry also build their frames on R14 (§7). Keep R14 pointing at usable stack space at all times — a fault can occur at any instruction boundary and will try to use it.

7. Interrupts and faults

Two kinds of event divert the processor, through one mechanism:

• External interrupts are asynchronous (a device wants attention). They are taken only when enabled (I set), at an instruction boundary.
• Faults are synchronous (something went wrong in an instruction). They cannot be masked.

Entry. The processor pushes the saved PC and SR onto R14, clears I, and jumps to the handler address taken from the vector table at IVB. IRET reverses this in one step.

• A fault saves the address of the faulting instruction, so a handler that fixes the cause can IRET to retry it.
• An interrupt (and TRAP) saves the address of the next instruction, so IRET resumes cleanly.

Vector table — 64 words at IVB:

WAIT and idle. WAIT suspends the processor until a device request is pending — burning no cycles. It is the right way to wait for input: AeturnisOS's KEY is built on it. A request that is already pending when WAIT runs returns immediately, so there is no race. (If interrupts are enabled, waking takes the interrupt; if not, the processor simply resumes.)

If entry itself cannot proceed (a bad R14, or an unreadable vector), the processor enters a deterministic lockup that only reset clears — an honest stop rather than a runaway.

8. Reset state

On reset:

• PC ← 0 — execution begins at address 0.
• SR — supervisor set, interrupts disabled, flags clear.
• IVB ← 0 — boot code installs the vector table and sets IVB before enabling interrupts.
• R0–R15 ← 0. Boot code sets up the stacks (R13/R14) before using them.

What is executable at address 0 is the platform's responsibility (a boot ROM).

9. Timing

The A16/01 runs at about 8 MHz with fixed, predictable timing — no caches or pipeline surprises. Cycle counts:

So NEXT — LOAD R1,[R0++] then JMP [R1] — costs 2 + 2 = 4 cycles.

10. Assembly language

The A16 assembler reads one statement per line. Case is ignored throughout.

Registers. R0–R15; DSP and RSP are accepted as names for R13 and R14. PC is not an operand.

Operands.

• a register: R5
• a memory reference: [Rb], [Rb++], [--Rb], [Rb + expr]
• a value or label: 0x1234, 42, 'A', or a name

Numbers. Hexadecimal 0x1A, decimal 26, or a character 'A' (its code). A leading - makes a value negative.

Labels. name: defines a label (its address); use the bare name anywhere a value is expected. Forward references are fine.

Directives.

Branch range. A Bcc target must be within −128…+127 words; the assembler computes the offset and rejects anything farther — use JMP for long range.

A representative fragment — clear the 800-cell screen:

SCREEN  equ 0x8000
COUNT   equ 800
        LDIMM R2, SCREEN       ; cursor
        LDIMM R4, COUNT        ; cells remaining
        LDIMM R3, 0            ; the blank cell value
loop:   STORE R3, [R2++]       ; clear a cell, advance
        SUBI  R4, 1            ; one fewer to go
        TST   R4, R4
        BNE   loop             ; repeat until R4 hits zero
        RET

Appendix — instruction summary

Memory   LOAD Rd,<m>   STORE Rs,<m>   LDIMM Rd,n
         modes:  [Rb]  [Rb++]  [--Rb]  [Rb+n]

ALU      ADD ADC SUB SBC AND OR XOR NOT NEG MOV CMP TST MUL MULH DIV MOD   (Rd, Rs)
ALUI     ADDI SUBI CMPI SHL SHR ASR ROL ROR ANDI ORI XORI                 (Rd, imm0-15)

Flow     JMP Rb | [Rb] | addr        CALL Rb | [Rb] | addr        RET
Branch   BRA BEQ BNE BHS BLO BHI BLS BGE BLT BGT BLE BMI BPL BVS BVC       (target, +-127)

System   NOP HALT WAIT EI DI IRET  TRAP n  BRK
         GETSR/PUTSR  GETIVB/PUTIVB  GETPC   (Rd/Rs)

Revision A16/01. Eight instruction classes, sixteen registers, four addressing modes. Classes 8–F are deliberately empty — the machine will earn its complexity, not be born with it.

0•X prototype — the diagnostic loop (tester walkthrough)

This is a prototype. Systems, layout, and behaviour will change.

The prototype proves one claim: the scenario system is artificial, the failure is not. SIMCTRL injects a real component condition (a failed pump, a lost umbilical, a stuck thruster, a leaking cabin) — the physics then does the rest, exactly as it would for a genuine fault. Every scenario is solvable two genuinely different ways: one from the terminal (an operator command word) and one from a physical control (a breaker, a switch, a hatch). Nothing is scripted — the solutions emerge from the simulation.

Getting in

1. Dismiss the disclaimer (click / Enter / Space). You arrive in a cold ship: standby lighting, the terminal dark.
2. Press the console boot button (amber). The A16 runs POST live on the CRT (~3 s) and the lights come up. When BOOT OK appears the ship's SIM diagnostic vocabulary auto-loads (a brief flurry of definitions) — you don't type it by hand.
3. Click the CRT to lock in to the terminal (a small reticle + left-click). Tab stands you back up; Esc is the AOS stop key while seated (and the pause menu while piloting).

Move: WASD + mouse-look while piloting. There is no walk-through collision yet — you can pass through walls/doors/hatches to reach any control.

The terminal, in 60 seconds

Diagnose (three depths — pick whichever you need):

Drive the harness:

Operator remedy words (the real ship controls):

Physical controls: the ENG board (engine-room, starboard wall) carries the breakers (BATT, TERM, AVIO) and — below them — the BKP PUMP and THR ISO switches. The HAB↔CTRL hatch is operated by the green wall panel beside it. The dock-reset console is in the airlock (LOCK).

The four scenarios

1 — DOCKING-POWER (1 SIM-START)

• What happens: the dock umbilical loses power; shore stops reaching the bus.
• Symptom: with the battery breaker open (the docked default, floating on shore), the BUS-VOLTS gauge collapses and PWR raises an undervolt alarm.
• Diagnose: PWR (undervolt), the BUS-VOLTS gauge in ENG.
• Fix A — terminal: DOCK-ON — re-establish shore power. BUS volts recover.
• Fix B — physical: close the BATT breaker on the ENG board — the battery now holds the bus. (1000 SHED also buys time by dropping load, but doesn't restore the source.)

2 — COOLANT-PUMP (2 SIM-START)

• What happens: the primary coolant pump fails (flow → 0).
• Symptom: the COOLANT-TEMP gauge climbs steadily; ENV raises a coolant caution (then warning). COOLANT.FLOW reads ~0.
• Diagnose: ENV, COOLANT.TEMP, COOLANT.FLOW.
• Fix A — terminal: 1000 BACKUP! — bring the standby pump online. Flow returns, temperature falls — with the primary still failed (containment, not repair).
• Fix B — physical: the BKP PUMP switch on the ENG board (same effect, same command path).

3 — STUCK-THRUSTER (3 SIM-START)

• What happens: the main thruster sticks at ~40 % output regardless of command.
• Symptom: PROP raises caution + warning; the thruster's feedback diverges from the command (it fires while commanded idle), and its STATUS STUCK bit sets. This one is fast (seconds).
• Diagnose: PROP.
• Fix A — terminal: THR-ISO — isolate the thruster (closes the propellant valve; output → 0 with precedence over the stuck fault). THR-ARM re-arms it.
• Fix B — physical: the THR ISO switch on the ENG board.

4 — PRESSURE-LEAK (4 SIM-START)

• What happens: a slow leak opens in the habitable cabin (HAB).
• Symptom: the CABIN-PRESS gauge declines gradually — a trend-watcher notices before any alarm; ENV eventually raises a pressure caution (<95 kPa).
• Diagnose: ENV, CABIN.PRESS (watch the trend).
• Fix A — terminal: 1000 SCRUB! — raise makeup. Delivery is finite, so this buys time (slows the decline) rather than erasing it.
• Fix B — physical: close the HAB↔CTRL hatch (its green wall panel). This contains the leak — CTRL stays habitable; HAB keeps venting. Watch the two cockpit pressure gauges: CABIN (HAB) keeps falling while COCKPIT (CTRL) holds — or read CTRL.PRESS vs CABIN.PRESS at the terminal. The cabin gauge still reads HAB (correctly). Containment, not repair.

Recovering — the dock-reset console (airlock)

Three grades, mild → severe:

All three run independently of the A16 (a dead terminal can't block recovery), bump the reset generation, and wake a running OS to re-bind. SIM-START after a reset waits for the generation change, so a reset always wins over a stale command.

A suggested first run: boot → SIM-LIST → 2 SIM-START → watch COOLANT-TEMP climb → ENV → 1000 BACKUP! (temp falls) → walk to the airlock → RESTORE.

Castellan CP-28/50 — Main Storage Battery

CASTELLAN POWER · Vendor 0x0C40 · Distributed/certified by the Central Authority over ANET. A 28-volt lithium storage pack for small craft — the house battery that carries the bus when shore power is absent.

The CP-28/50 is a seven-cell-series lithium pack sized for a utility craft's standing loads. It presents a nominal 28 V, floats on the ship bus through a panel breaker, and reports its state of charge to the power controller. Terminal voltage sags under load by its internal resistance — expected behaviour, not a fault.

Specifications

Open-circuit voltage falls approximately linearly from 29.4 V (full) to 21.0 V (empty). Under a load current I, terminal voltage is V_oc(SoC) − I · 0.05 Ω.

Installation & service

Mounts in a standard power bay; feeds the ship bus through a Castellan panel breaker (see CP-B30). State of charge is coulomb-counted and published on the power controller's BATT_SOC telemetry. The pack is a field-replaceable unit — swap at end of service life; the house bus rides through on shore power while it is out.

Revision history

See components-changelog.md.

Castellan CP-28/20C — Shore Converter / Charger

CASTELLAN POWER · Vendor 0x0C40 · Distributed/certified by the Central Authority over ANET. Converts dock shore power to the ship's regulated 28 V bus and floats/charges the main battery.

When the craft is docked and the umbilical is mated and powered, the CP-28/20C holds the ship bus at its float voltage and supplies both the running loads and the battery charge current, up to its output limit. With shore present it is the preferred source; the battery floats beneath it. Remove shore power and the bus falls back to the battery.

Specifications

Installation & service

Sits between the dock umbilical (through the dock breaker) and the ship bus — one-way, no backfeed into the dock. Field-replaceable. Loss of the converter while docked drops the ship to battery (the docking-power fault); the battery then drains at the load rate.

Revision history

See components-changelog.md.

Castellan CP-28 — Main DC Bus Node

CASTELLAN POWER · Vendor 0x0C40 · Distributed/certified by the Central Authority over ANET. The ship's main 28 V distribution node, with integrated bus telemetry on ABUS.

The CP-28 is the common tie point for the battery, the shore converter, and the ship's loads. It presents a coherent telemetry block — bus voltage, total load current, which sources are contributing, and battery state of charge — so the power controller and the operator read the whole electrical picture as one consistent sample. It flags undervoltage (a sagging bus) and overload (demand beyond capacity).

Specifications

Telemetry

Publishes VOLTAGE, LOAD, SOURCE (battery / shore bits), and BATT_SOC under a sequence-counter coherent block; STATUS carries UNDERVOLT and OVERLOAD.

Revision history

See components-changelog.md.

Castellan CP-B30 — Panel Breaker

CASTELLAN POWER · Vendor 0x0C40 · Distributed/certified by the Central Authority over ANET. A protective circuit breaker for the ship's power feeders (battery, dock, main loads).

The CP-B30 is a resettable overcurrent breaker. It is commanded closed through its ABUS control register, and it reports whether it is actually conducting. On overcurrent it trips open and latches — holding the close command will not defeat the protection. Clear the fault, then issue a reset to reclose.

Specifications

Behaviour

• Close — set CONTROL.ENABLE; the breaker conducts if not tripped.
• Trip — current above 30 A latches the breaker open; STATUS.TRIPPED sets and feedback reads open.
• Reset — CONTROL.RESET clears the latch; the breaker recloses only if commanded closed and the overcurrent is gone.

Installation & service

One breaker per feeder; field-replaceable. The battery breaker and the dock breaker are the same part.

Revision history

See components-changelog.md.

Halden HF-CP20 — Coolant Circulation Pump

HALDEN FLUIDICS · Vendor 0x0B20 · Distributed/certified by the Central Authority over ANET. A variable-speed coolant pump for a small-craft thermal loop.

The HF-CP20 circulates coolant through the equipment loop and the radiator. It is commanded as a speed fraction and reports its shaft speed, delivered flow, and electrical current. Flow scales with commanded speed and pump condition; lose flow and the cooled equipment heats up — the pump is the thermal loop's prime mover.

Specifications

Behaviour

CMD sets the speed fraction (0…1000 = 0…100 %). Delivered flow = CMD · 20 L/min · condition. STATUS reports JAMMED and DRY. An unpowered, disabled, jammed, or failed pump delivers no flow.

Installation & service

Inline in the coolant loop; drawing power from the ship bus through its breaker. Field-replaceable; a redundant pump (where fitted) can carry the loop while this one is out. The prototype SV-1 fits two — a primary (controller-modulated) and a standby backup that starts off and is brought online by an operator changeover; total delivered flow is the sum, so the backup alone can carry the loop.

Revision history

See components-changelog.md.

Halden HF-RAD12 — Radiator Panel

HALDEN FLUIDICS · Vendor 0x0B20 · Distributed/certified by the Central Authority over ANET. The thermal loop's heat-rejection panel — radiates waste heat to space.

In vacuum there is no convection or conduction to carry heat away; the only sink is radiation. The HF-RAD12 is a coated panel through which coolant passes, rejecting heat to space as ε·σ·A·T⁴. Its capacity rises steeply with temperature but is ultimately bounded by its area and emissivity — size the heat load to the panel, or the loop runs hot.

Specifications

At the loop's full-flow equilibrium the panel rejects the equipment's steady heat load; at ~1.2 m² and 0.85 emissivity that holds the coolant near 32 °C for a ~500 W load.

Installation & service

Hull-mounted, plumbed into the coolant return. Passive — no power, no commands. Field-replaceable; a fouled or holed panel loses rejection capacity and the loop warms.

Revision history

See components-changelog.md.

Halden HF-SCR4 — CO₂ Scrubber

HALDEN FLUIDICS · Vendor 0x0B20 · Distributed/certified by the Central Authority over ANET. A regenerative CO₂ scrubber for a small crew's cabin atmosphere.

Crew metabolism steadily consumes O₂ and adds CO₂ to the cabin air. The HF-SCR4 removes CO₂ at a commanded rate; makeup gas then restores the partial pressures the crew consumed. Run it fast enough to outpace the occupants and cabin CO₂ stays low; fall behind and CO₂ climbs toward the caution band.

Specifications

At full command the HF-SCR4 removes 1.5 mmol/s of CO₂ — comfortably ahead of roughly four occupants' production (~0.26 mmol/s each).

Behaviour

CMD sets the removal fraction (0…1000 = 0…100 %). CO₂ removed = CMD · 1.5 mmol/s. The life-support controller normally modulates it against the measured cabin CO₂ partial pressure.

Installation & service

Draws cabin air; drawing power from the ship bus. Field-replaceable; a saturated or failed bed lets CO₂ rise even with the unit commanded on.

Revision history

See components-changelog.md.

Kestrel KP-RCS100 — RCS Thruster

KESTREL PROPULSION · Vendor 0x0E80 · Distributed/certified by the Central Authority over ANET. A 100-newton reaction-control thruster for small-craft maneuvering.

The KP-RCS100 is commanded as a thrust fraction and reports the thrust it actually achieves, ramping to command over a short spin-up. Because feedback is the modeled physical result — not an echo of the command — a thruster that fails off, degrades, or sticks at a value is diagnosable from the cockpit by comparing command against feedback. No EVA required.

Specifications

Behaviour

CMD sets the thrust fraction (0…1000 = 0…100 % of 100 N); FEEDBACK is the achieved fraction. Fault conditions — failed-off (no thrust), stuck-at (STATUS.STUCK; feedback frozen, ignores command), and degraded (tracks command but falls short) — all show in the command-vs-feedback relationship.

Installation & service

Hull-mounted on its thrust axis; drawing power and propellant from the ship. Field-replaceable; thrust can be reallocated to other thrusters while one is isolated.

Revision history

See components-changelog.md.

Aeturnis ACP-PWR — Power Controller

AETURNIS DEVELOPMENT LABORATORIES · Vendor 0x0AD1 · Distributed/certified by the Central Authority. The power subsystem's local controller — aggregates the electrical picture, raises alarms, and sheds load to protect the bus.

The ACP-PWR reads the bus voltage, battery state of charge, load current, and active sources, and presents them as one coherent telemetry sample. It raises undervoltage, low-charge, and overload alarms (with deadbands so they cannot chatter) and, on overload, sheds non-essential load — a protective action that overrides the main computer.

Specifications

Alarm thresholds (undervoltage, SoC, overload) are tunable firmware configuration (see ship-systems-sim.md §4), not fixed hardware limits. Defaults: undervoltage caution < 24 V / warning < 20 V; SoC caution < 30 % / warning < 10 %.

Revision history

See components-changelog.md.

Aeturnis ACP-ENV — Life-Support & Thermal Controller

AETURNIS DEVELOPMENT LABORATORIES · Vendor 0x0AD1 · Distributed/certified by the Central Authority. The life-support and thermal controller — owns the scrubber and coolant pump, aggregates cabin and coolant state, and keeps the crew's environment safe.

The ACP-ENV reads cabin pressure and temperature, O₂, and coolant temperature, and presents them as one coherent sample. On a craft with a separately-sealable cockpit, it also reports that volume's pressure, so an isolated section can be watched holding while the cabin vents. It modulates the CO₂ scrubber and the primary coolant pump on the crew's behalf (a standby backup pump, where fitted, is a separate operator- commanded unit). A coolant over-temp is a local protective action: the controller forces the pump to full regardless of the main computer's command until the loop recovers.

Specifications

Alarm thresholds are tunable firmware configuration (§4). Defaults: cabin pressure caution < 95 kPa / warning < 80 kPa; coolant temp caution > 60 °C / warning > 80 °C.

Revision history

See components-changelog.md.

Aeturnis ACP-PROP — Propulsion Controller

AETURNIS DEVELOPMENT LABORATORIES · Vendor 0x0AD1 · Distributed/certified by the Central Authority. The propulsion controller — commands the thrusters and watches command-vs-feedback for faults.

The ACP-PROP forwards thrust commands to the thruster and aggregates achieved thrust and fault state. It raises a mismatch alarm when feedback diverges from command, and flags a stuck or failed thruster — the cues that let the crew diagnose and reallocate thrust from inside.

Specifications

Mismatch thresholds are tunable firmware configuration (§4). Defaults: caution > 5 % / warning > 15 %.

Revision history

See components-changelog.md.

Aeturnis ACP-DOCK — Berth Controller

AETURNIS DEVELOPMENT LABORATORIES · Vendor 0x0AD1 · Distributed/certified by the Central Authority. The berth controller — tracks the umbilical and shore supply, and alarms on a lost or weak connection.

The ACP-DOCK aggregates the umbilical state (mated / power / data) and shore voltage, and handles connect/disconnect requests. It alarms when the umbilical is unmated or shore voltage sags — the first sign of a docking-power problem.

Specifications

Alarm thresholds are tunable firmware configuration (§4). Default: shore undervoltage < 20 V.

Revision history

See components-changelog.md.

Aeturnis A16 — Revision History

AETURNIS DEVELOPMENT LABORATORIES · Processor Standards Distributed and certified by the Central Authority over ANET. Heritage: the A16 descends from the Earth-era DCPU-16 — the austere 16-bit, word-addressed machine of the evacuation ships. Twelve centuries of documentation, rebuilding, and refinement separate the two; the A16 is the modern consolidation of that lineage.

This history records revisions to the processor standard itself — the instruction set and the silicon revisions that implement it. It does not record a vessel's individual maintenance (that lives in the ship's own log). Entries are newest first.

A16/01 — ISA v1 · AW 1195

The first Aeturnis-standardized processor. A deliberately small, fully-comprehensible machine, specified so that one person can hold the whole of it in their head and a modest industrial base can re-manufacture it from documentation alone.

• 16-bit word size; word-addressed; 64K-word address space.
• Sixteen general registers; separate program counter, status register, and interrupt vector base.
• Status flags and conditional branches (replacing the ancestor's skip-and-execute conditionals).
• Two hardware stacks with auto-increment / auto-decrement addressing.
• Vectored interrupts and restartable faults; WAIT (sleep until a device signals) and HALT.
• A software breakpoint (BRK) for the machine monitor.
• Instruction classes 0x8–0xF held reserved — the machine is to earn its complexity, not be born with it. Extended arithmetic, memory expansion, and coprocessor interfaces are allocated here for future silicon revisions.

Certified for shipboard use. This is the processor in the terminal in front of you.

Forthcoming

• A16/02 (planned) — a silicon revision for larger physical memory (banking) and bulk transfer, built against the reserved instruction space. Backward-compatible: A16/01 software continues to run unchanged. No pilot is ever required to replace a working A16/01 to keep operating — see the Central Authority's standing compatibility guarantee.

A16/01 remains fully supported. Hardware revisions are physical: a processor upgrade is an installed part, not a download. Your existing machine is not made obsolete by a newer one.

AeturnisOS — Release History

AETURNIS DEVELOPMENT LABORATORIES · AeturnisOS Distributed and certified by the Central Authority over ANET. Heritage: AeturnisOS continues the shipboard Forth-and-monitor tradition of the Earth-era DCPU-16, rebuilt and consolidated for the A16. The command line is the language.

Official AeturnisOS releases are obtained over ANET from the Central Authority and installed on a ship's computer. You are never required to update to keep operating — an older release remains fully functional for its era's work; a newer one adds capability. Entries are newest first.

AOS 0.3 — AW 1199

The operations release: the vocabulary a crew uses to answer a fault, not just read it.

• Operator remedy words — the real ship controls: SHED ( n -- ) (load-shed level), DOCK-ON (reconnect shore power), BACKUP! ( n -- ) (bring the standby coolant pump online), and THR-ISO / THR-ARM (isolate / re-arm the thruster). Each writes through the controllers' command authority and reports acceptance — you read the telemetry to confirm the ship moved.
• CTRL.PRESS — a cockpit-pressure reading, so a cabin leak you contain by dogging the hatch is observable: CABIN.PRESS keeps falling while CTRL.PRESS holds.

An older release keeps working; this one adds the operator controls above. No A16 change.

AOS 0.2 — AW 1198

The device release: AeturnisOS learns to speak to the ship around it.

• ABUS device vocabulary — discover and operate the ship's hardware from the terminal: DEVICES, DESCRIBE, the low-level register words (D@, D!, DEV.STATUS, DEV.CTRL!, DEV.SET/DEV.CLR, DEV.RESULT), and a quality-aware read (V@?) that never mistakes a stale or faulted reading for a real value.
• Stock ship vocabulary — the hardware named in human terms, bound to devices by role: dotted accessors (COOLANT.TEMP, COOLANT.FLOW, CABIN.PRESS, CABIN.O2, each with a quality-aware ? form), the whole-ship dashboard STATUS, per-subsystem detail (PWR, ENV, PROP, DOCK), and conservative control words that write setpoints to the controllers and report acceptance (PUMP!, SCRUB!).
• Named storage and data — VARIABLE, CONSTANT, CREATE, ALLOT.
• Text & comments — string literals (." …") for messages, and \ / ( … ) comments so documented examples run as written.
• Time — a monotonic millisecond clock on the ship's own timeline: TICKS (read) and MS (wait).
• BEGIN … AGAIN loops (interruptible) and fixed-point value printing (.1 / .2) for instrument readouts; widened arithmetic (UM*, M*, UM/MOD, */, */MOD) so scaled values rescale correctly.
• Interrupt/foreground execution model — short interrupt handlers latch work; all ordinary Forth runs in the foreground at defined service points, with a cooperative abort to stop a runaway program without losing your definitions. A fault drops to the monitor's recovery floor (its own polled input), and FORTH restores a known-good configuration.
• Reset awareness — the dock console's resets notify the running system; monitors can observe the reset generation and restart their own logic. (The dock console that drives resets arrives with the scenarios.)
• Error messages that teach — what was expected, and an example.

AOS 0.1 — AW 1196

The first AeturnisOS release: a complete, self-contained Forth environment on the A16.

• Forth REPL and compiler — define your own words (: SQUARE DUP * ;) and they become part of the machine; IF/ELSE/THEN, BEGIN/UNTIL, WORDS, HELP.
• Machine monitor — the recovery floor beneath the language: DUMP, PEEK, POKE, GO, and real breakpoints (BRK → the debugger); reached with MON, left with FORTH.
• Interrupt-driven console — the keyboard sleeps the processor rather than spinning; a divide-by-zero or other fault drops safely into the monitor instead of corrupting.
• ATDC/1 display — 40×20 text on the standard Aeturnis text controller.

AeturnisOS is one evolving system, not a family of forks. You are free to write your own environment on the A16; anything official from Aeturnis reaches your ship only through the Central Authority.

ABUS — Revision History

AETURNIS DEVELOPMENT LABORATORIES · ABUS, the Aeturnis Bus Distributed and certified by the Central Authority over ANET. Heritage: ABUS formalizes the Earth-era DCPU-16 convention of memory-mapped devices and a discoverable device directory into a proper, enumerable bus standard for the A16.

ABUS is how the A16 discovers and talks to the ship's hardware — sensors, actuators, controllers, and displays. This history records revisions to the bus standard; a specific device's firmware history lives with the device. Entries are newest first.

ABUS v1 — AW 1197 · in standardization

The first standardized Aeturnis device bus.

• Memory-mapped device windows — each device presents a block of registers the A16 reads and writes directly; no special instructions required.
• A discoverable directory — every device advertises its class, vendor, model, revision, capability flags, window location, and interrupt line, so software finds hardware by what it is, not by a hard-wired address.
• A standard device header — a common status/control word pair on every device, so one driver convention fits all of them.
• Interrupts — devices signal events (alarms, completions) on the A16's device vectors; the handler acknowledges and clears them.
• Fixed-point telemetry — physical quantities (pressure, temperature, flow, voltage, current, …) in a defined signed fixed-point encoding, consistent across the bus.

Supersedes the earlier ad-hoc device directory. Being standardized now; rolls out with AOS 0.2.

Forthcoming

• Bulk / streaming transport for storage and network devices, and controller-to-controller links for distributed ship control — allocated for a later revision, backward-compatible with v1 devices.

A device built to ABUS v1 declares the revision it needs; a computer can tell you plainly when a part requires a newer bus or OS than it has, rather than failing silently.

Ship Components — Revision History

Distributed and certified by the Central Authority over ANET. Each entry records a component's hardware/firmware revision; a component's full specification lives in its datasheet under components/. Entries are newest first.

A ship is assembled from parts, each a real product from an in-world manufacturer, speaking ABUS. This history records revisions to those parts; it complements the bus standard's own history (abus-changelog.md).

Controllers — Aeturnis Development Laboratories (vendor 0x0AD1) · AW 1205 · initial certification

The subsystem controllers — host-resident Aeturnis logic that aggregates each subsystem, raises alarms with deadbands, and runs the local safety loop (control is local).

• ACP-PWR power controller (model 1 rev 1) — datasheet
• ACP-ENV life-support controller (model 2 rev 1) — datasheet
• ACP-PROP propulsion controller (model 3 rev 1) — datasheet
• ACP-DOCK berth controller (model 4 rev 1) — datasheet

Designed against the latest A16 / AeturnisOS / ABUS specifications at time of certification.

Propulsion — Kestrel Propulsion (vendor 0x0E80) · AW 1205 · initial certification

First certification of the Kestrel reaction-control line against ABUS v1.

• KP-RCS100 RCS thruster (model 0x0301 rev 1) — 100 N, 0.2 s spin-up, command-vs-feedback diagnosable. datasheet

Designed against the latest A16 / AeturnisOS / ABUS specifications at time of certification.

Thermal — Halden Fluidics (vendor 0x0B20) · AW 1204 · initial certification

First certification of the Halden small-craft thermal line against ABUS v1.

• HF-CP20 coolant pump (model 0x0201 rev 1) — 20 L/min, 3000 rpm, 200 W variable-speed. datasheet
• HF-RAD12 radiator panel (model 0x0202 rev 1) — 1.2 m², 0.85 emissivity, passive radiative rejection. datasheet
• HF-SCR4 CO₂ scrubber (model 0x0203 rev 1) — 1.5 mmol/s CO₂ removal, 60 W (life support). datasheet

Designed against the latest A16 / AeturnisOS / ABUS specifications at time of certification.

Power — Castellan Power (vendor 0x0C40) · AW 1203 · initial certification

First certification of the Castellan 28 V power line for small craft, against ABUS v1.

• CP-28/50 main battery (model 0x0101 rev 1) — 50 Ah, 29.4 V full / 21.0 V empty, 0.05 Ω internal. datasheet
• CP-28/20C shore converter (model 0x0102 rev 1) — 28.4 V float, 20 A limit, 90 % efficient. datasheet
• CP-B30 panel breaker (model 0x0103 rev 1) — 30 A latching overcurrent trip, reset to reclose. datasheet
• CP-28 main bus (model 0x0104 rev 1) — 28 V nominal, 40 A capacity, coherent bus telemetry. datasheet

Designed against the latest A16 / AeturnisOS / ABUS specifications at time of certification.