Help file related to the PET 2001 Emulator.

PET 2001 Emulator Guide

Topics:

Welcome to the PET 2001

The Commodore PET 2001 (as in Personal Electronic Transactor + a magic number) was the earliest of the first three ready-to-run home computers that were introduced in 1977, also known as the “trinity of 1977”. It doesn‘t have sound (which was soon overcome by some ingenuity) and it features character graphics only, but it’s a great little computer and fun to program. This help section is not so much about operating the original computer (for this refer to the manual section), but about how to operate the emulator.

Keyboard Input

Computer Keyboard

Support of real keyboards is set up so that you may type as natural as possible. The emulator implements a symbolic keyboard, meaning, special characters are generally what they are on your keyboard.

This also means that some characters that are shifted keys on your keyboard may not be available as shifted keys in a program, but shifted keys still work for any alphabetical keys and keys on the number — even the BASIC abbreviation work! In order to enter any other shifted keys (e.g. for PETSCII graphics), simply hold the SHIFT key and click the respective key on the virtual keyboard below the screen.

Special Key Mappings

Not all PETSCII characters have a direct equivalenant on modern keyboards. Therefore, a few special mappings are used (ALT is Option on Mac):

STOP
is mapped to ESC.
is mapped to the caret (“^”) and to TAB, as well.
(Some games use “↑” for fire and this should make for a convenient action key.)
Moreover, the first key in the first row (left of “1”) and the key next to the right SHIFT key (and left of “Z”) may work, if this is something like “`/~”.
is mapped to the underscore (“_”).
(“↑“ and “←” are really the same characters as “^” and “_”, respectively, just in an older ASCII standard.)
π
Pi is mapped to SHIFT+TAB and should generally work as a shifted key for any keys which are regognized as “↑”.
RVS ON
is mapped to to ALT + TAB.
RVS ON is also mapped to “®”, which should be ALT+R on most keyboards.
If thereā€˜s an ALT key distinct from an ALT-GR key, this should work together with R, as well.
RVS OFF
is mapped to to ALT + SHIFT + TAB.
It should also work with ALT+SHIFT+R. (May be subject to the type of keyboard used.)
DECIMAL
the DECIMAL key on the number pad is mapped to the dot (“.”), just like on the PET.
NUMPAD =
similarly, the ENTER key on the number pad is mapped to “=”.
PAUSE
ALT+ESC pauses/resumes the emulator.

The emulator also supports Unicode character input as may provided by a special keyboard layout. See this Unicode-to-PETSCII chart regarding input mapping.

E.g., here is a Mac OS layout for the Commander X-16 keyboard: Commander-X16-PETSCII.dmg.
(This should work with any US / international keyboard featuring C64/VIC-20-like legends.)
Note:You may have to log out and in again. If the keyboard layout doesn’t show up under the input sources, open the “Keyboard” preferences, select the tab “Input Sources”, press the “+“ button, and import “Commander-X16” from the “en” language group. The layout should be now available both in the preferences and in the keyboard menu.

Keyboard Modes

The emulator features two distinct input modes, selected by the “Keyboard” menu below the emulated screen:

Edit Mode

This guarantees that there is just a single, distinct key pressed at any time. It also implements key repeat, which is not found on the PET 2001 out of the box. This is generally the best mode for programming and any text=oriented activities. The emulator always resets to this mode, in order to prevent confusion.

Games Mode

This faithfully emulates the key action of the real PET 2001 and is best for games and any programs that may implement their own keyboard scan routine in order to detect multiple key-presses at once.

Games Mode features a special input mechanism with CAPS LOCK engaged, which is used to toggle the following modes on and off:

  • First, there’s the virtual joystick mode, which is only active when any joystick scheme is enabled: with CAPS LOCK engaged, the cursor keys and the space bar are mapped to the joystick directions and the fire button, respectively.
    (This also works with any of the “to keyboard” modes, which allows you to play any of the games requiring a numeric keypad, even, if your computer doesn’t have one.)
    An activity indicator below the joystick icon provides feedback and doubles as a reminder that the virtual joystick mode is active.
  • Similarly — and somewhat alternatively —, there is a virtual numeric keypad mode, which emulates a numeric keypad on computers that do not have one. For this, activate the virtual keypad option by clicking its icon below the PET’s virtual screen and use again CAPS-LOCK to toggle in and out of this mode as required.

    The keys will be mapped as follows, using the keys 7, 8, 9, and below:

    7  8  9     7  8  9
    U  I  O  →  4  5  6
    J  K  L     1  2  3
    M           0

    Again, there’s a small activity indicator for visual feedback.

You may disable any of those mappings momentarily by pressing SHIFT and the conflicting key. Mind that this does not work with the option for rerouting joystick input to the numeric keypad and SHIFT as the fire button.

The Virtual Keyboard

The virtual keyboard, depicted below the emulated screen works both with touch input and mouse clicks: simply tap or click a key on the keyboard image (visual feedbak is provided). Moreover, holding down the SHIFT key on the physical keyboard will also affect the virtual keyboard. (So you may conveniently enter PETSCII characters by SHIFT-kclicking the respective key image.

In Edit Mode the virtual keyboard generates a single, distinctive key-press at any time and SHIFT keys work as a toggle.

In Games Mode keys are set by multi-touch interaction, just like on the real PET 2001.
If your device does not support multi-touch or does not have a touch screen, you can emulate multi-touch by holding down the ALT key for multiple, concurrent key-presses. (Mind that you have to reload the page for this to work, if you are switching a desktop browser to responsive design mode, as this detected on page-load.)

Multiple, concurrent key-presses in “Games Mode” may not work as you might expect with the standard Commodore keyboard scan routine, as this doesn‘t implement full key-rollover.

Business Keyboard

The business keyboard is available by selecting any of the “CBM 2001/B” options from the ROM menu. There are few differences regarding the keyboard mapping:

  • Since the business keyboard features an ESC key of its own, ESC is mapped to this and STOP is mapped to ALT + ESC.
  • Similarly, TAB is mapped to TAB, but you can still use ALT + TAB for RVS ON/OFF.
  • Mind that the keys of the numeric keypad, while resulting in the same PETSCII codes as numbers entered by the main key pad have distinctive internal key codes. For games, be sure to use the number pad for this or the virtual numeric keypad.
  • For the business keyboard, the virtual keyboard generally behaves like in “Games Mode”. You may want to use the SHIFT LOCK key to enter shifted characters.
  • TO use the SHIFT LOCK or REPEAT keys, use the virtual keyboard. These are not mapped otherwise.

Please mind that the business keyboard doesn’t feature any provisions for entering graphics characters (other than those corresponding to to upper-case characters) or pi (π). This is a treat of the original PETs coming with the business keyboard.

Click/Touch Cursor Controls

The “click cursor” allows you to freely position the cursor anywhere on the screen, by simply clicking or tapping onto the emulated screen. Repositioning the cursor will also force the editor out of quote/insert mode and reset any active RVS ON mode.

To use this feature, please activate the checkbox “Click Cursor” below the emulated screen. Be aware that accidential clicks/taps may interfere with input statements. So, while this is helpful for editing and sketching up things on the screen, it may be best to leave this option off while running programs.

Character Sets

The PET 2001 features, like all the Commodore 8-bit computers that followed, two character sets, one for upper case letters and graphics characters (default), and one for upper-case / lower case text and just a limited range of graphics characters. Mind that the original PET 2001, unlike later models, displayed unshifted characters in upper-case in both modes and displayed lower-case letters for shifted characters!

This is how you change the character set on the PET 2001 (by a POKE to a hardware address, the PCR of the VIA):

  • POKE 59468,12 … switch to upper case / graphics.
  • POKE 59468,14 … switch to upper case / lower case.

There’s also an item “Switch Character Set” in the “Utils/Export” menu (see below) and a respective item in the context menu for the virtual screen that will do the same for you.

Later ROM revisions implemented the mixed case (“business”) character set with shifted letters in upper-case, like it is found on later 8-bit Commodore machines. This is automatically implemented with ROM 4.0 (see below) and you can always switch bitween the old and new version of the character ROM by an item of the virtual screen‘s context menu (see bleow).

Emulator Controls

The emulator features a set of basic controls, which are found below the virtual screen in two rows.

First row:

Reset
Resets the virtual PET in its current configuration. SHIFT-clicking or CTRL-clicking this button will reset the machine to default values (the same configuration the machine is using, when the page is initially loaded). If the page was loaded with a special configuration, like a link to a program to load (see below), the latter option will also create a new entry in the browser history.
Pause
Pauses or resumes the virtual machine, toggling between the respective states.
(The virtual machine will also be implictely paused, while a dialog is displayed or when the emulator is in a hidden browser tab.)
Utils/Export
A menu with various export options and some helpful utilities. This will be covered more extensively below.
Screen Color
PET 2001s came both with white screens and green phosphor screens. There‘s also an option for an inverted (dark on white) E-Ink display, not found on the original. Select your favorite screen color here.
Keyboard Mode
Controls the virtual key repeat added by the emulator. Choose between “Editing” (repeat on) and “Games” (repeat off, unmodified input).
ROM Version

ROM versions available are,

A) For the original PET 2001 and PET 2001N:

ROM 1
This is the ROM originally delivered with the first batch of PET 2001s, also known as “Old ROM”. This has a few quirks, like an incomplete IEEE bus implementation (disk operations don’t really work, but this is partially fixed in the emulator) and no built-in monitor.
ROM 2
This is the upgraded ROM for the PET 2001 with BASIC 2.0, also known as “New ROM”. (The same Commodore BASIC also known from the VIC-20 and the C64, which made its debut on the PET 2001.) This is also the default.
ROM 4
BASIC 4.0 for the PET 2001N. This is mostly compatible with ROM 2 and shares most of the zero page addresses, but comes with additional disk commands. Chosing ROM 4 will also activate the new character ROM with unshifted lower-case characters.

B) For the CBM 2001/B with the business keyboard:

ROM 2b
BASIC 2.0 with the business keyboard for the “Series 2001/B Business Computer” or CBM 2001/B.
ROM 4b
BASIC 4.0 with the business keyboard for the CBM 2001/B.

Most programs written with the PET 2001 in mind will require ROM 2, which may be generally the best option. Some very old programs may require ROM 1, while newer ones may use ROM 4 — if not stated otherwise, it’s really a matter of trying. (Please mind that the emulator currently doesn’t support any of the additional disk commands that came with Commodore Basic 4.0, but the most basic ones, like DLOAD and DSAVE.)
Changing the ROM version will reset the virtual machine.
(Mind that ROM 2 is also known as ROM 3. Officially it was the “Level II ROM Set” and may be identified by its use of pound marks in the startup message, whereas ROMs 1 and 4 use asterisks.)

RAM Size
Chosse between 8K, 16K and 36K of RAM.
While 8K was the standard configuration, some programs will require an extra amount of RAM.
Changing the RAM size will reset the virtual machine.

Second row:

Click Cursor
This option allows you to freely position the cursor on the virtual screen by simply clicking/tapping on the desired location. Repositioning the cursor will also force the editor out of quote/insert mode and reset any active RVS ON mode. (Since this may interfere with input statements, this option may be best left off while running programs.)
Prg Library
Displays a list of programs in an overlay. Use the “run” or “online” links to try them in the emulator without reloading. (Shift-clicking such a link will create a new entry in your browser history.)
Shift-click or ctrl-click the button to open the program library in a new window.
Mount File
Use the file dialog to locate a program file or archive to mount, ready for use. See below for supported formats. Generally, just dragging and dropping a file onto the virtual screen of the emulator will be simpler und do the same job.
Directory
A button to access a directory listing may appear in this place, if you loaded/mounted a disk or tape archive (see below).
File Display
A mounted file will be indicated by a media icon and the file name next to it. Clicking the media icon will trigger the most appropriate action: either load and run a single program or bring up a directory dialog for an archive format.
The file icon also serves a file activity indicator and will light up during file access.
In case you would want to reset the mounted media, there’s an option for this in context menu of the file display.
Virtual Keypad
Activates the virtual keypad option (see the section on the keyboard above). This only affects the keyboard when in Games Mode and with CAPS-LOCK engaged.
Joystick
Opens a dialog for selecting the type of joystick adapter to use. Also an indicator for whether joystick support is currently active or not.
Sound Controls
The final element are the sound controls. Mind that the volume is relative to the volume set on your system. A click on the speaker icon mutes and unmutes audio. (Audio will be entirely disconnected, when sound is off, which may be favorable for battery life.) The wave icon at the right of the volume slider activates a bit of experimental post processing, which is meant to work somewhat like the “loudness” option found on audio equipment.

Saving Files

The emulator has a virtual IEEE-488 device attached at address 8, which can be used to load and save files. To save a program, type “SAVE"NAME",8” (replace “NAME” by your actual choice) and the emulator will generate a binary file in .prg format. The file will presented as link, which you can either click to download it directly into your configured download folder, or you may right-click it and chose “Save Link As…” (or similar) to save it under a name and location of your choosing.

There’s also an option “Export PRG-File From Memory ” in the “Utils/Export” menu, which does essentially the same, without requiring an explicit command to be typed into the virtual machine.

(Note that IEEE-488 doesn’t work very well with ROM version 1.)

Loading Files

There are several ways of loading a file into the emulator:

  • Mounting a file and typing “LOAD"NAME",8” into the emulated PET. This will load any previously mounted file into the emulator.

    Note on ROM 1.0 (old Rom):
    IEEE-support isn’t great with ROM version 1 and requires pessing the STOP key. The emulator will press the STOP key for you automatically and will, in case the file starts at the usual BASIC start at $0401, attempt to adjust the BASIC system pointers according to the program. If all works well, there shouldn’t be any notable difference in operations.

    Note on binary and BASIC program types:
    Unlike with later Commodore 8-bit computers, files are always loaded absolute on the PET. In order to run BASIC programs from other Commodore machines, the emulator uses drive number 8 to force a program to be loaded to the usual start address of BASIC at $0401, as in “LOAD"8:NAME",8”. Unlike with the better known C64, there is no secondary drive address on the PET!

  • Dropping a file on the virtual screen of the emulator. An overlay and a glow around the edges will signal the reponse, as soon as you move a file over the virtual screen. Dropping the file onto the screen will either automatically load the program, if it is a single file format, or show a directory, if it is an archive. Drag & drop is probably the simplest option.
  • If you have loaded previously an archive file, there will be a button “Disk Directory” or “Tape Directory”. Clicking this button will bring up a dialog to select the program and any options. The emulator also provides an appropriate directory listing for these archives to BASIC on “LOAD "$",8”.
  • You may load a program or archive by a special URL-link or directly from the Program Library.
  • Finally you may click the media acount to the left of the displayed file name. This will trigger the most appropriate action, either reset and load + run a single file or bring up a directory dialog for an archive format.

Mounting Files

You may mount a file either via the “Mount File” button, which will give you access to your normal system file dialog or per drag and drop. Archive formats, like disk images, will bring up a directory dialog. The emulator supports full access via “LOAD”. There’s also full support for disk directories in drive 8 (including wildcards and type selectors). Tape archives (“.t64”) are handled like disks mounted in drive 8. Binary PRG-files will load and start automatically, when dropped, but not when mounted via the “Mount File” dialog.

Supported File Formats

There are a number of file formats supported by the emulator, commonly known by their file extension:

  • Program Files (.prg, .pet):
    This is the standard format for program files on Commodore 8-bit machines. It’s the same format the original machines used to save files on tape or on floppy disks.
    These files will be normally run automatically by the emulator. Hold SHIFT while dropping such a file onto the emulator to just load a program without running it automatically.
  • Disk Archives (.d64, .d80, .d82):
    D64 has somewhat become the standard format for floppy disk images for Commodore machines. D80 and D82 archives (images of 8050 and 8052 disk drive formats) are often related to files for the 80xx series and will probably require ROM 4.
    Loading a disk image file will bring up a directory listing, where you may chose a prorgam to run and select some options.
    Options are:
    Load as BASIC
    Forces the virtual machine to load this file as a normal BASIC program. Normally, a program will be laoded as a binary file at the address found at the very beginning of the program-file, which is usually what you want (same as “LOAD "NAME",8,1” on later Commodore machines). However, you may want to run a BASIC program which was meant for a different Commodore 8-bit machine, which uses a different start address for BASIC programs. Check this option in order to do so and the PET will adjust the program to the usual start address.
    Reset
    This will reset the virtual machine prior to loading the program.
    Auto-Run
    Automatically run the program after loading. Otherwise, you’ll have to type “RUN” and press ENTER manually. However, you may want to inspect the program by typing “LIST” or using any of the Utilities (see below), in which case this option should be off.
    Min. RAM Size
    Lets you manually choose a RAM configuaration (the file size listed along the file names may provide a hint). Otherwise, the emulator will make a smart guess, which may not be that smart, anyway.
    Each of the items in a directory list features a context menu that allows you to directly extract a given file from an archive and to save it as a separate file to your drive.
    In case the archive was loaded from the Program Library, an item’s context menu will also include an option for a direct link to run this item. (Presets for the ROM version, sound and screen color are determined from current settings.)
  • T64 Tape Archives (.t64):
    T64 is for tape archives what D64 is for disk archives. The directory dialog for this has the same options as above.
    (Documentation for this format is somewhat lacking. The implementation has been tested with version $100 files and works, like VICE, for type 1 files, which are programs, only. Other file types, while parsed, will be ignored in the catalog. File sizes are checked to work around a common bug with early T64-files. Mind that T64 tape images are intended for the C64, however, some programs, like the type-in ones from books and magazines, will run on a PET with little adjustment. You probably want to load those programs as BASIC files and LIST them before running to check for POKE-commands, etc.)
  • P00 Files (.p00.p99):
    This is a single-file format commonly found on DOS, but it’s also used to store PET programs in some rare cases.
  • BASIC Source Files (.txt, .text, .bas, .ba):
    Load BASIC source files in plain text. Edit files in your favorite editor or copy them from type-in listings and simply drop them onto the emulator (or load it by the file-upload dialog). The editor will use the same algorithm as the real machine to transform them into regular, binary Commodore BASIC programs. The source code may be either in lower case or in upper case (or even mixed). The usual abbreviations for commands are recognized (works best in lower case source texts). PETSCII special characters may be escaped in curly brackets (“{…}”), see below for details.
  • 6502 Assembler Source Files (.a, .as, .asm, .a65, .s, .src):
    The emulator features a built-in 6502 assembler (more on this below). The emulator will present a listing of the 2-pass assembly process, and, in case that the build was sucessful, will present some options for what to do next (like load the program, inject it directly into memory, or export it as a file.)

The emulator will accept only files with any of the file extensions listed above and will handle the files based on that extension.

A places to look for program files may be www.zimmers.net/anonftp/pub/cbm/pet/ALLFILES.html (have a look at the sections demos/Cursor/ and games/). Download files to your computer and then drop them onto the emulator.

Techical Notes — How it Works
Technically, loading files is implemented by a special IEEE data input buffer. When you mount a file, this buffer is filled with the contents of that file along with the start address, and the next LOAD command will use this as the source. Even if filenames do not match. (There’s also a small default file with instructions, which will be loaded whenever you attempt to load a file without mounting anything prior to this.) If you load a file from an archive, like a disk image, and there is a matching file, the file will be transferred to the buffer on a first step. Otherwise, you will just reload what happens to be in the buffer, which is the last file loaded. (There is currently no facility to report a missing file to the virtual PET.) Auto-load and auto-run are implemented by automatically typing the respective commands into the virtual PET, as soon as it is ready to accept input and flashes its cursor. Thus, the procedure is identical to manual typing these commands.
Dropping a file or loading a file from a directory dialog chains these steps (mounting a file, loading it, and running it) into a single, automated flow.

Developer Info: Save States
If you want to export a save state for your users, you can do so by saving a program with a filename ending in the file extension ".SAV" to device address 8 (default floppy drive). Any such file will be downloaded to the user’s local download folder with this very file extension. When you later try to load a program with such a file extension, the user will be prompted for the file. The existing mount point will remain undisturbed and a special, temporary mount point will be used instead. Thus, you can still load overlays, etc, from an archive, like a disk image, and the user can still rerun the program by clicking the file icon.

In the event that the user leaves the dialog without selecting a file and a temporary save file has been loaded before, this one will be reused. If there isn’t such a file, a zero byte will be loaded into the very last byte of the off-screen part of the video RAM at 0x83FF, dec. 33791. If you’re loading a saved state from a machine language program, you may preset and then check this byte for success.

Mind that this will not really work from within BASIC, as your program will start over after issueing a LOAD command. (You could, however, try to set some control values and flags in a safe memory space, like the cassette buffer in order to preserve state. The same goes for setting up some values to save as a program in the first place.)

BASIC Source Files

Editing BASIC source file using your own, favorite text editor and simply dropping them onto the emulator is probably the most comfortable way of programming a PET 2001. (No chiclet keyboard, and, while the BASIC editor was certainly nice for its time, your text editor is probably better at it.) Just be sure to save the file as a plain text-file (Unicode is supported, of course).

BASIC source files maybe in either character case, the emulator will try to figure out the correct case for each of the lines. If a line starts in lower case, it will assume lower-case text. Otherwise, it will assume upper-case text (default). Meaning, you may even mix case between lines, as it may happen with copy & paste. Empty lines will be simple ignored.

The usual rules for BASIC text apply: You may use “?” for PRINT and even the usal Commodore BASIC abbreviation, like “pO” or “poK” for “POKE”. Mind that BASIC only accepts lines of up to 80 bytes length (that is, after tokenizing any BASIC keywords to single bytes). The emulator will abort with an error message, if a line exceeds the maximum length. Also mind that the maximum line number in Commodore BASIC is 63999!

Escapes for PETSCII Characters in BASIC source Files

While the emulator recognizes Unicode substitutes for PETSCII characters (including the new “symbols for legacy computing” range), not all PETSCII characters can be expressed in Unicode. Hence, any special PETSCII characters should be escaped in a special markup. (Mind that graphics characters may appear in BASIC only inside strings.) The emulator uses curly brackets for this (“{…}”), which may embrace either a PETSCII character code in decimal or hex notation or a label.

{ddd}
Decimal character code escape, like “{147}” (clear screen) or {18} (rvs on).
{$hh}
Character code in hexadecimal notation (with a leading dollar symbol), like “{$93}” (clear screen).
{label}
Most of the common labels for PETSCII screen control characters, like “{HOME}”, and their abbreviations are supported. This should work naturally. Any spaces or dashes are ignored. See below for an extensive list.
{n label}
The emulator even “understands“ markup with leading quantifier, as in {4 SPACES} or {12 DOWN}, as may be found in some listings (but will never export them for compatibility reasons.) This works also with decimal or hexadecimal character codes.

(In case the emulator fails to parse an escaped character code or dosen’t recognize a label, it will simply ignore it.)

Labels for PETSCII Screen Control Characters

The PET 2001 uses fewer control characters than later machines, just 12 in total, of which onl 7 may appear in strings. Here they are are, together with a few extra characters and the labels that may be used for them (spaces, etc in names are ignored, as well as case):

  • Home (19, $13):
    HOME
    HOM
    HM
    CRSR HOME
    CHOME
    CH
  • Clear Screen (147, $93):
    CLEAR
    CLEAR SCREEN
    CLEAR SCR
    CLS
    CS
    CLEAR HOME
    CLR HOME
    CLRHM
    CLRH
    CLR
    CLH
    SC
  • Cursor Down (17, $11):
    DOWN
    CRSR DOWN
    CRSR DWN
    DWN
    DN
    CD
  • Cursor Up (145, $91):
    UP
    CRSR UP
    CU
  • Reverse On (18, $12):
    RVS ON
    RVS
    RV ON
    RON
  • Reverse Off (146, $92):
    RVS OFF
    RV OFF
    ROFF
    ROF
  • Insert (148, $94):
    INSERT
    INST
    INS
  • PI (255, $FF):
    PI
  • Stop (3, $03):
    STOP
    STP
  • Space (32, $20):
    SPACE
    SPC
    SP
    BLANK
    BL
  • As you may see, there’s an abbreviation for everyone and most of the common abbreviations will be recognized. Just use what ever you are used to or what’s in the type-in listing. (The emulator will use the very first label in each of the lists, when exporting a program using labels, see below. Spaces or π will never be replaced by markup in any of those exports, as these are printable characters.)

    Finally, there is also a special label “{ASM START}” (alternatively “{ASMSTART}” or “{ASM_START}”.) This will terminate the interpretation of BASIC source text immediately (with the rest of the line ignored) and inserts an ASCII string of the next memory address after the tokenized BASIC program. Any following source text is assumed to be 6502 assembler code. (In case no code is found, a simple 0x60RTS” instruction is appended.)
    This allows for a combined BASIC and assembler source, where you can transition from BASIC to machine language by “SYS {ASM START}” or to append this address to a final “DATA” statement to be read from BASIC and to be used as a call address anywhere inside the program.
    See the assembler documentation for details and examples.

    Installing Option ROMs

    Similarly to loading files, you may also install option ROMs or overwrite installed ROMs by dragging and dropping a binary ROM-image (with file extension “.bin” or “.rom”) or using the mount dialog.
    Only a single ROM image can be installed at once and you will have to provide either a start address (in hex) or a ROM socket designator (as in “Hn”, “Dn” or “UDn”).
    To install multiple ROM images, pause the emulator first to avoid any crashes.

    ROM addresses and sizes are normalized to multiples of 0x800 (2K).
    Common option ROM addresses are 0x9000 (D3, UD3, UD11) and 0xA000 (D4, UD4, UD11).

    Mind that you cannot replace the character ROM. Any installed ROMs are reset and lost, when changing the ROM configuration (using the ROM-menu).

    Note: Of the original PET 2001s, only the PET 2001N (the later model with the “real” keyboard) came with sockets for option ROMs (D3 and D4). So there will be no option ROMs for the orignal ROM 1.0 configuration and you’ll probably need ROM 4.0.

    Loading Programs from URL-Parameters

    The emulator will load any of the programs from the Program Library using special hot-links. For security reasons, this option is restricted to files in this specific server directory and will not work with external resources.

    Parameters are (either as a query string or as hash/fragment, separated by “&”:

    • prg=<filename>, also program=, load=, run=
      Will load a program or BASIC source files. Binary programs will be run automatically, use “run” spefically to auto-run a text file. If there’s no file extension supplied, “.prg” will be assumed.
      Files may be located in disk or tape archives, an individual file inside an archive may be specified using a slash (/) as a path separator. If no file name is found, a directory list dialog will be displayed.
    • disk=<filename>, also floppy=, d64=, d80=, d82=, dsk=
      Will load the specified disk archive and display a director list.
    • t64=<filename>
      As above for T64 tape archives.

    General URL-Parameters

    Generally, default options may be specified in URL parameters, as well.
    As above, parameters are (either as a query string or as hash/fragment, separated by “&”.

    • keyboard=<option>, also kbd=…, kbdmode=
      Configures the keyboard mode (key repeat). Valid options are “repeat”, “edit”, “editing” (key repeat on) and “norepeat”, “games”, “gaming” (key repeat off).
    • repeat=<option>
      As above, but uses a truthy value, like “yes”, “no”, “off”, “true”, “false”, “1” or “0” to set the option.
    • color=<option>, also clr=…, screen=
      Sets the screen color. Valid options are “white”, “green”, and “ink” or “e-ink”.
    • ram=<size-in-K>
      Sets the RAM size. Valid options are “8” (default), “16” and “32”.
    • rom=<version>
      Sets the ROM version. Valid options are “1”, “2” (default) and “4”, and “2b” or “4b” for the CBM 2001/B with the business keyboard.
    • charrom=<version>
      Sets the character ROM version. Valid options are “old” (default), “new” (or “1” “2”, respectively).
    • autorun=<option>
      Explicitely requests a program that may be loaded by an other parameter to be run automatically, regardless of the file type. Valid options are any truthy values (see repeat).
    • list=<option>
      Lists a program upon loading, only available for programs loaded from URL-data (see below). Valid options are any truthy values.
    • asbasic=<option>, also isbasic=…, basic=
      Explicitely requests a program that may be loaded from a a disk or tape archive (by an other parameter) to be loaded as a BASIC program (to the normal start of BASIC at $0401).
    • persistence=<option>
      Configures the rendering mode of the CRT emulation (see below), either “normal” (default) or “long” (also “hot”) for a more dramatic demo mode.
    • pixelaspect=<option>, also pixels=
      Sets the pixel aspect (see bleow) for the CRT emulation. Valid options are “square” (default) or “tall” (or “1.0” and “1.2”, respectively).
    • joystick=<option>, also joysticks=
      Configures the type of joystick adapter (see below).
      One of “simple”, “pet” (or “dual”), “stupidpettricks”, “chuck_johnson” (or “compute”), “galaga” (also “wening”), “scramble” (also “jentzen”), “snes” (also “texelec”), “keyboard”, “keyboard_shift”, “keyboard_space” or “ignore” (default).
      (There’s also support for “cga”, “c64dtv”, also “hummer”, and “vic20”, but I’ve never seen a PET program written for any these adapters.)

    Mind that this allows you to bookmark a preferred configuration, like using the link ?screen=white&ram=32 for a white screen and 32K of RAM.

    Programs as URL-Data

    Finally, you may load an entire BASIC source text using URL parameters. The source may be either encoded using X-WWW-Form-URL encoding (AKA form data) or as a base64 string. Again, this me be supplied either as a query string or in hash/fragement. All the above configuration parameters also apply and may be used in conjunction.

    • data=<data-string>
      The data in the data string will be extracted, transformed into a binary BASIC program to be loaded into the virtual PET, just as if it came from a disk.
      The data format is assumed to be normal URL-encoded form data, if no format is specified at the immediate start of the data string.
      If a prefix “base64:” or “data:<mime-type>;base64” is found the following stream will be interpreted as base64 encoded data. (Suitable MIME-types are, text/plain, text/basic, application/text, application/basic, or application/octet-stream.)
      A file name to be used and displayd for the load command may be supplied by a parameter “filename=<string>” or “name=<string>”.
    • execute=<data-string>, also exec=
      Same as above, however, the supplied data will be auto-typed into the virtual machine and executed in direct mode.

    E.g., for a simple hello-world example,
    ?data=10%20print%22hello%20world%22&autorun=true,
    or, using the hash/fragment,
    #data=10%20print%22hello%20world%22&autorun=true.
    (The difference is here, that a normal query string, strating with “?”, will be sent over the network, while a hash/fragment will be handled inside the browser only.)
    And here’s an example for executing a statement in direct mode,
    ?exec=print(100+20)*5.
    All the usual PETSCII escape may be used (see above), also “\pi” may be used to escape Pi (π), e.g.,
    ?exec=printsin(\pi/6)

    The “Utils/Export” menu (see below) includes an option to automatically generate a data URL for the BASIC program currently in memory.

    You may also use the Link Console to assemble a data-URL for the emulator.

    Utilities and Export Options

    The menu “Utils/Export” below the emulated screen provides a number of ways to export your work from the virtual machine or to interact with it in oder ways. This is also where the developer tools of the emulator live. As there are:

    Options to Export the Screen Contents

    • Screen Text As Unicode
      Transforms the screen contents into Unicode text and presents the result in a clipboard ready for copy & paste. Mind that there isn’t a suitable equivalent for every of the PETSCII graphics characters. The emulator will do its best to find a close representation.
    • Screen As Image
      Exports the current screen as a PNG-image, which will be presented in a dialog ready for copying, or downloading it by drag & drop or by right-clicking the image.
    • Screen As Image, No Margins
      The above option exports the screen image with a small amount of padding to include for phosphor bleed. Use this option to get a slightly smaller image, representing the screen contents as-is.
    • Printer Hard-Copy
      This transforms the screen contents to an image emulating the output of a dot matrix printer. As with real matrix printers, the result will not always be the same…
    • Screen Memory As Hex-Dump
      Exports the current contents of the video RAM (screen codes) as a hex-dump, ready for use in an assembler source.
    • Generate BASIC Program
      Generates a BASIC program to reproduce the current screen, ready to be reused in a program. Think Photoshop in BASIC. A dialog lets you chose line numbers, steps in line numbers, the character case of the generated BASIC source, and the kind of escapes to be used for PETSCII special characters. (You may chose from transforming those to CHR$() statements, which will work everywhere, or any of the special escapes used by the emulator, compare the section on PETSCII escapes above.

    Options to Export Memory Ranges

    • BASIC As Escaped Listing
      Generates a listing of the BASIC program currently in memory, ready for copy and paste. Any special PETSCII characters (as found in strings) are ascaped to labels and there are a few options of what kind of labels to use (decimal or hex, and whether or not to use any labeled escapes, like “{HOME}”, where applicable.)
    • BASIC As Portable Listing
      As above, but any PETSCII special characters are transformed to CHR$() sequences. This is the most compatible option and should work everywhere. However, mind that there’s a small chance that a line may exceed the maximum length and the source may require some manual editing, because of this.
      The “escaped listing” may be preferable for the purpose of external editing.
    • Hex-Dump Address Range
      Generates a hex dump of an arbitrary address range, including ROM code. (The IO range, however, will be skipped.)
    • Hex-Dump Program
      Generates a hex dump of the current program as defined by the system pointers (TXTTAB between VARTAB). This will be principally the BASIC program, but will also include any assembler code that may have been loaded together with it.
    • Disassemble Address Range
      Disassembles a given address range, including ROM code. The disassembly is context aware, as of screen or system memory (for which it provides a simple hex dump), tokenized BASIC text, BASIC variables, and 6502 machine code.
      (BASIC contents will be listed according to its tokenized format, variables are decoded with respect to their structure in memory. The format of 6502 disassembly is close to this of the original MOS 6502 assembler.)
    • Disassemble Program
      As above, but selects just the range of the program currently in memory based on the values in the system pointers.
      BASIC programs are disassembled to a meaningful structure, showing tokens and strings (split into lines of up to 6 characters). E.g., the well known program,
      10 PRINT CHR$(205.5+RND(1));:GOTO 10
      will disassemble to,
      0401  1B 04               link: $041B
      0403  0A 00               line# 10
      0405  99                  token PRINT
      0406  20                  ascii « »
      0407  C7                  token CHR$
      0408  28 32 30 35 2E 35   ascii «(205.5»
      040E  AA                  token +
      040F  BB                  token RND
      0410  28 31 29 29 3B 3A   ascii «(1));:»
      0416  89                  token GOTO
      0417  20 31 30            ascii « 10»
      041A  00                  -EOL-
      041B  00 00               -EOP- (link = null)
    • Disassemble Variables
      Provides a disassembly of BASIC variables as they are found in memory.
    • BASIC System Pointers
      Shows a dialog with the most important system pointers for BASIC memory partioning by label, address, current contents (the address they are pointing to), along with a short description of their meaning.
      May be useful for debugging.
    • Show BASIC Variable Dump
      Lists any variables as they are currently in memory. Unlike the disassembly, this view interprets and presents the variables as they would be printed from within BASIC.
      If you are more interested in states and values of your variables than in the storage format, this is the view for you.

    Other Utilities and Options

    • Export PRG-File From Memory
      Save the current program to your computer as a binary program file. This is essentially the same as entering “SAVE "FILENAME",8” in BASIC.
    • BASIC Program As URL
      This exports a Link, which will load the current BASIC program in memory as a source file. There are options to adjust the format and encoding type of the link. — Mail your ten-liner to your friends!
    • Renumber BASIC In Memory
      A renumber utility for BASIC. Enter start line number and step, the emulator will do the rest. This includes line numbers in statements like THEN, GOTO, GOSUB, ON … GOTO, and ON … GOSUB.
    • Switch Character Set
      Switch between the upper case / graphics set and the upper case / lower case set. A prompt will tell you, what action will be performed and what mode the emulated PET is in currently. (Also, it will tell you, what POKE statement would be used in BASIC for this.)

    Screen Options / Rendering

    The context menu of the virtual screen provides some helpful shortcuts for interacting with the contents of the emulated PET’s screen, but also some options to set the rendering mode of the emulated PET and for the emulation.

    Namely, these are

    • Color: Green / Color: White / Color: E-Ink (Inverted)
      A group of options to select the phosphor color for the CRT emulation. (PETs came both with green and white phosphor. “E-Ink” is a modern addition, showing an inverted dark-on-white display, which may be useful in certain cirumstances.) The current selection is marked by a checkmark.
    • Switch To <character set / case>
      This provides a convinient way to switch the character set used by the PET without resorting to akane POKEs.
    • Switch To (Old|New) Charater ROM
      Switches the character generator ROM as used by the PET between the original version with unshifted letters in upper-case and the newer version with unshifted letters in lower-case. This is only relevant together with the mixed-case character set, as the upper-case/graphics set is the same for both revisions.
    • “Hot” Rendering / Long Persistence | Render with Normal Persistence
      The emulator tries its best to provide a decent experience of a CRT without being too heavy on the resources and providing a suitable programming environment at the same time. However, the PET’s CRT had a relatively slow phosphor, which is addressed in a more dramatic “hot” rendering mode with a longer persistence, where the CRT is somewhat in overdrive. This may provide a desireable effect for demos, or for an experience more closely to watching the screen in a dark room, or similar.
    • Set Pixel Aspect Ratio To (1:1.2|1:1)
      Unlike modern computers, the PET had not square pixels, but elongated, tall pixels with an aspect ratio of 1:1.2. The results of rendering this on a modern display may vary, which is also why the emulator defaults to square pixels. With this you can set the rendering aspect to your personal pleasing.

    Copy & Paste

    The implementation of copy & paste may vary with browsers and their specific implementation of security related features.

    Copy & Paste via the Screen Context Menu

    The first two items of the context menu of the virtual screen expose copy and paste functionality:

    • Copy As Text
      This exports the contents of the screen as Unicode.
      If the browser supports clipboard interaction for this feature, the text will be immediately transferred to the system clipboard. Otherwise, a dialog similar to Utils/export > Screen Text As Unicode will be displayed.
    • Paste To PET
      If the clipboard feature is supported, this will directly transfer the content of the system clipboard as typed text to the PET. A browser may show an additional button (typically labeled “Paste” or similar) or a permissions dialog (to be acknowledged once) as a security feature to confirm the interaction. If the clipboard interaction is not directly supported by your browser (e.g., Mozilla Firefox or older browsers), selecting the context menu item will bring up a dialog with a text-area for pasting.

    Paste via System Commands

    If the browser supports the feature and there isn’t a pop-updialog active, pasting is also supported via the system “Paste” menu item and its associated shortcut. (Currently, this is supported by all major browsers, as Google Chrome, Mozilla Firefox, Apple Safariat, at least in the respective desktop versions.)

    Notes on Paste

    Mind that you may only paste to a PET that is interactive and ready to accept keyboard input, meaning, it must not be paused and there has to be an active cursor.

    Pasted text will be evaluated for case before it is transferred to the emulated PET and may contain the usual PETSCII-markup ({ddd}, {$hh}, {label}). To the PET it will appear the same as if the text had been typed in by the keyboard. Pasted text may stretch over multiple lines and may even encompass an entire program. If not present, a closing RETURN will be added to the text in order execute it.

    Tip: Paste may be used to supply multiple values to input statements of a program, one line per input statement, which may come handy for testing.
    E.g., pasting the following will enter a tiny program, run it, and will pass the values 4 and 5 to the executing program:

    10 PRINT "RECTANGLE"
    20 INPUT "SIDE A"; A
    30 INPUT "SIDE B"; B
    40 PRINT "AREA: "; A*B
    RUN
    4
    5

    However, mind that transferring a file per drag & drop is still the preferred and also quicker method of loading BASIC source texts.

    Joysticks & Joystick Adapters

    The emulator supports up to two joysticks or gamepads connected to your compter. In Games Mode with the CAPS LOCK key engaged, the emulator also emulated a joystick from keyboard input, using the cursor keys (arrow keys) for directions and the space bar for the fire button. (Use CAPS LOCK to toggle between normal keyboard input and joystick emulation for these keys. If a real game controller is found, the keyboard joystick acts as an additional (second) one.)

    Click the joystick icon to access the joystick settings and choose an adapter scheme matching your game (or ”ignore” to disable joystick input). There‘s also a quick access menu with the most important options available as a contextual menu of the joystick icon.

    While the PET doesn’t have a joystick port of its own, there was quite a variety of schemes for joystick adapters to connect one or even two joysticks to the user port of the PET. These ranged from connection schemes for two simple joysticks for just left, right, and fire, a single joystick using all four directions connected by varying wiring schemes, to two joysticks, where fire was encoded by triggering both left and right inputs at once.

    Beyond simple, Atari-style joysticks there is also support for the TexElec serial interface for a single SNES gamepad. Mind that browsers may handle gamepads with various success, which may be especially an issue with the full range of SNES buttons.

    Finally, there’s are options to reroute any joystick input to the keyboard, where directions translate to the numeric keypad (left: “4”, right: “6”, etc) and the fire button to either “A”, SHIFT, or SPACE. This works also with the emulated keyboard joystick, which may come handy, if your computer doesn’t feature a numeric keypad. (A small indicator below the joystick icon provides feedback for any rerouted keyboard activity.)

    Sadly, there’s no good way for the emulator to “know”, which kind of connection/wiring scheme might be expected by a particular program. Open the Joystick Settings by clicking the joystick icon next to the sound controls to select any of the supported adapter schemes.
    Generally, either ”SIMPLE” or ”PET” will be a good choice to start with.

    Adapters supporting two joysticks come with an additional option with player assignments swapped. (Browsers assign joysticks in the order they become active. If the player/joystick assigment is not as expected, just go to the dialog and choose the respective swapped option.)

    Joystick support is initially off (option ”ignore”), but it may have been set by a program link. You may always disable any joystick handling by choosing ”ignore”, thus prohibiting any interferences this may cause with a particular program. This will also disable the emulated keyboard joystick.

    Note on browser support and stability:
    I’ve one cheap, non-standard SNES-style gamepad that works fine with Firefox, but misassigns A,B,X,Y buttons on Safari. Chrome reports correct buttons for the same gamepad, but fails to read the left and right buttons. Moreover, directions for this gamepad are reported as analog axis on Safari, but (partly) as buttons on Chrome. An old Logitech gamepad works fine with Firefox and Chrome, but gives weird readings on Safari, where all buttons and all axes are triggered at once. Rather than delivering raw data, browsers seem to to apply some voodoo of their own behind the scenes, which may work out or not. Generally, Firefox seems to provide the best and most stable support.
    If you experience any problems, reconnecting your controller or restarting the browser may help.
    See also the joystick tests programs here.

    Note on “Cosmiads Uni”:
    There’s a version of “Cosmic Cosmiads MK01” (Cosmiads Uni) with support a for joystick via PA0, PA1 & PA5 (here, the “SIMPLE” adapter scheme) added. Mind that this requires a POKE 2571,79 before running the program.

    Assembler and 6502 Machine Code

    The emulator features a buil-in 6502 assembler and disassembler. For these, please refer to the separate Assembler Help page.

    Mind that the PET features its own machine monitor in ROM (with the exception of ROM 1). The interrupt vector points to this monitor and executing an instruction of binary zero (0x00, “BRK”) will summon it to your order. From BASIC, this can be accomplished by jumping with “SYS” to any location containing a zero-byte.
    One should be always found at 0x400 (just before the start of any BASIC text) and can be called by the memorable command “SYS 1024”.

    PET Manuals, Trivia, Etc

    PET 2001 Manuals

    For more information on PET 2001 operations, you may download some essential references directly from this site:

    Further manuals and references can be found at www.zimmers.net/anonftp/pub/cbm/manuals/pet/ and www.commodore.ca/commodore-manuals/.

    Trivia — Sound on the PET

    An important thing to note about sound on the PET 2001 is that the PET has none, nada, niente, pas de son, du tout.

    However, it was soon discovered that the PET features a 6522 VIA chip for communications with two serial shift registers, which may be put under timer control. Purposefully, the outputs of these are routed to ports at the back of the PET. One of these registers can shift the bits out repetitively at a fixed interval that may be set by a timer. Which, if you think about it, can produce a series of pulses at a frequency of up to 1MHz, the PETs clock speed. In other words, we can produce sound by configuring a series of on/off (high/low) signal pulses and by this sample audio. (Which really matters, which is is audible, is not a specific state of the signal, but the transition between states.)
    All it needs now is to hook up a speaker to this pin by a resistor and connect this on the other side to the ground level of the computer (maybe adding a capacitor, as well) and, bang!, we have sound. As the pin, at which this signal is available, is called “CB2”, this is also known as “CB2 sound”.

    emulated hard copy of a screen of the Space Invaders for the PET
    The famous sound instructions from Space Invaders for the PET.

    While this is capable of producing quite a variety of timbres, the spectrum is rather limited, especially, when it comes to low frequencies. For decades, rich bass sound has been out of reach for the PET. That is, until lately. In 2021 ”shiru8bit” published his CB2 music album Faulty Robots, which is also available in the ‘Demo’ section of the Program Library, and in his 2022 demo “Back To The PET” (also availble in the Program Library). These two programs really redefined what is possible with sound on the PET! (Technically, this is about using additionally a second mode, which puts the CB2 output under “manual control” and some nifty interrupt management.)

    Speaking of demos, don’t miss “A Bright Shining Star”, presented by Genesis Project, also in 2022. This redefined graphics on the PET, just like Shiru had done it with music. (Be assured, the PET still has character graphics only. But, when the PET goes ”racing the beam”, things previously unknown become possible.)

    — It may be (proudly) mentioned that this emulator is currently the only one that can run these programs out of the box. :-)

    Known Issues / Missing Features

    • The IEE emulation only supports basic LOAD and SAVE for files. There is currently no support for OPEN and CLOSE, or for programs that load additional data files using these commands.
    • Disk images are read-only. Meaning, you cannot save to them, only to your local computer.
    • There is no support for cassettes. T64 tape archives may be accessed as emulated floppy disks, though.

    Things not supported, but maybe nice to have

    • IEEE support for OPEN and CLOSE.

    Let’s see…