One npm install gives you four commands:

npm install -g asm80-cli

After that, you have asm80, asm80-link, asm80-ar, and asm80-run in your PATH. They share the same assembler core as the browser IDE — same syntax, same directives, same output. No surprises. The code that turns your mnemonics into bytes is literally the same JavaScript module, just invoked from Node instead of a <script> tag.

asm80

The assembler. Give it a source file and it produces Intel HEX (or Motorola S-Record for 6800/6809). The CPU is detected from the file extension — .z80 for Z80, .a80 for 8080, .a65 for 6502, and so on — so there's no flag for that. You just write:

asm80 hello.z80

and get hello.hex. If you want a relocatable object module instead (for linking later), pass --module:

asm80 --module mylib.a80

This produces mylib.obj80. Note the extension: it's .obj plus a CPU suffix, i.e. .objz80, .obj80, .obj65, .obj09. The linker needs to know what it's linking. Add --no-lst if you don't care about the listing file. The listing is mostly useful for debugging — it shows you the generated bytes next to each source line, so you can spot when a relative jump is out of range or an operand got encoded differently than you expected.

asm80-link

The linker takes a YAML recipe with a .lnk extension in the same format the ASM80 IDE uses and produces a single .hex file from multiple object modules. A typical .lnk looks like this:

segments:
  CSEG: '0x0000'
  DSEG: '0x8000'
vars:
  BIOS_PRINT: '0x5'
modules:
  - crt0.objz80
  - main.objz80
library:
  - z80-runtime.objz80
entrypoint: __start

The segments: section tells the linker where to place code and data. CSEG is the code segment, DSEG is for initialized data, the addresses are absolute, so you're laying out your binary exactly as it will sit in memory. If your ROM starts at 0x0000 and your RAM at 0x8000, those are the numbers you put here.

The vars: section injects symbols at link time, which is handy for BIOS entry points or hardware addresses you don't want hardcoded in your source. Your assembly code can reference BIOS_PRINT with an EXTERN directive, and the linker fills in the actual value. No magic numbers scattered across files.

Modules listed under library: only contribute code that's actually referenced, same as a static library in a C toolchain. If your runtime library defines 30 routines and your program calls two of them, only those two end up in the final hex. Modules listed under modules:, on the other hand, are always included in full — that's where your main code and startup routines go.

The entrypoint: field names the symbol where execution begins. The linker makes sure this address ends up as the first thing in the output, so the CPU starts running the right code after reset.

asm80-link project.lnk

asm80-ar

If you're building a library from several object modules, asm80-ar packages them together using a .lbr recipe:

name: mylib
version: 0.1.0
modules:
  - mathops.obj80
  - stringutils.obj80

The output extension depends on the CPU: .lib80 for 8080, .libz80 for Z80, .lib65 for 6502, .lib09 for 6809 etc. This mirrors the .obj convention, everything is tagged with what CPU it belongs to, so you can't accidentally link Z80 code into a 6502 project. (You'd be amazed how often that comes up.)

asm80-ar mylib.lbr

The result is a single file you can reference in any .lnk recipe under the library: key. Build the library once, use it in every project that needs it.

asm80-run

It's a command-line emulator. Hand it a source file or a .hex and it assembles (if needed), loads, and runs:

asm80-run hello.z80

Serial output goes to stdout, so you can pipe it, diff it, test it. The -T flag sets a tick limit, which is useful for automated tests where you don't want a runaway loop eating your CI minutes:

asm80-run -T 100000 hello.z80

For hardware configuration (memory layout, serial port addresses, peripherals) it reads .emu files, the same format the IDE uses. If you've already set up your project in the browser, the same config works here. Here's what a real .emu file looks like - this one comes from the IC80 test suite:

cpu: z80
memory:
  rom:
    from: '0x0000'
    to: '0x7FFF'
  ram:
    from: '0x8000'
    to: '0xFFFF'
serial:
  type: 6850
  mapped: port
  control: '0xDE'
  data: '0xDF'

The cpu: field tells the emulator which CPU to spin up: z80, 8080, 6502, 6809, ... Everything else follows from that choice: the instruction decoder, the register set, the interrupt model.

The memory: block defines the address space layout. rom: marks the region that gets loaded from the hex file and is read-only at runtime. Writes to ROM addresses are silently ignored, just like on real hardware. ram: marks the read-write region. In this config, the lower 32K is ROM and the upper 32K is RAM, which is a classic split for small Z80 systems. The emulator doesn't care about gaps, if you only define ROM from 0x0000 to 0x3FFF and RAM from 0xC000 to 0xFFFF, everything in between is unmapped and reads back as 0xFF.

The serial: section is where it gets useful for testing. type: 6850 tells the emulator to simulate a Motorola 6850 ACIA, the most common serial chip in homebrew 8-bit designs. The mapped: port field means the ACIA is accessed through I/O port instructions (IN/OUT on Z80) rather than memory-mapped I/O. The control: and data: fields give the port addresses: 0xDE for the status/control register and 0xDF for the data register. When your code writes a byte to port 0xDF, it shows up on stdout. When it reads the status register at 0xDE, the emulator reports whether there's input waiting. This is exactly how real 6850 hardware works — the emulator just replaces the physical UART with a pipe to your terminal.

So when asm80-run executes your program and the code sends characters out through the emulated 6850, those characters land in your shell. That's what makes it possible to write tests that check actual program output: assemble, link, run, capture stdout, compare.

All four in action: testing a C compiler

Here's where it gets concrete. IC80 is a C compiler I'm working on that targets 8-bit CPUs. Its test suite (run-test.ps1) exercises the entire pipeline with all four tools:

1. IC80 compiles a .c file to Z80 assembly

2. asm80 assembles the .z80 source and the runtime (crt0.z80, libc.z80) into .objz80 modules

3. The script generates a .lnk recipe and asm80-link links everything into a .hex

4. asm80-run loads the hex, runs the emulator with a tick limit, and the script checks the serial output against expected results

The tick limit matters here. Each test case gets 100,000 ticks, enough to run any reasonable C test program to completion, but short enough that an infinite loop bails out in milliseconds instead of hanging the build. If the output doesn't match, the test fails. If the emulator hits the tick limit before the program terminates, the test also fails.

The whole thing runs in a few seconds. No browser, no GUI, no clicking. Just a script that compiles C, assembles Z80, links, runs, and tells you if the output is correct. That's the kind of thing asm80-cli was built for.

        ; <LIVESTART maxT=500000>
        ; <SEED A=0x00, B=10, HL=0x4000>
loop:
        add  a, b
        djnz loop  ; <TRACE A, B>
        ; <LIVESTOP A, B, HL>

See the text after the arrows? You didn't type that. It showed up on its own (grey, slightly translucent, sitting right next to your code) the moment your fingers stopped moving. That's ghost text, and it's the result of the IDE assembling your source, spinning up a Z80 emulator, and running the whole thing in the background. Change B=10 to B=5 and the numbers update before you finish reaching for the next key.

That's Live Coding. Let me walk through what's actually going on.

The example, line by line

LIVESTART opens a live coding session. The maxT=500000 parameter sets a T-state budget; the emulator will stop after half a million T-states regardless of where it is. This prevents runaway loops from locking up the IDE. Default is 1000, which is fine for short snippets but too tight for anything with a real loop.

SEED injects values into CPU registers before execution begins. Here I'm setting A to zero, B to 10 (the loop counter for DJNZ), and HL to 0x4000. Every register you don't mention keeps its default (zero on session start, or whatever value it had if you're mid-session). You can use decimal or 0x hex notation — B=10 and B=0x0A are the same thing.

The loop body is two instructions: ADD A, B adds B into A, and DJNZ loop decrements B and jumps back if B isn't zero. Classic Z80 pattern.

TRACE on the DJNZ line captures the CPU state every time the program counter passes through that address. Since this is inside a loop, the ghost text shows aggregated results: 10× means the emulator passed through 10 times, avg 44 T/cycle is the average T-state cost per iteration, and A:0A B:00 are the final values when the loop exited.

LIVESTOP ends the session. The ghost text here shows total T-states for the entire session and the final values of any registers or addresses you listed. The register list is optional — ; <LIVESTOP> alone is valid, it just won't show register values in the ghost text.

How the machine works

Every time you change a character in your source, the IDE kicks off a pipeline: parse, assemble, load into emulator, run from LIVESTART to LIVESTOP (or until maxT is exhausted, or an ASSERT fails). The results get painted as ghost text next to each annotation. The whole cycle typically finishes in single-digit milliseconds for short programs, so it genuinely feels instant.

If your edit introduces an assembly error — misspelled mnemonic, bad operand, unresolved label — the IDE can't produce a binary, so it can't run the emulator. But it doesn't blank out the ghost text. Instead, the text stays in place and turns grey, meaning "this is stale, from the last successful run." You can still read it while you fix your typo. The moment the source assembles cleanly again, the ghost text goes live with fresh values.

You can have multiple live sessions in a single file. Each LIVESTART/LIVESTOP pair is independent. They can't overlap or nest — that's a hard rule — but otherwise you can scatter them through a file to test different sections of your code in isolation.

A note about LIVESTOP: it's optional. If you omit it, the session runs until it exhausts its T-state budget or hits a failing ASSERT. This is fine for quick experiments, but for anything you want to keep, an explicit LIVESTOP makes the intent clearer.

SEED, MEMSTATE, and deterministic runs

Assembly code doesn't exist in a vacuum. Your registers hold values, your memory contains data, your I/O ports have state. If you want Live Coding to show you meaningful results, you need to tell it what state to start from. That's what SEED, MEMSTATE, and PORTSTATE are for.

SEED handles registers:

        ; <SEED A=0xFF, B=10, HL=0x4000, SP=0xFFFF>

MEMSTATE writes bytes into RAM at a specific address:

        ; <MEMSTATE 0x4000: FF 00 AB CD>
        ; <MEMSTATE *: 21 FF FF 3E>

The * address means "continue from where the previous MEMSTATE left off." So if the first line wrote four bytes starting at 0x4000, the second line writes four more bytes starting at 0x4004. Handy for setting up longer data blocks without counting addresses by hand.

PORTSTATE writes to the I/O port address space:

        ; <PORTSTATE FE: BF>

This puts 0xBF at port 0xFE; useful if your code reads from hardware and you want to simulate a particular input.

Placement matters. If SEED or MEMSTATE appears in the header — before the first actual instruction — it sets the initial state for the session. If it appears inline, mid-code, it acts as a one-shot injection: the emulator applies it exactly when the program counter passes through that address. This lets you simulate things like "at this point in execution, new data arrives on port 0xFE."

The reason all of this matters: deterministic runs. If every piece of state is explicitly set, the results are reproducible. Same source, same ghost text, every time. No "it works on my machine" surprises, because there's no ambient machine state to interfere.

How to insert annotations

You don't need to memorize any of this syntax. Type ; < in the editor and autocomplete shows you every available annotation — TRACE, SEED, EXPECT, MEMSTATE, all of them — with parameter hints. Pick one, fill in the arguments, done.

Or right-click anywhere in the editor and select "Insert Live Annotation" from the context menu. The IDE writes the ; <...> wrapper for you.

The annotations live inside comments, so your assembler ignores them completely. They're metadata for the IDE, not instructions for the CPU. Your assembled binary is identical whether annotations are present or not.

Ghost diff and the hover panel

Run that first example again, then change B=10 to B=12. The ghost text updates, and here's what you'll notice: the values that changed since the previous run light up in amber. Values that stayed the same are dimmed. At a glance, you can see exactly what your edit affected.

This is surprisingly useful when you're tweaking loop bounds or modifying an algorithm. You don't need to remember what the values were before — the color tells you what moved.

Hover over any ghost text and a panel pops up showing the complete register file at that snapshot: A, F, B, C, D, E, H, L, the shadow registers, IX, IY, SP, PC, flags — everything the CPU holds. You don't need to add every register to your TRACE annotation; just hover when you need the full picture.

For TRACE inside a loop, the ghost text also includes the iteration count and average T-states per cycle. This is a quick way to check loop performance without manual counting: if you expect 10 iterations at roughly 44 T per cycle and the ghost text says 10× avg 44 T/cycle, your mental model matches reality.

Assertions: EXPECT and ASSERT

Ghost text shows you what happened. Assertions tell the IDE what should happen.

        ; <LIVESTART maxT=100000>
        ; <SEED HL=0x4000>
        ; <MEMSTATE 0x4000: 01 02 03 04>

        ld   a, (hl)         ; A = 01
        add  a, a            ; A = 02
        ld   (hl), a         ; (0x4000) = 02

        ; <EXPECT A=0x02>                      ● green
        ; <MEMEXPECT 0x4000: 02 02 03 04>      ● green
        ; <ASSERT A=0x02>
        nop ; <LIVESTOP A>        → [18 T]  A:02

EXPECT is a soft check. If the condition holds, you get a green dot in the gutter. If it doesn't, a red dot and ghost text showing what the actual value was. Either way, the emulator keeps running. ASSERT is the hard version: if the condition fails, emulation halts right there, the line background tints red, and the ghost text shows you the mismatch.

MEMEXPECT and MEMASSERT do the same thing for memory contents. You specify an address and expected bytes (up to 8):

        ; <MEMEXPECT 0x4000: 02 02 03 04>

If any byte differs, the failing bytes are highlighted in red in the ghost text, giving you a byte-level diff. No guessing which part of your memory block went wrong.

PORTEXPECT and PORTASSERT complete the picture for I/O ports:

        ; <PORTEXPECT 0x10: FF>
        ; <PORTASSERT 0x10: FF>

The practical difference between EXPECT and ASSERT comes down to this: scatter EXPECTs liberally through your code as sanity checks. Use ASSERT for the one invariant that, if violated, means nothing downstream makes sense. EXPECT says "I'd like this to be true." ASSERT says "if this isn't true, stop wasting cycles."

ON N: targeting a specific loop pass

Sometimes you don't care about every pass through a loop. You want the CPU state on exactly the 5th iteration and nothing else. That's ON N:

        ; <LIVESTART maxT=500000>
        ; <SEED B=10>
loop:
        inc  a
        ; <ON 5 TRACE A, B>
        ; <ON 10 EXPECT A=0x0A>
        djnz loop
        ; <LIVESTOP>

ON 5 TRACE A, B fires only on the 5th time the program counter hits that address. Every other pass is ignored. The ghost text shows a single-pass snapshot, not an aggregate.

Combine it with EXPECT and you've got a targeted assertion: "on iteration 10, A must be 0x0A." If your loop logic goes wrong on a specific pass, you'll catch it without wading through all the other iterations.

One edge case: if the loop runs fewer times than your ON target, the ghost text tells you so — something like "loop ran only 7 times" — instead of silently showing nothing. This is helpful when you're debugging early-exit conditions and the loop terminates sooner than expected.

All supported CPUs

Everything I've described works identically across every CPU ASM80 supports. The annotation syntax is the same, only the register names change to match the target architecture.

A SEED for a 6502 file uses A, X, Y, SP. A SEED for a 6809 uses A, B, X, Y, U, S, DP. The annotations adapt; your workflow doesn't change.

What this actually is

Live Coding isn't a debugger. There's no stepping, no breakpoints, no "run to cursor." It's closer to having unit tests embedded directly in your source code that execute continuously as you type. Each annotation is either an observation ("show me A and B here") or an expectation ("A must be 0x02 here"). The feedback loop is measured in milliseconds, not in "save, switch to terminal, run, squint at hex dump."

The annotations stay in your source. They're comments, so they survive assembly, survive version control, survive being shared with someone else. If another person opens your file in ASM80, they see the same ghost text, the same green dots, the same assertions. It's documentation that verifies itself.

Change a constant and every annotation in the file re-evaluates instantly. You know before you even move to the next line whether your code still does what you think it does. And if it doesn't, the ghost text is right there telling you what it actually did instead.

That's the whole point: write code, state what you expect, see the results. If the ghost text agrees with your head, keep going. If it doesn't, you just learned something, and you learned it before you even left the line.

The Machine That Started Everything

In 1975, MOS Technology had a problem. They had designed the 6502 — a CPU that could do most of what the Motorola 6800 did, at a fraction of the price — but nobody believed them. Chuck Peddle, who led the 6502 design team, understood that a datasheet alone wouldn't sell chips. Engineers needed to touch the thing, to run code on it, to prove to themselves it wasn't vaporware. So MOS built the KIM-1: a single-board computer with a hex keypad, six seven-segment LED displays, and one kilobyte of RAM. They released it in 1976 for $245.

Two hundred forty-five dollars. Adjusted for inflation, that's roughly a thousand dollars today — not cheap in an absolute sense, but in 1976 a comparable development system from Motorola or Intel would run you several thousand. The KIM-1 wasn't marketed as a personal computer. It was a development and evaluation board, a way to learn the 6502, a tool for engineers who wanted to prototype embedded systems without committing to a full product design. But something unplanned happened: hobbyists bought it. Radio clubs bought it. Students bought it. People who had no business buying a single-board computer bought one anyway, because for the first time you could afford to own a real CPU and actually program it.

What could you do with 1K of RAM? More than you'd think, and less than you'd want. The KIM-1's monitor ROM — the firmware that handled the keypad, the display, the cassette tape interface — lived in two 6530 RRIOT chips, outside of that 1K. So your full kilobyte from \(0000 to \)03FF was yours. People wrote games, small control programs, music generators, even a chess program (though that one needed expansion memory). The KIM-1 had an expansion connector, and a small industry grew up around selling additional RAM boards — 4K, 8K, eventually 32K and 64K. With enough expansion, you could run a real operating system. But the stock machine, with its hex keypad and its six LED digits, was where most people started.

Programs were entered by hand, one byte at a time, through the keypad. You'd look at a printed listing — often from a magazine or a user group newsletter — and punch in hex codes. If you were lucky, you had a cassette tape interface and could save your work. If you were very lucky, you had a teletype or a serial terminal and could use the KIM-1's paper tape format to load programs faster. The machine was tedious to use and completely transparent. There was no operating system, no abstraction layer, nothing between you and the hardware. That's exactly what made it a brilliant teaching tool, and exactly what makes it satisfying to emulate fifty years later.

Why Emulate This Now?

Modern computers are magnificent and opaque. You can spend years programming one without ever understanding what the CPU is actually doing. The KIM-1 is the opposite: every clock cycle is accountable, every memory access is visible, every I/O operation maps to a physical wire. When you press a key on the hex keypad, the monitor ROM scans the keyboard matrix by writing specific bit patterns to a port, then reads another port to see which key is down. When a digit appears on the LED display, it's because the ROM wrote a segment pattern to one port and a digit-select pattern to another, and it's doing this hundreds of times per second, cycling through all six digits fast enough that your eyes see a steady image.

There's no display driver, no keyboard interrupt, no HAL. Just a CPU, two I/O chips, and a clever piece of firmware. You can trace the entire path from keypress to screen update in your head, or in a debugger, without hitting any abstraction boundary you can't cross. For someone learning how computers actually work — not how to use them, but how they work — there is no better starting point than a machine this simple.

That's why I built this emulator. Not for nostalgia (I don't have any — I never owned a KIM-1), but because it's the clearest possible demonstration of what a computer does at the hardware level. And because the ASM80 IDE already has a 6502 assembler, so the toolchain was sitting right there, waiting.

The ROM Patch Trick

The KIM-1 communicates with a serial terminal through bit-banging. The 6502 runs at 1 MHz, and the serial routines in the monitor ROM toggle I/O pins in carefully timed loops to produce the right baud rate. This works on real hardware. It is a nightmare to emulate accurately.

The problem isn't the 6502 emulation — ASM80's CPU core handles that fine. The problem is timing. On a real KIM-1, the CPU executes one instruction per microsecond (give or take), and the serial routines count cycles to produce precise bit timing at 110 baud or 300 baud or whatever rate the user has configured. In an emulator, the CPU runs inside a JavaScript event loop, driven by an audio callback (more on that later), and the relationship between emulated cycles and real-world time is approximate at best. Bit-banging serial at the wrong speed produces garbage.

The classic solution is to patch the ROM. The KIM-1 monitor has two key entry points: GETCH at \(1E5A (read a character from the serial port) and OUTCH at \)1EA0 (write a character to the serial port). Each of these is a substantial subroutine that handles start bits, stop bits, timing loops, and error checking. In the emulator, we replace them with something much simpler.

GETCH becomes: LDA \(BFFE; RTS. Four bytes. Instead of bit-banging a serial line, the CPU just reads from a magic address. The emulator watches for reads from \)BFFE and returns whatever character the user typed into the browser-based serial terminal.

OUTCH becomes: STA $BFFF; RTS. Another four bytes. The CPU writes a character to a magic address, the emulator catches it and appends the character to the terminal output.

There's one more piece to this. The original serial routines use two zero-page variables — \(EF and \)F0, called CNTH30 and CNTL30 — to store the baud rate timing constants. If these aren't initialized, the monitor hangs on boot trying to auto-detect the baud rate. So the emulator pre-seeds \(EF with 0x07 and \)F0 with 0x27 before the first reset. The values correspond to 300 baud, but it doesn't matter what they are — the patched GETCH and OUTCH never use them. They just need to be non-zero so the auto-baud code doesn't spin forever.

The elegance of this approach is that it's invisible to user code. Any program that calls GETCH or OUTCH through the standard entry points gets the patched versions. Any program that does its own bit-banging will not work, but such programs are rare, and they wouldn't work in an emulator anyway without cycle-accurate serial timing.

The RIOT Chip and the Display/Keyboard Multiplexing

This was the hardest part of the whole project.

The KIM-1 uses two MCS 6530 RRIOT chips. "RRIOT" stands for RAM, ROM, I/O, Timer — each chip contains 64 bytes of RAM, 1K of ROM, two 8-bit I/O ports, and a programmable timer. The two RRIOTs are called RIOT-002 and RIOT-003, and between them they handle all the I/O: the keyboard, the LED display, the cassette tape interface, and the serial port (before patching).

The seven-segment displays and the keyboard share the same I/O port. This sounds insane, and it kind of is, but it made sense in 1976 when every chip cost money. Here's how it works: Port B on RIOT-002 has a Data Direction Register (DDR) that controls which bits are outputs and which are inputs. The monitor ROM constantly cycles through different DDR values. When the DDR is set to drive a particular digit of the display, the ROM writes the corresponding segment pattern to Port A, and that digit lights up. When the DDR is set to scan a particular row of the keyboard, the ROM reads Port A to see which keys are pressed.

In the emulator, we intercept writes to the Port B DDR and decode which operation the monitor is requesting. The formula is: segment = ((ddrB >> 1) & 0x0F) - 4. The result tells us what the monitor wants.

If segment is 0 through 5, we're refreshing one of the six LED digits. The value written to Port A is the segment pattern, and we update the corresponding display element.

If segment is -1, the monitor is trying to read the cassette tape input. We inject 0xFF into Port A (or the current tape bit, if a tape is loaded).

If segment is -2, -3, or -4, the monitor is scanning one of three keyboard rows. Each row covers a different set of keys. Row 0 (segment -4) handles the hex digits 0 through 6. Row 1 (segment -3) handles 7 through D. Row 2 (segment -2) handles the function keys: PC, GO, +, DA, AD, F, and E.

The keyboard encoding is active-low, which means a pressed key is represented by a 0 bit, not a 1. If the user presses key "5" on the hex keypad, and the monitor is scanning row 0, we need to inject a value where bit 5 is zero and all other bits are one. The formula is (row ^ 0x7F) | tapeBit — we XOR the row value with 0x7F to flip all the key bits to their active-low form, then OR in the tape input bit on bit 7.

Getting this right took more debugging time than everything else combined. The multiplexing happens at high speed — the monitor cycles through all display digits and keyboard rows many times per second — and any mistake in the DDR decoding, the port injection, or the active-low encoding produces symptoms that look like random garbage on the display or phantom keypresses. The kind of bug where you stare at a logic analyzer trace (well, a console.log trace) for an hour before you notice that you're shifting right by one when you should be shifting right by one and then masking.

Cassette Tape as a List of Numbers

The real KIM-1 stored programs on audio cassette tape using a variant of the Kansas City Standard. The monitor ROM toggled an output pin at specific frequencies to encode ones and zeros, and read an input pin to detect those frequencies during playback. This is frequency-shift keying (FSK), and accurately emulating it would require modeling audio waveforms, sample rates, and signal detection thresholds. None of which sounded like fun.

Instead, the emulator records cassette data as a list of T-state intervals. When the monitor toggles the tape output bit (PA7 on RIOT-002), the emulator records how many CPU cycles have elapsed since the last toggle. The result is an array of numbers: [412, 413, 207, 206, 412, ...]. Each number represents the time between two successive bit transitions, measured in clock cycles. This captures the timing information that encodes the data without dealing with audio frequencies at all.

Playback works in reverse. The emulator keeps a pointer into the interval array and a cycle counter. Each time the monitor reads the tape input bit, the emulator checks whether enough cycles have elapsed to advance to the next transition. If so, it flips the bit and moves the pointer forward. The monitor's tape-reading routine sees exactly the same timing it would see from a real cassette, because we're replaying the exact cycle counts.

This approach throws away the audio entirely and keeps only the information content. You can't listen to the tape (there's nothing to listen to), but you can save it to a file, load it back, and it works every time. No wobble, no dropout, no "please adjust the volume knob on your tape recorder." The 1970s experience, minus the 1970s frustration.

AudioContext as a Clock

An emulator needs a clock. The CPU has to execute instructions at a consistent rate, and the display has to update smoothly, and everything has to stay in sync with real time. In a browser, you have three options: setTimeout, requestAnimationFrame, or the Web Audio API. The first two are unreliable — the browser can throttle them, delay them, or skip them entirely when the tab is in the background. The Web Audio API, specifically ScriptProcessorNode, is the one thing browsers take seriously about timing, because audio glitches are audible and users complain.

The emulator creates an AudioContext at 48 kHz and a ScriptProcessorNode with a buffer size of 2048 samples. Every time the audio system needs a new buffer, it fires a callback. At 48 kHz, 2048 samples is about 42.67 milliseconds — roughly 24 frames per second. Each callback runs the CPU for the appropriate number of cycles (about 42,670 at 1 MHz), then updates the display.

The display update has a subtle trick. The KIM-1's LEDs are multiplexed — the monitor ROM lights one digit at a time, cycling through all six fast enough that they appear steady. In a 42ms frame, the monitor might refresh each digit several times, or it might not get to all of them (if the user's code is doing something time-consuming). The emulator handles this with afterglow: if a digit wasn't refreshed during the current frame, its last value is preserved on screen. If a digit was written with a null pattern (all segments off), it keeps its previous value. This mimics the phosphor-like persistence of real LED displays — not because LEDs have phosphor, but because the human eye retains the image of a briefly-lit digit for a few tens of milliseconds. The effect is the same. Without afterglow, the display flickers horribly. With it, the digits appear steady, exactly as they do on a real KIM-1.

Yes, ScriptProcessorNode is deprecated. Yes, I should migrate to AudioWorklet. It's on the list. The deprecated API works in every browser today, and when it stops working, I'll deal with it. Premature migration is the root of all... well, not evil, but definitely wasted weekends.

SST Mode

The KIM-1 has a hardware single-step mode, controlled by a physical toggle switch on the board. When SST is on, the CPU executes one instruction, then immediately takes a Non-Maskable Interrupt (NMI). The NMI vector points into the monitor ROM, which displays the current registers and waits for the user to press GO to execute the next instruction.

On the real hardware, this works because the SST switch is wired to the NMI line through some edge-detection logic. After each instruction completes, if the switch is in the SST position, the hardware triggers an NMI.

In the emulator, the entire mechanism is one line of JavaScript. After each instruction executes, if the SST flag is set, call cpu.nmi(). That's it. The monitor ROM handles everything else — saving registers, displaying them on the LEDs, waiting for GO — exactly as it does on the real machine. The ROM doesn't know or care that the NMI came from a JavaScript boolean instead of a physical switch. An NMI is an NMI.

The toggle switch itself is rendered as an HTML checkbox, injected into the SVG front panel image via a <foreignObject> element. It sits right where the real switch would be. Click it on, and every instruction triggers NMI. Click it off, and the CPU runs free. The checkbox maps to a boolean, the boolean maps to an NMI call, and the original 1976 hardware design just... works, unchanged, fifty years later, in a browser.

This was the easiest part of the whole project. I kept waiting for it to be more complicated. It wasn't.

MOS Papertape Format

Before there were hex files (Intel HEX, Motorola S-records), MOS Technology defined their own format for storing programs on paper tape. The KIM-1 uses it for loading and saving programs through the serial port, and ASM80 supports it for uploading code to the emulator.

Each record starts with a semicolon and has the format: ;LLAAAADDDD...DDSS. LL is the byte count (how many data bytes follow). AAAA is the starting address, big-endian. Then come the data bytes, each as two hex digits. Finally, SS is a 16-bit checksum, stored big-endian with the high byte first.

The checksum is the sum of the byte count, the address high byte, the address low byte, and all the data bytes, modulo 65536. It's stored in two bytes, high byte first — which is the opposite of the 6502's native little-endian byte order. I assume this made sense to someone at MOS Technology in 1976. Maybe they were Motorola alumni. Maybe they just liked big-endian checksums. I didn't ask.

The end-of-file record is always ;0000040001. Zero data bytes, address \(0004, checksum \)0001. Why address \(0004? It's the reset vector for the monitor — pressing GO jumps through \)0004. The checksum is \(0001 because 0x00 + 0x00 + 0x04 = 0x0004... wait, that's \)0004, not \(0001. The end record is actually a special case; the checksum value \)0001 is a convention, not a computed value. The loader recognizes it as the terminator.

In the ASM80 IDE, you can load .pap files directly into the emulator's memory. The parser reads each record, validates the checksum, and writes the data bytes to the specified addresses. Saving works in reverse: select an address range, and the IDE generates .pap records with correct checksums. It's a simple format — no compression, no relocation, no metadata — and that simplicity is exactly why it's still easy to work with half a century later.

Why It's Satisfying

The KIM-1 is a machine simple enough to hold in your head. All of it. The CPU has 56 instructions, 13 addressing modes, and three registers that matter (A, X, Y plus the status flags). The address space is 64K, of which only 2K is ROM and 1K is RAM. The I/O is two chips with two ports each. The monitor firmware is about 2K of hand-written 6502 assembly. You can understand the whole thing — not superficially, not "I get the general idea," but actually understand every byte, every pin, every timing constraint.

That's why it was a teaching tool in 1976, and that's why it's still a teaching tool now. When you type a hex value on the keypad and watch it appear on the LED display, you can trace the entire path: the keyboard scan in the monitor ROM, the DDR writes to the RIOT, the port reads, the lookup table for the key code, the segment pattern write, the display multiplex cycle. There's nothing hidden. There's nothing you have to take on faith.

Modern computers are better at everything except being understandable. The KIM-1 is worse at everything except being transparent. And transparency, it turns out, is the one thing you can't get from a faster chip.

The emulator runs at asm80.com. Load a .pap file, flip the SST switch, step through the monitor ROM one instruction at a time, and watch a fifty-year-old design do its work. It's the same machine Chuck Peddle's team built to prove that their cheap little CPU was real. It's still proving it.