Writing an output character is done from right to left (bit #0 first, then #1..#7), as follows:

Flag on
r5 = r0;
DLAY();
DLAY();
Flag off
for (r4 = 8; r4 > 0; r4--)
{ DLAY();
  r5 >>= 1;
  if (r5 & %10000000)
  { Flag on
  } else
  { Flag off
} }
DLAY();
Flag on

CHIN returns with an input character in R0, but not until there is input (ie. it is synchronous). The high bit is used for parity and is always masked out by CHIN; therefore, only 7-bit input is supported. (Ie. the extended ASCII set values $80..$FF are unsupported.)
The Sense bit is normally high. It pulses low during key transmission (ie. whilst receiving clear bits of a byte). Waiting for the Sense bit to become clear is therefore equivalent to "press any key to continue".
Randomization is normally done by asking the user for a keystroke, then rapidly incrementing a register while waiting for the Sense bit to become clear. Eg.

printf("PRESS ANY KEY");
HERE:
addi,r1 1
tpsu    $80
bctr,eq HERE ;if Sense bit is set

will generate a random number (0..255) in r1.
There is also an optional 4-digit 7-segment LED display which can be attached to the system as an additional output device. Writing to this is done via the WRTD command. The operand is interpreted as follows:

bit 7: 1st digit
bit 6: 2nd digit
bit 5: 3rd digit
bit 4: 4th digit
bits 3..0: digit ($0..$9 = '0'..'9', $A..$F = ' ')

Eg. to write '7' to the 3rd digit would require an operand of $27. A delay is necessary between digit writes on the real machine, but not on the emulator. See the relevant magazine article for more information.

CHIN is used for cassette/papertape/keyboard. It works like this:

do
{ switch to alternate register bank
  PORTC = $80; // enable tape reader
} while (Sense bit is set); // ie. until start of start bit
PORTC = 0; // disable tape reader
DLY(); // wait for half a bit (ie. until centre of start bit)
r4 = 0;
for (r5 = 8; r5 > 0; r5--)
{ DLAY(); // wait for one bit
  r0 = PSU & %10000000;
  r4 <<= 1;
  r0 |= r4;
  r4 = r0;
}
DLAY();
r4 &= %01111111; // delete parity bit
r0 = r4;
switch to main register bank
clear With Carry flag
return;

So it is expecting the following format:

.01234567#

and it returns in the middle of the stop bit (#).
So, we enable the tape reader, wait for the Sense bit to become clear, and then disable the tape reader. Then, we read the eight bits from right to left (bits 0..7) via direct sampling of the PSU at the appropriate moment. The parity bit (bit 7) is then discarded (without checking it).

COUT is used for cassette/papertape/keyboard. r0 is passed as an argument; it is the ASCII character to be output. It works like this:

set Flag bit
r5 = r0;
DLAY();
DLAY();
clear Flag bit
for (r4 = 8; r4 > 0; r4--)
{ DLAY();
  r5 >>= 1;
  if (r5 & %10000000 == %10000000)
  { set Flag bit
  } else
  { clear Flag bit
} }
DLAY();
set Flag bit
return;

So, we set the Flag bit, wait, and clear the Flag bit. Then, we write the eight bits from left to right (bits 0..7). The high bit is not treated any differently to the others. Then we wait again, set the Flag bit and return.
Effectively, we write this for each byte:

##.01234567

where # means Flag set, . means Flag clear, and digits mean Flag is set/ cleared according to the relevant bit. We set the Flag before returning.

When loading, it waits until the input line goes low, then looks for the start character (':').

Some games have 110 baud and 300 baud versions. These are still all stored on cassette at 110 baud; the baud rate in this case actually refers to the speed of keyboard and screen operations, rather than cassette speed.

Hardware equates/memory map

Various memory configurations are possible. Here are some examples, but this is not exhaustive:

Region	Size	EA 77up2 ("Baby")	ABC/PC1500/KT9500	EA 78up5 or PC1001	EA 78up5 + 78up10	Modified ABC1500 with CP1002
$0000..$03FF	1K	PIPBUG 1 monitor ROM	PIPBUG 1 monitor ROM	PIPBUG 1 monitor ROM	PIPBUG 1 monitor ROM	PIPBUG 2 monitor ROM
$0400..$0436	55 bytes	RAM for PIPBUG 1	RAM for PIPBUG 1	RAM for PIPBUG 1	RAM for PIPBUG 1	PIPLA
$0437..$04FF	201 bytes	user RAM	user RAM	user RAM	user RAM	PIPLA
$0500..$05FF	256 bytes	mirror of $0400..$04FF	user RAM	user RAM	user RAM	PIPLA
$0600..$07FF	512 bytes	mirrors of $0400..$04FF	mirror of $0400..$05FF	user RAM	user RAM	PIPLA
$0800..$0861	98 bytes	mirror of $0000..$0061	mirror of $0000..$0061	user RAM on 4K version	user RAM	SMI RAM used by PIPBUG 2 + PIPLA
$0862..$087F	30 bytes	mirror of $0062..$007F	mirror of $0062..$007F	user RAM on 4K version	user RAM	SMI RAM unused by PIPBUG 2 + PIPLA
$0880..$0BFF	896 bytes	mirror of $0080..$03FF	mirror of $0080..$03FF	user RAM on 4K version	user RAM	unused
$0C00..$0DFF	512 bytes	mirror of $0400..$05FF	mirror of $0400..$05FF	user RAM on 4K version	user RAM	motherboard RAM
$0E00..$0FFF	512 bytes	mirror of $0600..$07FF	mirror of $0600..$07FF	user RAM on 4K version	user RAM	optional RAM
$1000..$13FF	1K	mirror of $0000..$03FF	mirror of $0000..$03FF	user RAM on 4K version	user RAM	unmapped?
$1400..$1EFF	2.75K	mirror of $0400..$0EFF	mirror of $0400..$0EFF	unused?	user RAM	unmapped?
$1F00..$1FFF	256 bytes	mirror of $0F00..$0FFF	mirror of $0F00..$0FFF	unused?	user RAM	mirror of $0F00..$0FFF
$2000..$2FF9	4090 bytes	mirror of $0000..$0FF9	mirror of $0000..$0FF9	unused?	user RAM	unmapped?
$2FFA..$2FFF	6 bytes	mirror of $0FFA..$0FFF	mirror of $0FFA..$0FFF	unused?	RAM (for use by EPROM)	unmapped?
$3000..$3FFF	4K	mirror of $0000..$0FFF	mirror of $0000..$0FFF	unused?	EPROM	unmapped?
$4000..$41FF	512 bytes	mirror of $0000..$01FF	mirror of $0000..$01FF	unused?	ROM? (for eg. ETI-686)	unmapped?
$4200..$57FF	5.5K	mirrors of $0000..$0FFF	mirrors of $0000..$0FFF	unused?	RAM (for eg. ETI-686?)	unmapped?
$5800..$7CFF	5.25K	mirrors of $0000..$0FFF	mirrors of $0000..$0FFF	unused?	RAM (for eg. ETI-686?)	unmapped?
$6D00..$7FFF	4.75K	mirrors of $0000..$0FFF	mirrors of $0000..$0FFF	unused?	RAM? (eg. for Linearisatie)	unmapped?

EA 77up2 ("Baby"): 1K ROM + 256 bytes RAM
Signetics Adaptable Board Computer aka Signetics PC1500 aka Signetics KT9500: 1K ROM + 512 bytes RAM
EA 78up5 ("1K Mini Computer" aka "2650 Mini Computer") or Signetics PC1001: 1K ROM + 1K RAM
EA 78up5+78up10 ("Expanded Mini Computer with EPROM"): 1K ROM + 15.75K RAM + 4K EPROM
Modified ABC1500 with CP1002 (see TN132): 2K ROM + 1152 bytes RAM

The ABC also supports parallel and serial I/O, has an on-board clock, and can be expanded to up to 24K of RAM. These features are not supported by Ami/WinPIPBUG, as the mappings of the serial and parallel I/O ports and clock are unknown.
The Signetics PC1001 Microprocessor Prototyping Card (1K RAM) (assembled) is a different, though closely related, machine.
The Signetics PC2000 is a 4K expansion RAM board suitable for (at least) the PC1001/PC1500/KT9500.
The Signetics PC3000 is another "evaluation kit" (as are the other Signetics-manufactured machines), about which almost nothing is known.

While using PIPBUG 1 "A" and "S" commands, valid inputs are:

<CR> (ie. ENTER) to exit
<LF> (ie. Ctrl+J) to display the next address/register
<nn><CR> to change contents address/register to <nn> and exit
<nn><LF> (ie. type the value then press Ctrl+J) to change contents of address/register to <nn> and display the next address/register.

PIPBUG 1 ROM areas are as follows:

$000..$01C: initialization
$01D..$05A: command handler
$05B..$0A3: input a cmd line into buffer
$0A4..$0AA: subr that stores double precision into temp
$0AB..$0F3: display and alter memory
$0F4..$139: selectively display and alter registers
$13A..$15F: goto address
$160..$1AA: breakpoint runtime code
$1AB..$1C9: subr to clear a bkpt
$1CA..$223: break point
$224..$23C: input two hex chars and form as byte in R1
$23D..$245: calculate the BCC char, EOR and then rotate left
$246..$24F: lookup ASCII char in hex value table
$250..$268: abort exit from any level of subr
$269..$285: byte in R1 output in hex
$286..$2A7: 110 baud input for papertape and char 1 MHz clock
$2A8..$2B3: delay for one bit time
$2B4..$2D4: COUT (Character OUT) routine
$2D5..$30F: get a number from the buffer into R1-R2
$310..$35A: dump to paper tape in object format
$35B..$3B4: subrs for outputting blanks
$3B5..$3FD: load from papertape in object format
$3FE..$3FF: unused?

Note that that PIPBUG, and programs for it, generally run with signed (arithmetic) comparisons, as opposed to the Arcadia, etc. which generally run with unsigned (logical) comparisons.

COUT has the following side effects when called:
PSL: CC = lt;
PSL: primary register bank (r1..r3) is always selected
PSU: Flag pin is always set
r0 = r4 = 0;
r5 = the old r0 (ie. what you passed)
You should not call it when SP > 5 (you need one level of stack for COUT's return address and another level for DLAY's return address).

CHIN has the following side effects when called:
PSL: CC = gt;
PSL: primary register bank (r1..r3) is always selected
PSL: With Carry bit is always set
r0 = r4 = return code (1..127)
r5 = *(DATABUS) = 0;
You should not call it when SP > 5 (you need one level of stack for CHIN's return address and another level for DLAY's/DLY's return address).

Utility EPROM areas are as follows:

Region	Label	Area	Type
$2FFA..$2FFB	START	RAM	data (1st CLI parameter)
$2FFC..$2FFD	END	RAM	data (2nd CLI parameter)
$2FFE..$2FFE	NEW	RAM	data (3rd CLI parameter)
$3C07	GPAR	EPROM	subroutine
$3C2A	INCRT	EPROM	subroutine
$3C3C	PADR	EPROM	subroutine
$3C50	HEXLIST	EPROM	subroutine
$3C6A	SEARCH	EPROM	subroutine
$3C8A	HEXIN	EPROM	subroutine
$3CDD	VERIFY	EPROM	subroutine
$3CF8	OK	EPROM	code section
$3CCB	?	EPROM	subroutine
$3CCE	?	EPROM	subroutine
$3D0E	FAULTY	EPROM	code section
$3D3B	MOVE	EPROM	subroutine

Some useful Ctrl-codes are:

Ctrl+G = BEL (7)
Ctrl+H = BS (8)
Ctrl+I = TAB (9)
Ctrl+J = LF (10)
Ctrl+M = CR (13)

Teletype I/O

At 1MHz, there are 1,000,000 short/fast cycles per second, which is 333,333.3' long/slow cycles per second. So each long/slow cycle lasts for 1,000,000÷333,333.3' = 3 µsecs.

At 110 baud, each bit ideally lasts for 9090.90' µsecs.
At 300 baud, each bit ideally lasts for 3333.3' µsecs.
At 1200 baud, each bit ideally lasts for 833.3' µsecs.

For a 110 baud teletype, a full bit delay is:
    bsta,un TDLA  ;3
TDLA:
    eorz    r0    ;2
    bdrr,r0 $ ;256*3
    bdrr,r0 $ ;256*3
TDLY:
    bdrr,r0 $ ;256*3
    lodi,r0 229   ;2
    bdrr,r0 $ ;229*3
    retc,un       ;3
= 3001 long/slow cycles = 9003 µsecs

and a half bit delay is:
    bsta,un TDLY  ;3
TDLY:
    bdrr,r0 $ ;256*3
    lodi,r0 229   ;2
    bdrr,r0 $ ;229*3
    retc,un       ;3
= 1463 long/slow cycles = 4389 µsecs

For a 1200 baud RS-232 terminal, a full bit delay is:
    bsta,un DLAY  ;3
DLAY:
    lodi,r0 89    ;2
DL1:
    bdrr,r0 DL1   ;3
    retc,un       ;3
3+2+(3*89)+3 = 275 long/slow cycles = 825 µsecs

and a half bit delay is:
    bsta,un DLY   ;3
DLY:
    lodi,r0 58    ;2
    bctr,un DL1   ;2
DL1:
    bdrr,r0 DL1   ;3
    retc,un       ;3
3+2+2+(3*58)+3 = 184 long/slow cycle s = 552 µsecs

Note that these delays are shorter than the ideals. However, there is also code that must be run by the caller to process (emit/receive) each bit, which takes additional time to run.

Each character begins with a start bit (%0). Then data bits 0..6 are sent (least significant bits first). Then a parity bit is sent. Then stop bits are sent.
The letter "U" has the 7-bit ASCII code of $55 (%1010101). This would be transmitted as %0,1010101,1,00.

Cassette I/O

A clear (0) bit (Sense bit off) is represented by a slowly pulsing signal. About 10 slowly pulsing cycles represents a clear bit.
A set (1) bit (Sense bit on) is represented by a quickly pulsing signal. About 20 quickly pulsing cycles represents a set bit.

The length of each bit, in time, is identical regardless of its value. (This is in contrast to the system used on the Elektor, which has identical pulses for all values and differentiates values by the positioning of the pulses.)

PIPBUG 1 encodes/decodes the files as Signetics Absolute Object Format (AOF) at 110 baud. There is a low start bit preceding each byte, and two high stop bits following each byte. The parity bit (bit 7 of the data) is always thrown away when reading. The data rate is approximately 10 raw data bytes per second. As values are encoded into ASCII pairs, the actual number of bytes loaded/saved per second from the user's point of view is about 5.

PIPBUG, BINBUG (except ACOS), CD2650 and (presumably) Selbstbaucomputer use a standard Kansas City Computer Users Tape Standard (CUTS) cassette interface to transform standard teletype I/O into cassette tape I/O (ie. high and low bits are turned into the appropriate pulse trains when recording, and pulse trains are analyzed and decoded into high and low bits during playback), usually at 110 baud:

Every "0" bit becomes 21.81' cycles (pulses) of a 2400 Hz tone, and
Every "1" bit becomes 10.90' cycles (pulses) of a 1200 Hz tone.

In practice, exactly 22 or 11 pulses should be done (as it is best to wait until the next zero crossing before doing the next bit).
The BIOS and games only see the teletype Sense and Flag lines, they cannot see the pulse trains. The cassette interface is invisible to the software; as far as it knows there is only an ordinary teletype attached. This means that you can record/play any sort of teletype I/O directly to/ from the tape, not just formal dumps.
300 baud is identical to 110 baud except that only 8 (instead of 22) or 4 (instead of 11) pulses are done; the pulses themselves are identical.

To load a tape, translate it to teletype format:

22 2400 Hz pulses in 9.09' msec = having teletype Sense low for 9.09' msec ("0").
11 1200 Hz pulses in 9.09' msec = having teletype Sense high for 9.09' msec ("1").
If we see a zero crossing every 413.2231 µsec it is a "0", and we should see 22 of those (or more if there are several 0 bits).
If we see a zero crossing every 826.4463 µsec it is a "1", and we should see 11 of those (or more if there are several 1 bits).

and vice versa when saving:

While teletype Sense is 0, flip the tape Sense every 413.2231 ÷ 2 µsec.
While teletype Sense is 1, flip the tape Sense every 826.4463 ÷ 2 µsec.

This is sufficient for all baud rates and encodings.

Here are diagrammatic views of the system, in record mode:

At computer		Tape		Terminal (VDU/keyboard)
Flag	->	tape can save this	->	VDU
Sense	<-	input comes from kybd	<-	Keyboard

and in playback mode:

At computer		Tape		Terminal (VDU/keyboard)
Flag	->	tape ignores this	->	VDU
Sense	<-	input comes from tape		Neither

Printer I/O

EA printer interface:
Uses the data port for (parallel) input and output.
Does not use buffering.
Can accept a new character every 64th of a second (in condensed mode) or every 32nd of a second (in expanded mode).
As soon as the game writes to the data port, it prints the character.
While printing is in progress, the high bit of the input data port is low. It is high while idle.

ETI-641 printer interface:
Uses extended port $19 (25) for (parallel) input and output.
Uses an internal 128-byte buffer.
Can accept a new character every 200,000th of a second (5 µsecs).
Once the internal buffer fills, or a CR is received by the printer, it prints (and empties) the entire buffer.
While printing is in progress, the high bit of the input extended port $19 (25) is low. It is high while idle.

To convert from ASCII to EUY format:

output =  (input & 0x1F)
       | ((input & 0x60) << 1);
output = ^output;

ASCII	EUY
$00..$1F	$00..$1F
$20..$3F	$40..$5F
$40..$5F	$80..$9F
$60..$7F	$C0..$DF
$80..$9F	$00..$1F
$A0..$BF	$40..$5F
$C0..$DF	$80..$9F
$E0..$FF	$C0..$DF

Eg. 'A' would be $41 in ASCII format or $81 in EUY format.
The above table is before the one's complement (ie. flip all bits) operation.

Matsushita EUY-10E023LE printer model number can be decomposed as follows:

E = Electrosensitive
2 = 250mm flat cable, 372mm connector cable
3 = 32/21/16 cpl with 2 spacing dots (horizontally between each character)
L = left-to-right scanning, MSD character generator
E = manufacturer code

Unarchived Software

The following are confirmed but unavailable:

C-BUG, MultiBug, MATBUG, SBCBUG, etc.
"the program supplied with the PROM Programmer article (Jan 1979)" (what article? which magazine?).

If you know of any other software, or have dumps/tapes/listings of any of the above software, please email us.

BINBUG Hardware

The FPGA640 + TCT PCG are mapped as follows:

Region	Description
$7000..$700F	1st..16th rows of UDG #0 imagery
$7010..$701F	1st..16th rows of UDG #1 imagery
...	...
$77F0..$77FF	1st..16th rows of UDG #127 imagery
$7800..$783F	Contents and inverse video of 1st character row (1st..64th columns): Bit 7: inverse video (0=off, 1=on) Bits 6..0: character ($00..$7F)
$7840..$787F	Contents and inverse video of 2nd character row (1st..64th columns)
...	...
$7BC0..$7BFF	Contents and inverse video of 16th character row (1st..64th columns)
$7C00..$7C3F	Colours and attributes of 1st character row (1st..64th columns): Bit 7: red (0=off, 1=on) Bit 6: green (0=off, 1=on) Bit 5: blue (0=off, 1=on) Bits 4..3: unused Bit 2: 0=PDG (Pre-Defined Graphic), 1=UDG (User-Defined Graphic) Bit 1: graphics (0=off, 1=on) Bit 0: flash (0=off, 1=on)
$7C40..$7C7F	Colours and attributes of 2nd character row (1st..64th columns)
...	...
$7FC0..$7FFF	Colours and attributes of 16th character row (1st..64th columns)

To read the joystick buttons, you REDE from port $09. Bits are:

Bits 7..6: unused
Bits 5..3: switch bits for joystick A:
 Switch '1' = %000 (fire/serve)
 Switch '2' = %001
 Switch '3' = %010
 Switch '4' = %011
 Switch '5' = %100
 Switch '6' = %101
 Switch '7' = %110
 Nothing    = %111
Bits 2..0: switch bits for joystick B (same format as for joystick A)

To read the joystick paddles, first WRTE a value of $00..$07 to port $EF, according to what you want to read:

Channel '1' (%000): 2nd joystick horizontal
Channel '2' (%001): 2nd joystick vertical
Channel '3' (%010): 1st joystick horizontal
Channel '4' (%011): 1st joystick vertical
Channel '5' (%100): 3rd joystick horizontal
Channel '6' (%101): 3rd joystick vertical
Channel '7' (%110): 4th joystick horizontal
Channel '8' (%111): 4th joystick vertical

Now REDE from port $EF in a loop until the MSB is low (ie. until something in the $00..$7F range is returned).
The X-axis is inverted, ie. $00=right..$7F=left.
The Y-axis is normal, ie. $00=up..$7F=down.

BINBUG BIOS

The following routines are cross-compatible between PIPBUG 1 and BINBUG:

Address	Label
$1D	EBUG
$5B	LINE
$8A	CRLF
$A4	STRT
$269	BOUT
$27D	AGAP
$286	CHIN
$2B4	COUT
$2DB	GNUM

The following routines have the same names, and roughly equivalent functionality, under both PIPBUG 1 and BINBUG; however, they have different addresses and therefore are not directly cross-compatible. They may also have different register usage, stack usage, side effects, etc.:

PIPBUG 1	BINBUG	Label
$1F	$22	MBUG
$AB	$B9	ALTE
$F4	$F1	SREG
$131	$121	GOTO
$160	$14A	BK01
$1AB	$17B	CLBK
$1CA	$197	CLR
$1E5	$1A1	BKPT
$246	$28C	LKUP
$2A8	$39B	DLAY
$2AD	$39F	DLY
$310	$2E5	DUMP
$35B	$27B	FORM
$35F	$2FB	GAP
$3B5	$3C4	LOAD

Here is a useful table comparing various BIOSes for these machines. As there is insufficient information regarding C-BUG, SBCBUG, etc. they are not listed:

OS	Input baud	Output baud	Tape baud	MHz	Range	Year	Notes
PIPBUG 1	110	110	110	1	$0..$3FF	?	EA 300 baud mod is possible
PIPBUG 2	110/300	110/300	110/300?	1	$0..$3FF	?	Supports both rates
HYBUG	300	300	High-speed	1	?	?	600 and 1200 baud mods are possible
BINBUG 3.5	300/parallel?	DG640	300?	1?	$0..$7FF	?	-
BINBUG 3.6	300/parallel?	DG640	300	1	$0..$7FF	1979	BINBUG3.6.pdf
BINBUG 4.4	300	DG640	ACOS	1?	$0..$7FF	?	Supports ACOS and DOS
BINBUG 4.5	?	DG640	ACOS	1?	$0..$7FF	?	Supports ACOS and DOS
BINBUG 5.2	1200	1200	ACOS	1?	$0..$7FF	?	Supports ACOS and DOS
BINBUG 5.3	?	serial	ACOS	?	$0..$7FF	?	-
BINBUG 6.0	Eurocard	Eurocard	ACOS	?	$0..$7FF	?	-
BINBUG 6.1	150?/300/1200/2400/parallel	DG640	ACOS	?	$0..$7FF	1982	sbcos_manual.pdf . Supports ACOS and VHSDOS
BINBUG 7.1	300/1200/2400/parallel	300/1200/2400	ACOS	?	$0..$7FF	1982	sbcos_manual.pdf . Supports ACOS and VHSDOS
GBUG	300	DG640	?	1/2	$0..$7FF	?	Optional parallel keyboard support
MATBUG 4.1	Eurocard	DG640	?	?	$0..$7FF	?	matbug_monitor_for_eurocard_system_notes.pdf
MIKEBUG 3	300	DG640	?	1?	$0..$7FF	?	-
Multibug (serial version)	300	300	300	?	$0..$7FF	1981	ETI-685
Multibug (memory-mapped version)	parallel	DG640	300	?	$0..$7FF	1981	ETI-685
MYBUG	300	DG640	?	1?	$0..$7FF	?	-
ACOS 2.C	-	-	Control & data I/O ports	1?	$6000..$63FF	?	-
ACOS 3.C	-	-	Extended I/O ports?	1?	$6000..$63FF	?	-
ACOS 3.E	-	-	Extended I/O ports	1	$6000..$63FF	1982	sbcos_manual.pdf
VHSDOS 2.6a	-	-	-	1?	$6800..$6FFF	1981	vhs_dos_v26a_source_listing.pdf
MicroDOS 4.5a	-	-	-	1?	$6800..$6FFF	?	MICRODOS.SRC

Baud rates given assume 1 MHz operation (and are therefore doubled at 2 MHz).

BINBUG outputs both to the serial port (at 300 baud) and to the VDU (1K RAM at $7800..$7FFF).
According to ETI Oct 1982, BINBUG can work at 300, 1200 & 2400 baud (!).
SBCOS = SBCBUG = BINBUG 6.1 + BINBUG 7.1 + ACOS 3.E
BINBUG 6.1 & 7.1 support/expect ETI-685 processor board.

Floppy Disk I/O

Each block is 256 bytes, as follows:

     0: next track (0..39).
     1: next sector (1..10).
2..255: data bytes

CMD files are used by VHSDOS and MicroDOS for storage of games. They normally consist of two or more chunks concatenated together. Each chunk has a 3-byte header:

  0..1: load address of chunk (big-endian)
     2: length of payload in bytes (normally <= $FB)

then the payload itself (if any) follows.
The CMD file is terminated by a chunk like this:

  0..1: start address of game (big-endian)
     2: $00

with no payload.
CMD chunks can seamlessly cross block boundaries.
Note that the above assumes that the block header (ie. "next track" and "next sector" bytes) have already been skipped.

The 10 sectors per track are numbered 1..10 and have an interleave of 7, ie. 1, 8, 5, 2, 9, 6, 3, 10, 7, 4. (The available disk images are already deinterleaved.)
At the flux level, there are 250,000 flux transitions per second.
Each bit is 1 clock flux + 1 data flux, so there are 125,000 bits per sec.
So theoretically 15,625 bytes per sec, if there were no sector headers, inter-sector gaps, etc.
However, post-read processing must occur, so we can only really achieve 1/8th of that speed (hence the interleaving). Thus, an effective speed of 12,800 bytes ÷ 8 = 1,600 bytes per second.
After each 20 msec sector read, there is about 140 msec of post-processing as the disk continues to spin. But the CPU has to keep up with the drive as it reads each byte, because the drive has no buffer. Therefore most of the time the CPU is not bothering to read the data passing under the head, but is instead post-processing previously read data.
With an infinitely fast disk, it takes about 30,642 clocks. ie. about 30.642 msec, between reading an arbitrary byte in a given sector and reading the equivalent byte in the next sector.
It also takes additional time to change tracks, and to start or stop the motor.

Game Help

These do nothing very useful, but are not expected to (eg. they are for controlling unemulated hardware, or are code fragments for incorporation into your own games):

2708 EPROM Programmer
Linearization (Linearisatie)
Vector Magnetometer
Wind Furnace Controller
most routines

These games are hardcoded for 110 baud:

On-screen Clock
PPI-based EPROM Programmer
110 baud version of Lunar Lander (machine code)
110 baud version of Biorhythms
110 baud version of Funny Farm Races

These games are hardcoded for 300 baud:

Astro Trek (but an official 110 baud patch is provided with the listing)
Reaction Timer
300 baud version of Lunar Lander (machine code)
300 baud version of Biorhythms
300 baud version of Funny Farm Races

2650 Line Assembler:

"It is not identical but is very similar to the Line Assembler described in the article "2650 mini assembler simplifies programming" by Jamieson Rowe published in the April 1979 issue of Electronics Australia (p. 76-80) and the follow-up article "Improving the 2650 mini line assembler" by A. M. Kollosche in February 1980 (p. 76)." - Chris Burrows.

The start address begin at 2, and increments by 2 every time F5 (reset) is pressed, for some reason.

2650 Micro BASIC programs (eg. Acey-Deucy, Blackjack, Guessing Game (Micro BASIC version), Life (Micro BASIC version), Lunar Lander (Micro BASIC version), Number Game, Radio Log, Temperature Conversion):

Type G1 and then press ENTER to begin execution.

Alien Hunt:

Has ! and " at end of table rows, for some reason.

Assembler, AssemblerPlusDemonstration, AssemblerPlusAssemblerList:

AssemblerPlusDemonstration.pgm will assemble without errors, but the generated machine code is not being written to memory anywhere (we are asking in this case for ORG $2000, but it doesn't seem to matter where we ask for, it is never generated anywhere). Hence, the current dump of Assembler.pgm should be considered suspect (although it has been verified). As the other two are based on that dump, they are likewise suspect.

Binary Floating Point Routines (Application Note AS57):

The program's prompt is corrupt (maybe the emulated teletype is not ready for it).
Each pair of hex digits is not shown until it has been completely input.
The spaces around operators are added automatically by the program rather than by the user.
The start address determines the rounding mode, as follows:

G6A6 will run with rounding.
G6AA will run without rounding.

Give 8 hex digits, then an operator, then another 8 hex digits, then =
Supported operators are +, -, * and : (which is division).

Biorhythm:

Dates are expected to be in dd/mm/yy format.
Invalid dates will cause the program to hang.

Bit Echo:

Prints flashing garbage after each letter, for some reason.

Cricket:

Doesn't randomize very well, for some reason.

DG640 Driver:

To get the flashing cursor, you need PIPBUG (not BINBUG).

ETI-685 Memory Tester:

This expects BINBUG 6.1. It is used as follows:

G440

where and are the start and end addresses, eg.:

G440 1000 1FFF

Funny Farm Races:

1. At the "PLAYER 1-" prompt:
Type in the name of the first player and press ENTER.

2. For each additional player you want to add:
Press P. The machine will say "PLAYER 2-" (or whatever).
Type in the name of the player and then press ENTER.

3. Press ENTER to begin.

4. For each player:
The machine will ask "BET?".
For each bet you want to place:
a. Press Y and then press ENTER.
b. The machine will ask "DOG NO?".
c. Press the number (0..9) of your preferred dog and then press ENTER.
d. The machine will ask "HOW MUCH?".
Press N when this player has placed all their bets.

5. Watch the race and then press ENTER.

6. Go to 4.

Furnace:

This program requires extra hardware (eg. various motors), which is not emulated by Ami/WinPIPBUG. Although it will load and run, it will not do anything useful on the emulators, and, intentionally, does not produce output on the screen. Also, it expects a data table (starting at !6000), which is not present.

Guessing Game (machine code version):

"When called, the program will wait until you enter any character. It will then generate a random number between 1 and 99, which you must guess. Starting address is $0440."

STRT = $440 code
INPT = $493 code
PRNT = $4A6 code
MSAG = $4B1 data

HexCal aka HexCalc:

Enter source address (2 hex digits).
/ appears.
Enter destination address (2 hex digits).
= and result appears.
The first digit of each pair entered is not echoed to the display until the second digit has been input.
Result is the relative offset (ie. the distance between the addresses). Eg.:

01/02=01
03/04=7F
05/05=00
20/30=10

PAIR equ $45E
gosub CRLF;
for (r1 = 3; r1 >= 1; r1--)
{
PAIR = BINOUT();
COUT('/');
PAIR = (BINOUT() - PAIR) & $7F;
COUT('=');
BOUT(PAIR); // Byte output in hex
COUT(' ');
}
goto $3F00;
BINOUT: ;$46D
// Input two hex chars and output in hex
*($476) = BIN(); // Input two hex chars and form as byte
BOUT(*($476)); // Byte output in hex
return *($476);

Life-MachineCode:

"Life is a matrix game concerned with the life, death and birth of cells. Imagine each cell to be in a two-dimensional linear matrix, such that each cell location has eight possible neighbours, as shown:

1 2 3
4 X 5
6 7 8

The rules of cell life, death and birth are as follows:

1. A live cell will survive if it has two or three live neighbours.
2. A live cell will die if it has less than two or more than three live neighbours.
3. A birth in an empty cell will occur if it has exactly three live neighbours.
4. Births and deaths take place simultaneously.

To work with practical terminals the program operates with a limited size matrix, but makes it effectively "infinite" by having "wrap around" from side to side and from top to bottom.
In our version of Life, live cells are represented by Os, and dead or empty cells as blanks. The program starts with an initial pattern (fed in by the player), and calculates the new patterns "generation by generation".
The 32*16 versions are intended for use with the Low Cost VDU of EA February and April 1978. The 32*24 versions are intended for terminals such as the EME-1 VDU, described in the EA January and February 1977 issues.
To use the program, type:

GC00<CR>

and then switch to the appropriate baud rate (110 or 300 baud). Then type a U for 110 baud operation, or a Y for 300 baud operation.
The program will respond with the word "LIFE", followed by the prompt character ":".
If you respond with "N", the program will expect a new matrix to be supplied. The program will echo the N, followed by a carriage return and line feed. A pattern may then be written in (or "seeded") by using the space bar for blanks (these are printed as dots), Os for live cells, and line feeds (LF) [Ctrl+J in Ami/WinArcadia] for new lines.
Blanks are not required on the right hand side of the pattern. Carriage return (CR) will permit overwriting of a line, allowing error correction. Once your pattern is complete, use LFs if necessary to advance to the bottom of the matrix.
Once the pattern is completed, the program will reprint it, and give the prompt sign again. If you now respond with a Gxx, $xx generations will be evolved, with a printout after the last generation. G00 will produce printout after 256 generations, while G01 will produce a printout after only one generation. And so on...
Immediately after you have typed in this command, the program will respond with a message such as <15S, to indicate that in less than 15 seconds it will print out the result of the Gxx instruction. After printing the result the new generation count and prompt will appear at the bottom left hand corner of the screen. This may overwrite live cells, so try and keep your patterns in the centre of the screen (patterns to the right will wrap around to the left).
The remaining instruction is P, which causes the program to print out the existing matrix. The instruction is not used a great deal.
This is the result of a simple pattern. This stabilises after four generations, and then continues forever unchanged:

..O. GENERATION 1
OOO.
....

..O. GENERATION 2
.OO.
.O..

.OO. GENERATION 3
.OO.
.OO.

.OO. GENERATION 4
O..O
.OO.

.OO. GENERATION 5
O..O
.OO.

One of the most interesting and simple patterns has been named the "Glider". The seed for this is shown below:

.O.
..O
OOO

If you are running Life at 1200 baud, it is better to use the autoprint version, which prints out after every generation, and stops automatically when the pattern stabilises.
Simply feed in a starting pattern (using the N command), and sit back and watch. The program will continue until a stable pattern is achieved, at which time it will stop. Note, however, that it cannot detect recurring cyclical patterns, so watch out for these. To stop them, you will have to use the reset facility of the 2650."

For 110 baud, you just need to press U, as documented.
For 300 baud, you need to press U (not Y), then ENTER, contrary to the documentation.
Then press N for a new field and set it up with Os and spaces, using Ctrl-J repeatedly to move down.

$C00..$C59: baud rate initialization routine?
$C26: LIFECRLF
$C39: LIFECOUT
$C5A: LIFECHIN
$C76..$EEC: Life game code
$EED..$F54: Life game variables

LIFECOUT has the following side effects when called:
PSL: CC = eq;
PSL: primary register bank (r1..r3) is always selected
PSU: Flag pin is always set
r1 = *(DATABUS);
r0 = r6 = 0;
You should not call it when SP > 4 (you need one level of stack for LIFECOUT's return address, another level for LIFEDELAY's return address, and another level for LIFEDELAY_ALT's return address.

LIFECHIN has the following side effects when called:
PSL: CC = gt;
PSL: primary register bank (r1..r3) is always selected
PSL: With Carry bit is always clear
r0 = r4 = return code (1..127)
r5 = r6 = 0;
You should not call it when SP > 4 (you need one level of stack for LIFECHIN's return address, another level for LIFEDELAY's return address, and another level for LIFEDELAY_ALT's return address.

Linearization (Linearisatie):

This program requires extra hardware, eg. light pen, which is not supported by Ami/WinPIPBUG. Although it will load and run, it will not do anything useful on the emulators, and, apparently intentionally, does not produce output on the screen.

Lunar Lander (machine code version):

F = Fuel (out of 40)
V = Velocity (- is down (towards surface), + is up (away from surface))
D = Distance from surface (- is underground, + is above ground)
B = Burn

The * is a graphical indicator of your distance from the surface.
You must give a 2-digit burn each turn. Neither digit is displayed until both have been entered.

Mastermind, Revised Mastermind:

You need to use Ctrl-L instead of ENTER after each line of input.

Maths Demonstration:

"This program provides the functions of a simple, 3-function calculator. It will multiply, add or subtract two single digit decimal numbers. Normal plus, minus and equals signs are used, with an asterisk symbol for multiplication. Starts at $0440."

Note that the listing is self-contradictory (the machine code bytes do not match the assembly source code).

STRT:
*(MOD) = ADDZ r3;
r3 = SUB1();
for (;;)
{ r0 = CHIN();
  if   (r0 == '+') goto PLUS;
  elif (r0 == '-') goto SUBT;
  elif (r0 == '*') goto MULT;
}

SUBT:
*(MOD) = SUBZ r3;
PLUS: // $45C
gosub COUT(r0); // print operation symbol ('+' or '-')
r2 = r3; // 1st argument
r3 = SUB1(); // 2nd argument
r0 = r2; // 1st argument
MOD:
r0 += r3, or r0 -= r3, depending on the desired operation
if (r0 < 0)
{ r0 = r3 - r2;
  *(A1) = '-'; // store '-' as 1st character
  r0 |= $30; // format for display
  *(A2) = r0; // store r0 as 2nd character
} elif (r0 >= 10)
{ *(A1) = '1'; // store '1' as 1st character
  r0 -= 10;
  r0 |= $30; // format for display
  *(A2) = r0; // store r0 as 2nd character
} else
{ r0 |= $30; // format for display
  *(A1) = r0; // store as 1st character
  r0 = NUL;
  *(A2) = r0 [NUL]; // store as 2nd character
}
goto ZEND;

MULT: // $48E
gosub COUT(r0); // print operation symbol ('*')
r2 = r3; // 1st argument
r3 = SUB1(); // 2nd argument
r0 = 0;
while (r2 != 0)
{ r0 += r3;
  r2--;
}
while (r0 >= 10)
{ r0 -= 10;
  r2++;
}
r2 |= $30; // format for display
*(A1) = r2;
r0 |= $30; // format for display
*(A2) = r0;
goto ZEND;

SUB1:
do
{ r0 = CHIN();
  clear With Carry and COMpare bits
} while (r0 < '0' || r0 > '9');
r3 = r0;
gosub COUT(r0);
r3 &= $0F; // remove display formatting
return r3;

ZEND:
r1 = 0;
while (*(MSAG + ++r1) != 0)
{ COUT(r0);
}
gosub CRLF;
goto STRT;

Memory Test:

You use the program as follows:

G48F <start-address> <end-address> <loops>

where <loops> is "01".."7F". ("80".."$FF" give infinite tests.) Eg.:

G48F 0500 3FFF 7F

If there is no resulting output other than linefeeds (just goes back to the "*" prompt), this indicates success.
Errors are as follows:

Z or S mean that cleared (zeroed) memory did not read back as $00.
W means that a single bit of memory (eg. $10) did not read back correctly.
L means that set memory did not read back as $FF.

The address of the error then follows the error code.

Message Editor:

"Upon being called, this program will give a prompt character, and await a command character. Commands:

T allows a message to be entered
C allows a stored message to be checked
R allows it to be repeated until the CPU is reset

In text input mode, the DEL character acts as a destructive backspace for correcting errors. To return to command mode, type an Esc.
If the message being stored is too long for the buffer, an F will be displayed. Starts at $0440."

Microbyte Adventure:

To play this game using Ami/WinBINBUG:

1. Choose "Options|Machine|BINBUG" (or press Ctrl+5).
2. Select BINBUG 3.5, 3.6 or 6.1 from the "Options|BIOS" submenu.
3. Select VHSDOS from the "Options|DOS" submenu.
4. Choose "File|Reinitialize machine".
5. Choose "File|Open...".
6. Select "Adventure.raw".
7. Click OK.
8. Type K and press ENTER.
9. Type ADVENT and press ENTER.

The dumped disk is installed for VHSDOS and has one saved game (GAME1.ADV). Note that loading the VHSDOS version under MicroDOS will corrupt the disk! Specifically, the free block list will be corrupted and therefore you will not be able to save the game (as not enough free space will be found) on such a disk. If you want to play it under MicroDOS, you must reinstall it for MicroDOS (by running the INSTALL program).

The INSTALL program does the following:

Disk byte	Action
$B16	Sets this according to the number of rows ($10=16 rows, $18=24 rows). This is part of the game (ADVENT.CMD).
$B17	Sets this according to the target platform ($00=VHSDOS, $01=MicroDOS). This is part of the game (ADVENT.CMD).
$3D..$3F	Sets the date stamp of the game (ADVENT.CMD) to the current date. This is done by DOS, and is a side effect of writing to ADVENT.CMD.
$3301	Sets the next sector field of track 5, sector 2 to 3 (from 10). This is done by DOS, and is a side effect of writing to ADVENT.CMD.

The vocabulary is:
NUGGET, GOLD, SILVER, BARS, JEWELERY, COINS, DIAMONDS, VASE, PEARL, EGGS, NEST, TRIDENT, EMERALD, PYRAMID, CHAIN, SPICES, RUG, CHEST, LAMP, LANTERN, KEYS, FOOD, BOTTLE, CAGE, ROD, CLAM, MAGAZINE, BEAR, BLADE, PILLOW, POTTERY, SHARDS, OYSTER, BIRD, TROLL, DRAGON, SNAKE, DWARF, GRATE, BRIDGE, STREAM, STUFFED, FUCKED, AXE, ALL, EVERYTHIng, HILL, DOOR, GO, WALK, RUN, MOVE, CRAWL, FORWARD, CONTINUE, BACK, RETREAT, DESCRIBE, LOOK, L, EXAMINE, GET, CARRY, TAKE, PICKUP, DROP, FILL, LIGHT, OPEN, OIL, CATCH, THROW, ATTACK, KILL, FEED, WATER, UNLOCK, FREE, RELEASE, WAVE, XYZZY, PLOVER, PLUGH, CROSS, CLIMB, JUMP, EMPTY, LOCK, CLOSE, EAT, DRINK, KUNGFOO, LOAD, SAVE, INVENT, INTENTORy, I, SCORE, QUIT, INFO, HELP, BUILDING, HOUSE, DEPRESS, NORTH, N, SOUTH, S, EAST, E, WEST, W, UP, U, DOWN, D, DOWNWARD, NORTHEAST, NE, NORTHWEST, NW, SOUTHEAST, SE, SOUTHWEST, SW, ENTER, INTO, IN, OUT, OUTSIDE, EXIT, LEAVE, FOLLOW.

This is a (very) partial map and walkthrough, based on confirmed 2650 version behaviour. See https://rickadams.org/adventure/ for more maps and walkthroughs; the 2650 version appears to be similar to the "550-point" version of the game (although it only goes up to 250 points). Eg. https://rickadams.org/adventure/walk550.txt.

Outdoors:
N, W, GET BLADE?, ENTER HOUSE, GET ALL, EXIT HOUSE, S, S, FILL BOTTLE, OIL, FILL LAMP, FILL BOTTLE, OIL, S, UNLOCK GRATE, OPEN GRATE, D

            9
            #
7-----5-----6
|     |     |
8-----4     1
      |     |
      3-----2
      |
     10

1: at a hill at the end of a road
2: in a forest
3: near a slit in the streambed (oil)
4: beside a stream in a valley
5: at a road near a house (blade)
6: in a forest
7: in a forest
8: in a forest
9: inside the house (bottle, food, keys, lamp)
10: directly above a grate in a dry streambed (grate)
5->9: ENTER HOUSE
9->5: LEAVE HOUSE
10->1 (of 1st level A): UNLOCK GRATE, OPEN GRATE, D

1st level A:
W, GET CAGE?, W, GET ROD?, FILL LAMP, LIGHT LAMP, W, W, CATCH BIRD?, W, D

6-----5-----4-----3-----2-----1

1: below the grate
2: in a cobble crawl (cage)
3: in the debris room (rod)
4: in an awkward sloping E/W canyon
5: in the bird chamber (bird)
The bird is frightened of black rods.
6: at the top of a small pit
1->10 (of outdoors): U
6->1 (of 2nd level): D

1st level B:

3
|
2
|
1
|
4----?

1: in a secret N/S canyon above a large room
2: in the canyon with the mirror
3: at the underground reservoir
4: in a secret canyon which exits to north and east (rug)
3->1 (of 0th level): U

0th level:

                                 ?    21
                                 |    |
                          ?-----22----20-19
                                 |        |
1-----2        37  38            ?    ?   |
      |       /     |                 |   |
      3     36-----35-----34-----33   16  |
      |                           |   | \ |
      4-------------------5-------6   17 15-----?
      |                            \  |  /
     18                             \ ? /
                                     \ /
                             13----12-7-14
                                      |
                                   11-8
                                      |
                                      9
                                      |
                                     10

1: at the top of a steep incline above a large room
2: in a cavern with a waterfall (trident)
3: at the end of an immense N/S passage (door)
4: in a giant room
Try a magic word.
5: in a long narrow E/W corridor
6: in the oriental room (vase)
7: the swiss cheese room
8: in a tall N/S canyon
9: at a wide place in a very tight N/S canyon [U]
10: the canyon becomes too tight to continue
11: the canyon runs into a mass of boulders - dead end
12: at the east end of the twopit room
13: at the west end of the twopit room [U]
14: in the soft room (pillow)
15: in a bed quilt [U,D] [S is same as SW here]
16: at the junction of three secret canyons
17: in a secret canyon above a sizable passage [D]
18: the passage here is blocked by a recent cave-in
19: in a maze of twisty little tunnels
20: at the junction of a high northerly passage and a low E/W one
21: at a dead end
22: in the hall of the Mountain King [U]
Some birds can kill snakes.
33: in a misty cavern
34: in an alcove
35: in a large low room
36: in the plover room - emerald
37: in the dark room
38: dead end crawl
1->3 (of 1st level B): D
22->1 (of 2nd level): U

2nd level:
S, GET NUGGET?

                    16
                     |
                    15-----17
                     |
             18-----14
            /        |
           19       13
                   / |
9-----8-----7    12 20-----21
            |     |
      4-----5-----6-11
      |           |
2-----1          10
      |
      3

1: in the hall of mists
Use a magic rod.
2: on the east side of a fissure
3: in the gold nugget room (nugget)
4: at the west end of a long hall
5: at the east end of a long hall
6: at the west end of the hall of mists (diamonds)
7: on the brink of a pit [D]
8: in a dirty broken passage
9: in a room full of dusty rocks [D]
10: in a maze of little tunnels, all alike
11: on the west end of a fissure in the hall of mists
12: in the slab room
13: in a N/S limestone passage
14: at a fork in the path (axe)
15: at a junction with warm walls (pyramid)
16: at a breathtaking view
17: in the chamber of boulders (spices)
18: in a west leading corridor
19: at the N/E side of the troll's bridge
20: outside a barren room
21: inside a barren room (chain)
It may be hungry.
12->1 (of 1st level B): U

The oil level in the lamp is stored at $1E33. Zeroing $16EF (eg. "E 16EF 0" in the debugger) will prevent the oil from being used up.
Location, etc. are likely to be in one or more of $1E22..6, $1E2D..F, $1E38..9, $1E48, $1E4C..F, $1E55..7, $1E75..$1EA1.

MicroWorld BASIC:

Note that this is *not* byte-for-byte identical to the official PIPBUG release of MicroWorld BASIC, as evidenced by the fact that eg. the official BINBUG patch (aka "personality module") for it will not work. The available dump was originally for PIPBUG, then was ported to PHUNSY, then was ported back to PIPBUG.
The first command you should issue is OLD. Then you can RUN or LIST the program.

Mini-Disassembler:

You must type 6 consecutive hex digits. These are not echoed to the screen (except that Ami/WinArcadia do this for you). The first 4 digits are the starting address (including any leading zeroes) and the last 2 digits are the least significant byte of the ending address (the most significant byte is always the same as that of the starting address). Eg.:

0440FF

will disassemble $440..$4FF.
Note that the mnemonics used are not always standard Signetics. Eg.:

HLT = HALT
LPU = LPSU
LPL = LPSL
PPU = PPSU
PPL = PPSL

To disassemble another region, type:

G440

at the command prompt ("*"). If you get another "*", retry; otherwise, now enter a new 6-digit address range.
There are bugs in the published program listing, causing incorrect disassembly of some instructions. There is a fixed version in the Enhancements Pack.
There is also the following unfixed bug: Some situations (eg. 3-byte instruction at $1FE..$200 when range argument was "0100FF") result in the mini-disassembler not detecting the end of the range and instead wrapping back around.

Music:

"The "Music" program occupies locations $4A0 to $5D3, and uses PIPBUG routines. It contains absolute addresses, and is not easily relocated. The music is generated at the flag output of the 2650, and some form of audio transducer is required. This can simply be an audio amplifier and speaker, connected via a suitable attenuator, to the buffered flag output of the CPU.
Monotonic musical notes are generated by pulsing the flag output at suitable rates, with the program "reading" the music from a section of memory. The timing of the music is determined by a time value called "UNIT", which is an even number of up to 15 bits, such that $5160 is about 1/32 of a second.
Each note is specified by two bytes. The first byte represents the number of UNITs that the note will last: $01 gives a duration of 1 UNIT, while $00 gives 256 UNITs, or 8 seconds with a UNIT value of $5160.
The second byte is split into three fields. The most significant bit, bit 7, indicates either a note (%0) or a rest (%1). The next three bits, bits 4, 5 and 6, specify the octave. %111 represents the top octave, while %000 represents the lowest. In practice, the three lowest octaves are not usable, giving a range of only five octaves.
The remaining four bits in the second byte represent the note within the octave. The first note in any octave is E, represented by $0, while the last note is D# (D sharp), represented by $B.
For rests, bits 6 to 0 are not used, so all rests become $80.
It is best to start and end all programs (tunes!) with $80 $80, a long rest, to separate the music from the noises PIPBUG makes while communicating with the terminal. To signify the end of a tune, insert $02 $FF after the long rest.
"Yankee Doodle" occupies locations $5D4 to $6B7, and requires a unit value of $2800, while "Bach" occupies locations $6B8 to $7A3, and requires a unit value of $7000.
To run the program, type:

G58C [<address of first note>] [<value of UNIT>] <CR>

The last two parameters are optional. If they are not given, the program will use the previous values. Thus, to play "Yankee Doodle", type:

G58C 5D4 2800<CR>

and for "Bach", type:

G58C 6B8 7000<CR> "

These print garbage while playing, for some reason.

Note	Very low	Low	Middle	High	Very high
E	$30	$40	$50	$60	$70
F	$31	$41	$51	$61	$71
F#/Gb	$32	$42	$52	$62	$72
G	$33	$43	$53	$63	$73
G#/Ab	$34	$44	$54	$64	$74
A	$35	$45	$55	$65	$75
A#/Bb	$36	$46	$56	$66	$76
B	$37	$47	$57	$67	$77
C	$38	$48	$58	$68	$78
C#/Db	$39	$49	$59	$69	$79
D	$3A	$4A	$5A	$6A	$7A
D#/Eb	$3B	$4B	$5B	$6B	$7B
Rest	$80	$80	$80	$80	$80

For the purposes of the above table, each "octave" is assumed to begin at E.
Note that there is a short delay for Yankee Doodle, and a long delay for Bach, before they actually begin to play the song.

Nim:

"The game of Nim: starting with 23 you and the program take turns at subtracting a number from 1 to 3. The one that leaves 1 after their move wins. Starting address is $0440."
The winning strategy is as follows:
You will have a turn where there are 6..8 widgets. Taking 1..3 widgets accordingly on this turn will leave 5 widgets.
The computer must then take 1..3 widgets, leaving 2..4 widgets.
You should then take 1..3 widgets accordingly, to leave 1 widget and therefore win.
Ie.:
If 23 remaining on your turn, take 2 leaving 21.
If 22 remaining on your turn, take 1 leaving 21.
If 21 remaining on your turn, take 3 leaving 18 but you are in danger.
If 20 remaining on your turn, take 3 leaving 17.
If 19 remaining on your turn, take 2 leaving 17.
If 18 remaining on your turn, take 1 leaving 17.
If 17 remaining on your turn, take 3 leaving 14 but you are in danger.
If 16 remaining on your turn, take 3 leaving 13.
If 15 remaining on your turn, take 2 leaving 13.
If 14 remaining on your turn, take 1 leaving 13.
If 13 remaining on your turn, take 3 leaving 10 but you are in danger.
If 12 remaining on your turn, take 3 leaving 9.
If 11 remaining on your turn, take 2 leaving 9.
If 10 remaining on your turn, take 1 leaving 9.
If 9 remaining on your turn, you will eventually lose.
If 8 remaining on your turn, take 3 leaving 5.
If 7 remaining on your turn, take 2 leaving 5.
If 6 remaining on your turn, take 1 leaving 5.
If 5 remaining on your turn, you will soon lose.
If 4 remaining on your turn, take 3 leaving 1 and winning.
If 3 remaining on your turn, take 2 leaving 1 and winning.
If 2 remaining on your turn, take 1 leaving 1 and winning.
If 1 remaining on your turn, you have already lost.

Number Game:

The ! prompt means to hit ENTER (it presumably uses this user-dependant delay for randomization).
Numbers up to 65535 are possible.
The target number is stored at $486..$487 in little-endian format.
The number of turns taken is stored at $4A8.

On Screen Clock:

The original published version has a bug at $505 ($00 should be $0C). There is a fixed version in the Games Pack.

This program needs the starting time to be poked into memory and registers before execution. Pause the machine and then set the time like this before starting at $500:
*($573) = tens of hours
r3 = ones of hours
r2 = tens of minutes
r1 = ones of minutes
All values are stored in ASCII format. Eg. for '5', use $35 (ASCII '5'), not $05.
Eg. use this sequence of debugger commands for 11:58 am:

P
E $573 '1'
E R3 '1'
E R2 '5'
E R1 '8'
J $500
P

When the time reaches 13:00, it will reset back to 01:00.

Othello (Reversi) 2.0:

Input must be in Y,X (row,col) format.

Printer Routines, Trace Routine:

Of course, the provided binaries do nothing (ie. do not "work") by themselves, as they are only subroutines. See the relevant magazine articles for more information about how to use them in your own programs.

Reaction Timer:

You have to react when the cursor is in the leftmost column.

Relative Address Calculator:

Enter the 1st address (4 hex digits).
Enter the 2nd address (4 hex digits).
It will then display the value to use for a relative branch from the 1st to the 2nd instruction (the same as Ami/WinArcadia debugger REL command does).

Relative Branch Calculator:

Enter source address (4 hex digits).
Enter destination address (4 hex digits), then "=" appears, and tells you the relative offset (or "?" if out of range).
The first digit of each pair entered is not echoed to the display until the second digit has been input.

Rotate:

"The computer generates a 4*4 array of the first 16 letters of the alphabet, arranged in a random order. The object of the game is to rearrange the array into the following form:

A B C D
E F G H
I J K L
M N O P

The array can only be rearranged by rotating [2*2] blocks of four letters clockwise. The block to be rotated is specified by the letter in its top left hand corner. It is invalid to try to rotate by calling letters on either the bottom row or the right hand column of the array.
If a mistake is made, it can be corrected once between valid rotations. Any two adjacent letters can be exchanged, with the proviso that only one exchange is permitted. When the required pattern has been achieved, or when the game is aborted, the program will print out the number of moves used.
The program occupies locations $440 to $5C7, and uses routines from PIPBUG. To run the program, type:

G440<CR>

and the computer will respond with "PRESS ANY KEY". Once this has been done, a random pattern will be generated and printed, and the prompt message "ROTATE:" given.
Here is a sample printout. The "Z" command was used to terminate the game.

*G440

PRESS ANY KEY

OJMD
EPLI
BFHK
CNAG

ROTATE: F

OJMD
EPLI
BNFK
CAHG

ROTATE: N

OJMD
EFLI
BANK
CHFG

ROTATE: N

OJMD
EPLI
BAFN
CHGK

ROTATE: F

OJMD
EPLI
BAGF
CHKN

ROTATE: EXCHANGE: L,M

OJLD
EPMI
BAGF
CHKN

ROTATE: P

OJLD
EAPI
BGMF
CHKN

ROTATE: M

OJLD
EAPI
BGKM
CHNF

ROTATE: CANCEL

OJLD
EAPI
GMNF
CHKN

ROTATE: G

OJLD
EAPI
BHGF
CKMN

ROTATE: YOU TOOK 07 MOVES

If you wish to rotate a particular block, type the letter in the top left hand corner of that block. If you wish to cancel a move, type carriage return, and the program will respond with "CANCEL", and then reprint the last but one block.
If you wish to exchange two adjacent letters, type X. The program will respond with "EXCHANGE:", and expect you to type in the two desired letters. If you cannot solve a particular pattern, type Z, and this will abort the game.
An average pattern, with only one exchange permitted, should take between 25 and 30 moves. Early attempts may take more."
Note that the game does not enforce the rule about only permitting one exchange per game.
The unpatched version (ie. as found in the Games Pack) will not work on Ami/WinArcadia. You should use the patched version (ie. as found in the Enhancements Pack).

RYTMON:

This program does not echo your input to the screen.

Solitaire:

This game expects a display with more than 16 rows. The SVT-100 terminal which is emulated by Ami/WinArcadia is only one of the output devices that could be hooked up to a real PIPBUG machine. The game was probably designed for a teletype. We suggest using the "Log|Echo I/O to console?" option.

Star Shoot:

The objective is to reach the end configuration shown below in as few moves as possible, by shooting stars. Each move consists of a digit 1-9 corresponding to the position of the star to shoot:

No.	Start	End
123	...	***
456	.*.	*.*
789	...	***

The only valid first move is 5. Shots have these results:

1	2	3	4	5	6	7	8	9
.!- !!- ---	!.! --- ---	-!. -!! ---	!-- .-- !--	-!- !.! -!-	--! --. --!	--- !!- .!-	--- --- !.!	--- -!! -!.

. means the star becomes a dot
! means the star or dot becomes a dot or star (respectively).
- are unchanged. It is possible to reach a configuration with zero stars and thus no possible moves, losing the game.

Time:

This program uses cycle counting techniques. Under Ami/WinArcadia 8.41, it appears to run too fast (ie. the "game" time goes faster than the emulator time).
The two most likely possibilities would be:
(a) the program was not originally tested and tuned to a sufficient precision by its programmer; and/or
(b) the real machine is spending a certain number of cycles servicing interrupts (which don't occur in the emulator).
Of course, since it starts counting from minute 1 rather than minute 0, the time as shown in this program will be minute later than that shown by the emulator.
When this program says "0100" (ie. "one hour"), emulator time should be approximately "00:59:00.00" (though it would be fair to allow a few milliseconds for initialization). However, emulator time when this event occurs is actually only "00:58:47.20". So this program is 12.80 seconds fast over that 59 minutes. (Or, conversely, you could suggest that the emulator is slow by that amount, or a combination of both.)
Such accuracy is approximately 1:276.5625 (slightly worse than 1 second fast per 5 minutes), which makes this program rather useless over lengthy periods.

Vector Magnetometer:

This program expects extra input (eg. various sensors) and output (eg. pitch and roll indicators) hardware, which is not supported by Ami/WinPIPBUG. (The LED display, used for output of heading data, is supported.) Although it will load and run, it will not do anything useful on the emulators, and, intentionally, does not produce output on the main screen (only via the LED display).

Signetics Instructor 50

This machine is a "microprocessor development board" aka "trainer".
The start address for user programs can be specified at runtime by the user as with eg. the Elektor TV Games Computer.
BIOS calls are made via eg. ZBSR *DISPLY; there is a zero page jump table at $1FE6..$1FFF.

Hardware equates/memory map

Region	Size	Basic version	Expanded version
$0000..$01FF	512 bytes	user RAM	user RAM
$0200..$0FFE	3582 bytes	unused	expansion RAM
$0FFF	1 byte	I/O port	I/O port
$1000..$177F	1920 bytes	unused	unused
$1780..$17BF	64 bytes	user RAM	user RAM
$17C0..$17FF	64 bytes	monitor RAM	monitor RAM
$1800..$1FFF	2K	monitor ROM	monitor ROM
$2000..$7FFF	24K	unused	expansion RAM

I/O Devices

The 28-key keyboard is as follows:

------Left Keypad------ ---------Right Keypad----------
.SENS.. .WCAS.. .BKPT.. ...C... ...D... ...E... ...F...
..INT.. .RCAS.. ..REG.. ...8... ...9... ...A... ...B...
..MON.. .STEP.. ..MEM.. ...4... ...5... ...6... ...7...
..RST.. ..RUN.. ENT NXT ...0... ...1... ...2... ...3...

MON, RST and ENT NXT are white on orange. All other keys are white on blue. There are no paddles.

8-digit 8-segment LED display (red on black):

Each of the 8 digits is divided into 8 segments, as shown: +0+ The + don't really exist, therefore it is really like this: 5 1 +6+ 0 4 2 5 1 +3+ 7 6 4 2 3 7 Eg. the bottom segment is controlled by bit 3 (so, $08 would set it, $00 would clear it). The display is controllable at the segment level (ie. you can get 256 combinations) via direct hardware access (ie. bypassing USE BIOS functions and using the WRTE instruction), using the bit numbers listed above.

"PARALLEL I/O" section, consisting of:

8 glow LEDs ("7".."0");
8 corresponding toggle switches (unlabelled);
Toggle switch with 3 possible positions (up, middle and down, corresponding to "MEMORY $0FFF", "EXTENDED I/O PORT $07" and "NON-EXT DATA PORT", respectively). "The default is probably EXTENDED I/O PORT $07."

In NON-EXTENDED I/O mode:

REDD,rn to read from the toggle switches
WRTD,rn to write to the glow LEDs

In EXTENDED I/O mode:

REDE,rn $07 to read from the toggle switches
WRTE,rn $07 to write to the glow LEDs

In MEMORY MAPPED I/O mode:

LODA,rn $0FFF to read from the toggle switches
STRA,rn $0FFF to write to the glow LEDs

"RUN" glow LED:

"It appears to be on all the time. It is on in monitor mode, during stepping, and remains on at breakpoints. It will turn off after the processor executes a HALT ($40) instruction. It won't turn back on again until you hit MON, RST, in that order. You can't just break back into monitor mode after hitting a HALT instruction. Hitting MON, RST somehow brings the machine back to life and into monitor mode; otherwise the machine is dark." - Tyler Whitney.

"FLAG" glow LED, showing the state of the Flag pin of the CPU.

"INTERRUPT" toggle switch: "DIRECT" or "INDIRECT":

When an interrupt is generated/received, the Instructor 50 writes $07 or $87 to the data bus, depending on the position of the DIRECT/INDIRECT INTERRUPT switch. Then it does a ZBSR $07 or ZBSR *$07, as appropriate.

"INTERRUPT SELECTOR" jumper (on underside of machine):

"A.C. LINE" (ie. 50Hz) or
"KEYBOARD" (ie. INT key).
"The default is probably keyboard."

S-100 bus (at rear) (not emulated).

"CASSETTE" jacks: "PHONE" and "MIC":

The cassette subsystem is somewhat like that of the Elektor TV Games Computer, but uses 6 pulses for a "0" and 3 pulses for a "1", except that 3 extra pulses are appended to the last bit of each byte (giving 6+3=9 pulses for a "0" or 3+3=6 pulses for a "1").
As with the Elektor, the rate at which bits (and thus bytes) can be loaded/saved depends the actual data payload (ie. depends on whether they are "0"s or "1"s).
Port $F8 bit 4 is FREQ. The BIOS is flipping that at a constant regular rate (at least while recording).
Port $F8 bit 3 is ENV. That is high whilever we are actually recording a bit, and goes low between bits. It stays high for longer for a "0" bit than for a "1" bit.
So whilever ENV is high, we just write the current status of the FREQ bit to the tape, and whilever ENV is low, we just write silence.
It gets NANDed, so if ENV and FREQ are both high, we are low, and otherwise, we are high.
It sets port $F8 to $10 and $18 while writing, and $00 at rest.
During playback, the Sense bit is set directly from the tape based on whether above or below the zero-crossing point.

USE BIOS

USE is an acronym for "User System Executive".

"When in Monitor mode, pressing anything on the hex keypad generates Error 2 on the real machine. On the control keypad, you can hit most keys with impunity. Hitting STEP while in monitor mode generates Error 9 on the real machine." - Tyler Whitney.
Error 2 means: "Restricted command."
Error 9 means: "Next instruction is in the MONITOR area." Ie. if the STEP button is pressed and the next instruction would be in the monitor area, it will be reported by the appearance of Error 9.

The USRDSP (USeR DiSPlay) command is used as follows:

R0: Return code.
R1..R2: Pointer to byte preceding string.
R3: $00/$01/$80. $01 returns immediately. The USE BIOS only allows character-level (ie. glyph-level) access. The character set is as follows:

$00

$01

$02

$03

$04

$05

$06

$07

$08

$09

$0A

$0B

$0C

$0D

$0E

$0F

$10

$11

$12

$13

$14

$15

$16

$17

$18

$19

$1A

$1B

$1C

0 or O

1 or I

2

3

4

5

6

7

8

9

A

b.

C

d.

E

F

P

L

U

r

H

o

=

space

J

-

.

Y

n

###

..#

###

###

#.#

###

###

###

###

###

###

#..

###

..#

###

###

###

#..

#.#

...

#.#

...

...

...

..#

...

...

#.#

...

# #

. #

. #

. #

# #

# .

# .

. #

# #

# #

# #

# .

# .

. #

# .

# .

# #

# .

# #

. .

# #

. .

. .

. .

. #

. .

. .

# #

. .

#.#

..#

###

###

###

###

###

..#

###

###

###

###

#..

###

###

###

###

#..

#.#

###

###

###

###

...

..#

###

...

###

###

# #

. #

# .

. #

. #

. #

# #

. #

# #

. #

# #

# #

# .

# #

# .

# .

# .

# .

# #

# .

# #

# #

. .

. .

. #

. .

. .

. #

# #

###

..#

###

###

..#

###

###

..#

###

..#

#.#

### #

###

### #

###

#..

#..

###

###

#..

#.#

###

###

...

###

...

... #

###

#.#

Note the trailing dots for "b." and "d.".
Available letters: ABCDEFGHIJLNOPRSUY
Unavailable letters: KMQTVWXZ

Game Help

Beat the Odds:

You can make a bet on any of the following results:

Event	Odds
0 lamps lit	250:1
1 lamp lit	15:1
2 lamps lit	7:1
3 lamps lit	7:2 (3.5:1)
4 lamps lit	5:2 (2.5:1)
5 lamps lit	7:2 (3.5:1)
6 lamps lit	7:1
7 lamps lit	15:1
8 lamps lit	250:1
0..1 lamps lit	25:1
2..3 lamps lit	2:1
4..5 lamps lit	1:1
6..8 lamps lit	6:1
0..2 lamps lit	11:2 (5.5:1)
3..5 lamps lit	2:5 (1:10)
6..8 lamps lit	11:2 (5.5:1)
Specific 2-digit number	250:1
Specific MS digit	15:1
Specific LS digit	15:1
Any one of 5 specified 2-digit numbers	50:1
Any one of 10 specified 2-digit numbers	25:1

Note that in the table above, the bet "6..8 lamps lit" is listed twice, with different odds. This is authentic to the original Signetics documentation.

This game is intended to be played by multiple humans using real money. One player would act as the "house" (ie. banker/dealer) and call for bets, take and record wagers, operate the computer, and pay winners according to the above odds. The computer is used merely as a randomizer. There is no logic in the game for showing odds, taking bets, ascertaining winners, paying winners, etc.

Dice with Display:

The rightmost parallel I/O switch (bit 0) needs to be on, otherwise the 7-segment LED digit area of the display will never change.
The program relies on random data in uninitialized RAM for its random number generation, hence you should ensure that "Settings|Emulator| Randomize memory?" is on before loading the game.

Game of Memories:

This is a Game of Life according to the rules from John Horton Conway. It was written for the Ami/WinInstructor emulator.

The particularity of Game of Memories is that the field for the Game of Life is laid out in a 16*16 byte grid storage area that the emulator can graphically represent and so the view can be resembled - whereby the name of the program: Game of Memories.

When the progam is loaded into WinArcadia, the field is still not seen. "Tools|Memory editor..." must be invoked. The field is in the memory bank $0E00..$0EFF. You should set "Region" to that memory region, and "View as" to "Characters".

The original listing has an error in byte $125:

0124 F9 7C BDRR,r1 $122

which causes an infinite loop. It should instead be:

0124 F9 7E BDRR,r1 $124

The version in the Games Pack incorporates this fix.

Train:

Bits 6..4	Bits 3..0
%000: 0 mph (stopped)	%0000: oP...... HSE
%001: 80 mph	%0001: oPOOO... HSE + 3 FC
%010: 40 mph	%0010: oPOUU... HSE + 1 FC + 2 EC
%011: 27 mph	%0011: oPOUAo.. HSE + 1 FC + 1 EC + 1 HC + 1 C
%100: 19 mph	%0100: oPOOo... HSE + 2 FC + 1 C
%101: 15 mph	%0101: oPooo... HSE + 3 C
%110: 12 mph	%0110: oPUUUo.. HSE + 3 EC + 1 C
%111: 10 mph	%0111: o=ooo... LSE + 3 C
-	%1000: o=UUo... LSE + 2 EC + 1 C
-	%1001: o=AAo... LSE + 2 HC + 1 C
-	%1010: o=UUo... LSE + 2 EC + 1 C
-	%1011: o=OOOo.. LSE + 3 FC + 1 C
-	%1100: o=...... LSE
-	%1101: M....... MT
-	%1110: doooo... EM + 4 C
-	%1111: Mooo.... MT + 3 C

Train components are:

Abbreviation	Display	Description
EM	d	electric-powered mine engine
MT	M	battery-powered mine tractor
HSE	oP	high speed engine
LSE	o=	low speed engine
FC	O	full car
HC	A	half-full car
EC	U	empty car
C	o	caboose