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

There are two major methods of input, the real keyboard on your computer and the virtual keyboard of the emulator.

Computer Keyboard

Support of real keyboards is set up so that you may type as natural as possible. Special characters are generally what they are on your keyboard. E.g., the double quote is still how you type it normally, probably a shifted key, while it is no a shifted key on the PET 2001. Hitting a normal letter key will produce this letter as normal, even if it appears in upper case on the PET. Shifted variants of PET characters are available for all of the alphabetic characters, allowing you to enter the common Commodore BASIC abbreviations naturally as on a real PET. However, shifted variants are probably not available in combination with special characters or punctuations. In this case, please resort to the virtual keyboard (see below). The shift key on your keyboard will still work with the virtual keyboard, so you may shift-click a key on the virtual keyboard to access a graphics character.

The emulator works best with a full-size keyboard featuring a numeric keypad, which generally mirrors the layout of the PET 2001’s chicklet keyboard. This is especially true for games, which freequently make use of the numeric keypad for directional input. Cursor keys and editing keys, like HOME, DEL, etc, are supported as well and mapped to their PET equivalent, including left and right shift keys. In order to mirror the PET 2001 keyboard layout even closer, the ENTER key on the numeric keypad is mapped to “=” and the decimal key is always mapped to a dot (“.”), even if it is a comma on your particular keyboard.

However, not all PETSCII characters have a direct equivalenant on modern keyboards. Therefore, a few special mappings are used:

STOP
is mapped to ESC.
↑
is mapped to the caret (“^”) and to TAB, as well,
SHIFT+TAB to Pi (π).
←
is mapped to the underscore (“_”) and to ALT+TAB,
ALT+SHIFT+TAB is mapped to “◥”
RVS
is mapped to “®”, which should be ALT+R on most keyboards.
The shifted variant, “RVS OFF“ should be also available by holding the SHIFT key.
(May be subject to the type of keyboard used.)

Additionally to this, ALT + ESC pauses or respectively resumes the emulation.
Please mind that with joystick support enabled and CPAS LOCK engaged, the cursor (arrow) keys and the space bar will be used for joystick emulation (see below) and wont work for normal keyboard input. Use CAPS LOCK to select input modes for these keys. Set the joystick adapter to “ignore” to disable this behavior.

The Virtual Keyboard

The virtual keyboard, depicted below the emulated screen, is ideal for touch screens and also complements the real keyboard for the input of graphics characters. Simply tap or click a key on the keyboard image (visual feedbak is provided). To input a shifted character, first click/tap one of the two SHIFT keys and then click/tap the actual key. If you have a real keyboard, shift-clicking a key will work as well.

Mind that for touch devices, when the keyboard is in “Games” mode (see below), SHIFT will be sent directly to the emulated PET, as some games require this for input (and games won’t operate on shifted keys, anyway.) In this case, SHIFT keys will work only as multi-touch action together with another key pressed. If SHIFT apparently stopped working, check the keybaord mode.

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.

Keyboard Modes

The PET 2001 doesn’t feature key repeat out of the box. To the opposite, its operating system actively inhibits it. In order to facilitate natural keyboard input and fluent cursor movements, the emulator adds its own key repeat functionality. However, this usually isn’t best for games, which often implement a keyboard repeat of their own. Games will also benefit from the more immediate reaction of the unmodified keyboard input. Therefore, the emulator features a special menu to switch between “Editing” (virtual key repeat on) and “Games” (virtual key repeat off) modes. This menu is found, like all other emulator controls, directly below the virtual screen.

On touch devices, when in “Games” mode, SHIFT is sent directly as a keystroke to the virtual PET and works only with multi-touch, pressing SHIFT and another key at once.
To avert any confusions, the keyboard will always be set to “Editing” when pressing the “Reset” button.

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. 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
Choose between “ROM2”, also known as “new ROM”, the most common configuration, and “ROM1”, the version the very first PET 2001s came with, or the later “ROM4”, which was available as an upgrade.
Most of the early PETs, which came with the early revision of the ROM, were upgraded to the new ROM, since the original one had a few quirks (especially with disks) and was missing some functionalty, like the built-in monitor.
Generally, ROM2 will be the best option and is also the default. However, some old programs require ROM1.
ROM4 is mostly compatible with ROM2, but has a modified screen editor and comes with a set of buil-in disk commands. Otherwise, it is practically identical to ROM2, as it uses the same zero page addresses and memory layout. (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.) Chosing ROM4 will also activate the new character ROM with unshifted lower-case characters.
Changing the ROM version will reset the virtual machine.
(Mind that ROM2 is also known as ROM3. 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.
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 ROM4.
    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.
  • 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 common Unicode substitutes for PETSCII characters (including the new legacy computing range), not all 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 0x60 “RTS” 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.

    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” and “green”.
    • 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”.
    • 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).
    • 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”, “galaga”, “snes” (also “texelec”), “keyboard”, “keyboard_shift” 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

    • Switch Screen Color: (Green|White)
      Switches to the phosphor color for the CRT emulation. (PETs came both with green and white phosphor.)
    • 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. 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.)

    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 an option 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 “A”. And yet another one, where the fire button is mapped to SHIFT, just to have them most frequent used input schemes covered. This works also with the emulated keyboard joystick, which may come handy, if your computer doesn’t feature a numeric keypad.

    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 ROM1). 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…