
         ===============================
         Der WDR Papiercomputer-Emulator
                        or
           The Know-How Paper Computer
         ===============================

                 by Dave Hassler

	               for
            TSC 10K Cassette BASIC 2
		       and
	    MITS Altair 680 BASIC 1.1

  Released under the MIT License, April 25, 2025

INTRODUCTION:

   These programs emulate the WDR Papiercomputer, developed by Wolfgang Back
and Ulrich Rohde in 1983 for the West German television program
"WDR Computerclub."  Originally, the computer model was drawn on a piece of
paper, with a program "tape" (of sorts) on the left side that held the 
ordered program instructions, and on the right side a number of boxes 
representing registers "within" the computer.  Users could use matches, paper 
clips, coins, or whatever small things were handy to represent the numerical
contents of a register.
   The Papiercomputer was wildly popular, with over 400,000 copies printed,
and many more thousands were likely drawn on notebook paper.  By any account,
it was one of the most widely distributed computing products in Europe in
the 1980s.  As late as the mid-2010s, a version of the Know-How computer
was used in Namibia to teach programming concepts to children.  Wikipedia
has a nice article on the computer at: 
   https://en.wikipedia.org/wiki/WDR_paper_computer

   This emulator takes a few small liberties with the original concept.  The
registers are named A through E, instead of 1 through 8.  The emulator
operates on an 8-bit word: the high 3 bits are for the opcode and the bottom
5 bits for either the program counter value or register identification.
Numerical values are from 0-31 (that's a lot of matches!), as are program
line numbers.  Other emulators (such as for Windows or Javascript) allow for
much larger programs and value ranges, and sometimes even additional opcodes;
I have stuck with the five original opcodes from the papiercomputer, which
still presents a "Turing complete" computing environment.  Program line numbers should start with 0 rather than 1.  Other than that, the emulator
behaves as expected.


STARTING THE EMULATOR:

   To get the emulator code into your computer, you can A) bring in the
BASIC source code via a text upload through a serial terminal emulator (or a
*real* terminal, for that matter, if your old Hazeltine is still working),
or B) upload an S Record file, which will be much faster, but only works if
you're using specifically TSC 10K BASIC (not the FLEX version) or MITS Altair
680 BASIC 1.1.  The former must load at $0100 and the latter at $0000 if the
interpreter is resident in RAM.
   Both formats for both BASICs are included in the archive.  (With Altair
680 BASIC, before running the emulator enter the value $3447 into locations
$007C, $007E, and $0080)  Warm start the BASICs, then RUN.  Warm start
locations to jump to are $0103 for TSC BASIC, and $0007 for Altair 680 BASIC.


OPERATION:

   The emulator is divided into two main sections: the Editor and the Run
Module.

The Editor
   From the Main Menu, press E for the E)dit option. Now one can enter and
edit program "tapes" -- think old paper tapes containing punched code,
chugging through an ASR-33...  

   There are five instructions available to the Know-How emulator:

	HLT (opcode 000, octal) - Stop execution of a running program
	INC (opcode 001)   - Increment a register by one (+1)
	DEC (opcode 010)   - Decrement a register by one (-1)
	JMP (opcode 011)   - Set the Program Counter to the line referenced
	ISZ (opcode 100)   - Test for a zero (0) condition in a register
				if not zero, +1 the Program Counter;
				    if zero, +2 the Program Counter.

   Code is entered into the editor in the following format:
			## mnemonic operand
   E.g., 4 ISZ B means line 4 of the program/tape will hold the opcode for 
the ISZ mnemonic and test Register B for a zero condition.  *The space
between the line number and mnemonic, and between the mnemonic and operand,
are required.*
   Enter the lines in sequential order, starting with Line 0.  You can enter
lines of code out of sequence, but because the "tape" is initialized with
all zeros (also the opcode for HLT), two lines of 0 will stop a listing.  If,
after Line 0, you entered 12 DEC C then Line 12 would be "punched" into the
tape array, but will not list, because it's all 0 between Lines 0 and 12.
Last on listing, the very last instruction listed will be HLT, regardless of
whether you entered it.
   The editor has some error checking during code entry, but it may not
catch everything.  To edit a tape/program, simply enter new instructions for
the line. E.g., Line 8 is: 8 INC A but you decide that's an error and that
line should jump to Line 11.  Enter 8 JMP 11 and the new code will replace
the first Line 8.

The Run Module
   When R)UN is selected from the Main Menu, the user is asked to enter
"initial values" for the five registers.  This is in keeping with the spirit
of the original papiercomputer, which had users place counters in the 
register boxes before "running" their code: there are no load instructions
for the registers anyway.  :^)
   The user has the option to allow the program to run continuously or via
single-step: one instruction at a time.  In Single-Step mode, after an
instruction executes, a pointer ("<") will show which instruction will
execute next, allowing one to follow the flow and logic of a program.  Once
a program finishes, you can either go to the Main Menu, or run the program
again with the same or different values in the registers.


LOADING AND SAVING 'TAPES':

   To load a "tape," select E)DIT from the main menu.  Once the ? prompt
comes up, set your "Send ASCII/Text File" (or whatever it's called
on your serial terminal emulator) delays to 10 ms for character and 1,000 ms
(yes, one full second) for the line delay -- BASIC needs time to process that
input.  Then, send the Know-How Tape file.  Verify the transfer by L)ISTing
the tape.  If you see several 'JMP 0' instructions, you have an issue with
the source file, due to the way TSC BASICs output numeric variables (see
below).
   To save a file you've entered into the editor (or prepared 'offline'), 
first turn on "Text Capture" (or whatever it's called on your serial terminal
emulator) and then L)IST the code you've entered.  Once it's completely
finished, stop the text capture, and then clean up the resulting text file. 
The main thing is to make sure there are NO spaces either before or after a
line of code.  A line such as 6 JMP 14 should not have spaces before the 6
or after the 4.  Clean up and save, then you're good to go.


SAMPLE TAPES/PROGRAMS:

   Here is a sample program that adds two numbers together:
	
	0 JMP 3		<-- jump to line 3 to see if nothing left to add
	1 DEC B		<-- subtract 1 from Register B
	2 INC A		<-- add 1 to Register A
	3 ISZ B		<-- is B empty? If no, +1 the PC; if yes, +2.
	4 JMP 1		<-- (no) go do some more starting at line 1
	5 HLT		<-- (yes) then we're done

   The result will be in Register A.  The first JMP at line 0 is to see if
the user wanted to do something like 3+0 -- that's just 3, which is already
in Register A.

   Two text files of "Know-How Tapes" are included in this archive:
MULTIPLY.KHT and DIVIDE.KHT.  They are my solutions for these operations,
but it will likely be more fun if you try to come up with your own programs.
If you run them, I suggest you do so in Continuous Mode, at least at first.
With the MULTIPLY tape, if the product exceeds 31 (it still
works, just with "rollover").  Initial register setup should be as follows:
A = multiplicand, B = multiplier, and C-E = 0.  The result will be in
Register C.
   For the DIVISION tape file, put the dividend in A, divisor in B, C-E = 0.
The result can be read as follows: if, on conclusion of the run, Register B
is zero (empty, meaning the dividend was evenly divisible by the divisor),
the answer is in Register C.  If Register B contains anything at run's end,
the quotient is in C and the remainer is in Register D.  But again, "rolling your own" will likely be more fun.


NOTES, CONSIDERATIONS, IDEAS:

   If a program crashes during a run, Control-C will work with TSC BASIC;
with Altair BASIC, you may need to hit the RESET button on the computer.
  To resume without loss of tape data (but you *did* save it before running it, didn't you?), type GOTO 30 instead of RUN.
   The emulator runs quite slowly: it's going through code at about 1 second
per instruction -- that's roughly the equivalent of a 4.5 Hertz clock speed!
Yikes!  But, considering the thing is written in BASIC and its target
audience (kids, or +50-year-old computer nostalgia nerds!), the speed should
not be an issue.  The single-step option is more for when time is needed to
figure out or explain a bit of code to someone else, or when testing.
   One option I thought about was adding some bit-shifting opcodes (there's
room for two more codes in my setup), either ROL and ROR or LSR and ASL (but
without a carry bit in play) since I have the emulator set up to have the
registers "roll around," up from 31 to 0, and down from 0 to 31.  That would
need a 5-bit display to be added to the end of each register's output.
   Another thought is expanding the JMP mnemonic to allow access to more
than 32 lines of code, maybe to a range of 0-63 for a JMP, doubling the
potential size of a program.  Or create a new JPX instruction for 0-63, if
you want to leave the JMP alone.  I don't think most people will want to
write programs greater than 32 lines of Know-How code, but anyone is more
than welcome to extend this thing in any way she sees fit.
   Along those lines, on the .D64 image in this archive (as well as a text
file version) is a "generic version" of the emulator that, with a few tweaks,
should run under almost any early version of BASIC (MITS Altair BASIC 1.1
had some issues, but CBM BASIC 2.0 and TSC BASIC 2 for 6800 had no issues).
Feel free to tinker with it.
   I wrote this on a lark, and also to to learn about making custom
characters with CBM BASIC 3.5.  As of this writing, I've only had a C16 for
a few months, and I totally dig it -- with the exception of sound, it's a
big improvement over my beloved VIC-20 of youth.

   Have fun!
	Dave Hassler, 18.Apr.2025
	www.vanportmedia.com/PAL-1/cbm
	www.vanportmedia.com/hm68


THE LICENSE:

The MIT License (MIT)

Copyright  2025 David H. Hassler

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
