What It Is

This repository is the current official PiDP-8/I software development nexus. Here we continue development of the software from the last stable software version published on the kit information site. This software differs in several major ways and dozens of minor ways from that old software.

Getting Started: Source Code

The recommended way to get started is to build this software from source into an existing Raspberry Pi OS installation on the Pi you are using with the PiDP-8/I board. Raspberry Pi OS Bookworm or later (64-bit) is required. It also works with some other OSes.

The last tagged release was cut on 2021.02.14, but trunk is well ahead of that. Building from trunk is the recommended starting point for new installs. A new tagged release is expected by mid-April 2026. See the README.md file for full details on how to clone from Fossil, configure, build, and install.

Oscar Vermeulen's quick install page offers an alternative set of copy-and-paste instructions for building from trunk. Note that his recipe uses ~/tangent as the build directory rather than ~/pidp8i as we do here — something to be aware of if you are following instructions from both sites.

If you specifically need the 2021.02.14 tagged release, it remains available as a tarball (about 17 MB). The tip of trunk is also available as a tarball for those who prefer not to use Fossil directly.

Getting Started: Binary OS Images

Those with plenty of Internet bandwidth and a micro SD card they don't mind overwriting may prefer to use a pre-built binary OS image. The upcoming release will provide an image based on Debian Trixie (64-bit ARM), roughly 3.7 GB unzipped, which runs on the Pi Zero 2 W, Pi 2, Pi 3, Pi 4, and Pi 5:

Upcoming release (not yet available — link will be active when the release is tagged)

The image boots directly into a running PiDP-8/I simulator with the front panel lights blinking. SSH is enabled out of the box. WiFi can be pre-configured by editing a file on the boot partition before first boot. See the installation instructions for full details.

Oscar Vermeulen also maintains independent pre-built SD card images on his quick install page, based on a trunk snapshot from early 2024. These cover the Pi 4 and the Pi Zero 2 W, Pi 2, and Pi 3.

Legacy Binary Images

The previous binary releases (v2021.02.14), based on Raspberry Pi OS Buster Lite, remain available for those running the original Pi Zero (ARMv6) which is not supported by the current image:

ILS version (2021.02.14) — for Pi 2 and Pi 3 (multi-core, with incandescent lamp simulator); roughly 850 MB
NLS version (2021.02.14) — for original Pi Zero, Pi A+, Pi B+ (single-core); roughly 850 MB

Note that the 2021.02.14 ILS image does not work on Pi 4 and up due to a hardware change introduced in that generation. Users on Pi 4 or Pi 5 should build from source using the instructions above.

Updating an Existing Binary OS Installation

As shipped, the binary OS images contain the PiDP-8/I software source code and Fossil, which lets you update the software without re-flashing your SD card. This suffices for typical cases:

$ cd ~/pidp8i
$ fossil update
$ make reconfig
$ tools/mmake && sudo make install
$ sudo systemctl daemon-reload
$ pidp8i restart
$ pidp8i

By default, that will get you the latest tagged release version. To follow trunk instead:

$ fossil update trunk

From then on, fossil up will update you to the latest trunk without needing to specify the branch name each time. To switch back to the release branch:

$ fossil update release

OS/8 RK05 Media

One of the most time-consuming steps in building the PiDP-8/I software is building the OS/8 RK05 disk images from pristine, tested, curated sources. If you simply want the resulting disk images, they are provided here for direct download:

Name	Contents
V3D `dist`	OS/8 V3D in its as-distributed state: no patches, no add-ons
V3D `patched`	`dist` plus a coherent set of bug-fixing patches; the most useful "clean" image
V3D `boot`	`patched` plus selected add-ons; boots with IF=0 on the PiDP-8/I
V3D `src`	non-bootable disk containing the contents of all ten OS/8 V3D source tapes
OCK `dist`	OS/8 Combined Kit (OCK) version of the `dist` image above
OCK `patched`	OS/8 Combined Kit (OCK) version of the `patched` image above
OCK `boot`	OS/8 Combined Kit (OCK) version of the `boot` image above

These disk images were last updated on 2021.02.14 and are considered stable. They should work under SIMH on any platform, and could potentially even be written back to real RK05 disk packs and run on actual PDP-8 hardware. Let us know how you're using them on the PiDP-8/I mailing list.

They were built with the default set of --enable-os8-* options and assume the simulated hardware configuration of the PiDP-8/I. If you need a different software set or hardware configuration, download the source and build the disk images yourself. The software currently builds on several different platforms, not just the Raspberry Pi.

Learning More

Official Project Resources

The current PiDP-8/I software has many more features and many fewer bugs than Oscar's original version, but in the end both do more or less the same thing, so Oscar's documentation still applies fairly well. The primary source of discrepancies between his documentation and this software are described on the Major Differences wiki page.

You're welcome to discuss this version of the PiDP-8/I software on the PiDP-8/I mailing list, hosted by Google Groups. Those active in its development participate there and usually react quickly to posts about this software.

Project Documentation

This software project has its own documentation and tutorials, collected here for convenience:

The top-level README file tells how to configure, build, and start using the PiDP-8/I software.
The full reference for all configure script options is in its own document. The build system is highly configurable with many subtle aspects that are useful to some, but that most users will not need to bother with.
Configuration of the simulator's throttle is complicated enough to deserve its own document.
The binary OS image guide explains how to install it to an SD card and get started.
While building your PiDP-8/I, you may run into trouble which can be diagnosed by the pidp8i-test program, documented here.
The project wiki contains several tutorials, design documents, etc.
The project ships several example programs for those who want to learn to program the PDP-8.
We ship a Python class called simh for controlling SIMH and OS/8 from the host system. See its tutorial.
There is a tutorial for the DCP disassembler installed on the OS/8 disk packs by default.
The default OS/8 boot disk has many patches applied, described in the linked document, along with information about the DEC patches we have chosen not to apply.
There are several documents about the U/W FOCAL V4E distribution included on the standard OS/8 boot disk, starting with our U/W FOCAL manual supplement.
For a detailed user-focused list of changes since this project began, see the ChangeLog.
If you would like to contribute to the development of the PiDP-8/I software project, see the contribution guide.
The KiCad PiDP-8/I front panel schematic was converted to PDF by Tony Hill. (400 kB)
Who brought all of this software, hardware, and documentation to you? See the project's authors file. Those pieces are included under a variety of licenses.

SIMH Documentation

The PiDP-8/I software project is based on the actively-developed official version of SIMH. The SIMH project has its own documentation, but PDF versions of the relevant subset are provided here for convenience:

SIMH Main Manual — Required reading if you want to give commands at the sim> prompt (Ctrl-E from within the simulator) or read and modify boot/*.script.
PDP-8 Simulator Manual — Covers details specific to the PDP-8 simulator. (The main manual covers functionality common to all SIMH simulators.)
SIMH FAQ — Frequently-asked questions about SIMH, with answers.

Rare PDP-8 Documentation

While most of the information about the PDP-8 is widely available on the Internet and may thus be easily found by Googling, we have a small number of documents here that are not so easy to come by, plus some links that don't seem to come up as high in Google searches as they ought to.

Note that while the PiDP-8/I kit replicates the front panel of the PDP-8/I, the SIMH emulation implements the instruction set of the later PDP-8/e. For front panel operation, reach for the 1969 edition; for programming and instruction set details, the 1973 edition is more accurate.

DEC's 1969 edition System User's Guide for the PDP-8 family computers, the pinnacle of which was the PDP-8/I at that time. DEC published many editions of this guide, and the newer versions come up far more frequently in web searches, but they're often not OCR'd (whereas this version is) and they tend to focus on the newer PDP-8 models which don't apply entirely to the PDP-8/I.
DEC's 1973 Small Computer Handbook, because when dealing with SIMH, you actually want documentation of the newer models of PDP-8, since SIMH simulates a fairly tricked-out late-model PDP-8; there is no easy way to restrict SIMH to support only the features that existed at the time of the PDP-8/I. For example, SIMH's PDP-8 simulator will process mode B EAE instructions introduced in the PDP-8/e, well after the PDP-8/I came out with its less functional EAE option.

You may want to split the difference between these two documents and try to find a 1968 edition of the Small Computer Handbook. The closest I'm aware of online is the 1967 edition which mentions the PDP-8/I inside, but shows the original PDP-8 "Straight Eight" and a PDP-8/S on the cover. I assume it was written while the PDP-8/I design was being finalized, so it may be fairly accurate, and it may be full of bugs; I couldn't say. I happen to have here a paper copy of the 1968 edition, which you can tell from the 1967 edition by the yellow-green themed cover (JPEG, 473 kB) showing the standard rack-mounted and rare console version of the PDP-8/I.

PiDP-8/I Software