KIM-1 Simulator


A KIM-1 simulator with the look and feel of the KIM-1 and a debugger to look ‘inside’

Console, with choice of colors of font and background:



KIM-1 built in ROM tape load and save:




Downloads

Version 1.1.4 April 2022

Setup for Windows and executable for Raspberry PI OS and Ubuntu
Source (requires Lazarus IDE 2.x))

KIM-1 Simulator

Hans Otten, 2019- 2022, Version 1.1.4 Latest version at http://retro.hansotten.nl
Changelog at bottom.

Applicable license: MIT license

Contents

Introduction

The KIM-1 simulator is written for my personal use to aid me in developing and testing software for the KIM-1. It is not meant to be a cycle exact complete KIM-1 emulation. Instead it shows as much as possible what is happening inside. So do not expect it to run the typical KIM games on the LED and Keypad.
Just for fun and a tribute, it looks and feels and functions as a real KIM-1. The debugger is what the purpose of this program is. The program is developed on Windows 10 (32 bit executable) and tested and compiled also on Raspberry PI Os (a Debian Linux variant and Ubuntu 20.04.3 LTS. Since source is available, it will run anywhre Lazarus IDE is available.

What is simulated

  • 6502 or 65C02 CPU (only documented behaviour)
  • KIM- LEDs and keypad
  • TTY in and out with TTY console
  • 6530-002 and 6530-003 ROM
  • The suppress ‘echo TTYecho’ hardware
  • The TTY/LED input bit
  • KIM-1 Tape load and save ti audio

Limitations

What the KIM_1 Simulator does not do as the real KIM-1:

  • Light the LED segments from the RRIOTs outputs. Instead the SCANDS routine is intercepted and the LEDs show the hex output of location F9 FA FB.The simulation is not cycle exact enough to perform the KIM-1 way of flashing the LEDs. So some First Book of KIM type programs will not work.
  • The TTY in and out routines are intercepted and rerouted to an ACIA emulation. See the ACIA routines.
  • The upper pages are not mapped to the lower pages as in most KIM-1 configurations. The vectors at FFFA etc are pointing to the KIM-1 ROM vectors, so RESET. NMI and IRQ work.
  • Tape hardware is not emulated.
  • No hardware single-step via NMI, the debugger has much better facilities for that/
  • The CPU runs as fast the host CPU allows, and lets the host operating system do some work like key and display and other applications running and continue the emulation loop until the user stops the 6502 CPU.
  • The CPU emulation may not be perfect, only valid and documented opcodes are implemented, especially ADC and SBC have many, not emulated here, undocumented issues.
  • IRQ handling is not present in this version, see planned enhancements

Enhancements

The KIM-1 Simulator is a KIM-1 with:

  • 6502 or 65C02 CPU (make the choice in the Debugger)
  • RAM to $1400
  • RAM from $2000 to $E000
  • ACIA 6850 at $1600 (equal to Corsham’s I/O card)
  • ROM at $F000 with ACIA routines
  • Pages E and F are not mapped to page 0 and 1 as in most expanded KIM-1’s.
  • LEDs and switches to the user RRIOT Port A and B
  • Switch between TTY and LED/keypad

To do, planned expansions after version 1.0

  • IRQ and 6530 timer support
  • Testing and bugfixing
  • Better documentation …


Installation

Windows

Run KIM1SIMsetup.exe or use the KIM1SIM.EXE + KIM1Simulator.html file in a folder of choice.

Raspberry Pi OS

Execute KIM1SIM from the Raspberry Pi folder

Ubuntu 20.04.3 LTS

Execute KIM1SIM from the Ubuntu folder

Note that the font used is Courier New. Install ttf cour.ttf on Linux in .home/.fonts to prevent substitution with artefacts

Other platforms
Install Lazarus (Version 2 and higher) and build from source.

After installation

Start the KIM-1 Simulator and choose Settings to set the default working directory. Otherwise files may appear at locations you do not want!

How to use as KIM-1

Start the emulator main program and push the ‘Run’ icon. Then press the RS key on the keyboard (or type R).
After that the LEDs awake and the keyboard is operational as a KIM-1.

  [0] to [F]  -   Sixteen keys used to define the hex code
                  of address or data

  [AD]  -   selects the address entry mode

  [DA]  -   selects the data entry mode

  [+]   -   increments the address by +1 but does
            not change the entry mode

  [PC]  -   recalls the address stored in the Program
            Counter locations (PCH, PCL) to the display

  [RS]  -   causes a total system reset and a return to
            the control of the operating program

  [GO]  -   causes program execution to begin starting
            at the address shown on the display

  [ST]  -   terminates the execution of  a program and
            causes a return to the control of the
            operating program

Besides pressing the keys on the KIM keybaord on the screen you can also use the PC keyboard:

  0-9 : key 0 - 9
  a-f : key A - F
  A-F : key A - F
  +   : +
  < : AD 
  > : DA
  P,p : PC
  G,g : GO
  S,s : ST
  R,r : RS
  S,s : ST

Console

Press the TTY swicth and you have a console terminal. The KIM-1 teletype commands now work and also programs line KB9 Basic can be used. See the Console chapter below.

KIM-1 Tape load and save

The KIM-1 tape load ($1873) and save ($1800) programs are emulated.

Fill in the tape ID and optionally start and end address as documented in the KIM-1 User manual.

Start the Save at $1800 and the laod at $1873 with the KIM-1 monitor.

You will be prompted for file to load or save.

Default working directory and other settings

Use the menu Settings – Set default work folder to choose a folder for all files created or used by the emulator. The settings are saved between sessions.

Default settings config file : “/home/(user)/.config/KIM1SIM.cfg” or C:\users\(user)\Appdata\local\KIM1SIM.cfg”

Loaded at startup, updated via the Settings menu.

Load and Save

The menu has Load and Save functions, you can load and save to many 8 bit binary formats as MOS papertape, Intel HEX, Motorola S record, binary and simple hex.

TTY console mode

Press the TTY console switch to let the KIM simulator use a glass teletype in a console window. The standard KIM user interface is shown, see the manual how to use.
Note: set the PC keyboard to CAPS Lock, only uppercase is used in the KIM monitor.
Note the menu options to record a session, (Load Text to Console) or play (Save text from Console, followed by Stop saving text ) a text file in the console.
This is in fact the same functionality as a teletype with high speed papertape punch or reader. You can use this to load and save Basic programs as ASCII text files. Or use the KIM-1 tape routines built in KB9 Basic!

The console

The console is an emulation video terminal (ANSI color, subset) connected to an ACIA (a Motorola 6850) in the KIM-1. The KIM Monitor is patched to send or receive via the ACIA and is transparant to the user of the KIM-1 I/O routines (even the quirlks like flags and returned register values!)

Keyboard input, when the console window has focus, is sent to the serial input of the ACIA. No local echo. The KIM-1 monitor only accepts uppercase (hint: Caps lock!), user programs are free to use upper or lowercase.

Characters sent tot to ACIA output are received by the console window and handled as a VT100 would do, a subset of the ANSI/VT100 is implemented.
All keys of the PC are usable, SHIFT works. Note the translation of codes from the PC keyboard to ASCII characters is for the US International keyboard.
Other mappings are possible by changing the routine in console.pas: procedure TFconsole.FormKeyDown

Received characters by the console are handled as follows, a subset of the ANSI set.

Single control character


$01 : CursorHome 
$04 : CursorRight 
$05 : CursorUp 
BS  : Backspace 
TB  : Tab 
LF  : LineFeed 
FF  : ClearScreen 
CR  : CarriageReturn 
$13 : CursorLeft 
$16 : DeleteToEndofLine 
$18 : CursorDown 
DEL : Backspace  

ESC sequences

ESC[K             Clear from cursor to the end of the line
ESC[0K            Clear from cursor to the end of the line
ESC[1K            Clear from the beginning of the current line to the cursor
ESC[2K            Clear the whole line
ESC[J             Clear the screen from cursor
ESC[0J            Clear the screen from cursor
ESC[1J            Clear the screen until cursor position
ESC[2J            Clear the screen and move the cursor to 0-0, defined sprites are removed, loaded bitmaps are kept

Insert / Delete

ESC[1@            Insert a blank character position (shift line to the right)
ESC[1P            Delete a character position (shift line to the left)
ESC[1L            Insert blank line at current row (shift screen down)
ESC[1M            Delete the current line (shift screen up)

Move cursor

ESC[H             Move to 0-0
ESC[f             Move to 0-0
ESC[s             Save the cursor position 
ESC[u             Move cursor to previously saved position 
ESC[(Row);(Col)H  Move to row,column
ESC[(Row};(Col)f  Move to row,column
ESC[nA            Move the cursor up n lines
ESC[nB            Move the cursor down n lines
ESC[nC            Move the cursor forward n characters
ESC[nD            Move the cursor backward n characters

Attributes

ESC[m             Reset all attributes
ESC[0m            Reset all attributes
ESC[1m            bold
ESC[4m            underline
ESC[5m            italics
ESC[7m            Turn on reverse color
ESC[27m           Turn off reverse color

Color attributes

color     FG       BG      FG high  BG high 
--------------------------------------------
black    ESC[30m  ESC[40m  ESC[90m  ESC[100m
red      ESC[31m  ESC[41m  ESC[91m  ESC[101m
green    ESC[32m  ESC[42m  ESC[92m  ESC[102m
yellow   ESC[33m  ESC[44m  ESC[99m  ESC[103m
blue     ESC[34m  ESC[44m  ESC[94m  ESC[104m
magenta  ESC[35m  ESC[45m  ESC[95m  ESC[105m
cyan     ESC[36m  ESC[46m  ESC[96m  ESC[106m
black    ESC[37m  ESC[47m  ESC[97m  ESC[107m

FG = foreground
BG = background
High = higher intensity

  • Printable character (>= $20): placed on screen where te cursor is, cursor moved to next position
    Wrap around at end of line, screen scroll up when bottom line is reached
  • CR Carriage Return: cursor moved to beginning of line
  • LF LineFeed: cursor moved one line down, screen scroll up when bottom line is reached
  • FF FormFeed: clear screen, position cursor top left
  • ESC sequences start with the ESC character

The debugger

From the menu Simulator choose Debugger to show the debug window. This windows has step/single step/run buttons, shows the registers and flags, zeropage, memory and the stack. The Trace logfile facility may store a trace of what happened. The disassembler part shows a disassembly.

Several refresh buttons let you update the current state of the machine.

Single step, RUN, trace log

First set the PC to the first instruction of the program to test.

  • Step in: execute next instruction
  • Step over: execute next instruction but skip JSR subroutines
  • RUN: execute at maximum speed ( wait 0) or slow (wait x seconds between steps), use the STOP button to halt execution
  • Step n: execute n instructions full speed
  • Run to: execute instructions full instructions until the breakpoint or watchpoint location is reached or STOP pressed
  • You can set 1o code breakpoints, 10 memory watch points and wacthpoinst on registers A,X,, Y and Stackpointer, press the Breakpoints and Watches button to show the form to fill in as desired.
  • Trace log on/off: first set the Trace log file directory from the file Menu, then use any Step to have every instruction logged with status in the logfile and the tracelog.Note that this slows down execution a lot and the files can become large. So clean up regularly!
    The file name of the log is set to KIM1SIMtrace(datestamp).log.

Symbol table and the disassembler

The disassembler shows locations/labels in hex format. If the assembler symbol table is available (TASM can produce that as blank delimited list) you can load it and do some symbolic disassembly.
Load and show the symbol table from the menu “Symbol table”. Supported symbol table formats: TASM 32 bit and CA65 (part of CC65 suite).

RRIOT status display

From the menu Simulator choose RRIOT to show a windows with the current RRIOT status or you can enter new values for the various registers.
Press Refresh to update to the current state, it is not updated realtime.
The 6530-002, responsible for the KIM-1 hardware, is decoded to the relevant in/output bits.
Note that the simulator does not perform the KIM-1 LED/key functions this way. Code for output to the LED displays is currently present but commented out in the source.
Timing limiting is essential for this to work, the simulation now runs as fast as the host CPU can deliver.

The Profiler

Available from the ‘watches and breaks’ form or from the Window menu

This facility keeps track (once activated with the Profiling Check box) how much an instruction is executed,
Independent of the debugger, always available.

Use the Refresh button to see the current state, not automatically updated so it is no a high performance hit.
Any opcode, from o to 255, is counted. The display shows the maximum 65C02 instruction set.

You can save the profiler data to a CSV file, with instruction mnemonic and number of times executed per line.
Invalid instructions are marked as ‘Unknown’.

Compiling and building the simulator from source

Prerequisites

  • A modern PC and operating system. Windows 10 is where the software has been developed, Raspberry OS and Ubuntu have been tested. MacOS may work, but is untested
  • Development (Compile and run everywhere!) with Freepascal and Lazarus IDE, see https://www.lazarus-ide.org/
    Any Lazarus version above 2.0 will be OK.
  • The archive with the KIM-1 Simulator sources KIM1SIMs09.zip (or higher version).
  • Unpack in a folder, avoid blanks in folder and filenames
  • Start the IDE by clicking on KIM1SIM.lpi
  • Build with Run – Build
  • On Windows a Setup installable can be made with Inno Setup, KIM1SIM.iss and compile with Inno Studio.

Note that the font used is Courier New. Install ttf cour.ttf on Linux in .home/pi/.fonts to prevent substitution with artefacts

The include files with KIM ROM and 6502 code

If and when the ACIA routines and other routines in the KIM1SIM ROM are altered you need to rebuild the KIM1SIMrom.inc file.
Subfolder ‘romtoconst’ contains the binary of the original KIM ROMS (6530-002.bin, 6530-003.bin) and the additional ROM binary with ACIA routines (kimsimrom.bin).
The .inc files for the compilation of the KIM1SIM, to be placed in the main folder, are created with the program creatINC.exe, a console application (source included here).
Copy the the tree .inc files to the main folder and compile the KIM1SIM program again.

D:\myfiles\development\kim-1 simulator\romtoconst\creatINC.exe
kimrom002 include file created
kimrom003 include file created
kimsimrom include file created

Folder KIM-1 assembler sources

Here you find assembler sources of various tests. Assemble with TASM, included in the folder. See TASM.HTML for information.
It is convenient to compile from an editor like Notepad++, plugin NPPEXEC
with command to create intel hex file

"D:\myfiles\development\kim-1 simulator\KIM-1 assembler sources\tasm" -65 -x3 -g0 -s $(FILE_NAME) $(NAME_PART).ihex  $(NAME_PART).lst  -s $(NAME_PART).sym

or to create a binary file with

"D:\myfiles\development\kim-1 simulator\KIM-1 assembler sources\tasm" -65 -x3 -g3 -s $(FILE_NAME) $(NAME_PART).bin  $(NAME_PART).lst  -s $(NAME_PART).sym

Note that also symbol files are generated which can be read in by the debugger in the KIM-1 Simulator.

  • kim1sim6502test.asm : The 65(C)02 test, a program that runs on the TTY console
  • kimsimrom.asm : the source of the KIM-1 Simulator ROM at $F000 with ACIA support for KIM-1 TTY in/out
  • Various snippets used to test the CPU emulation

Changelog

  • V 0.9 October 2021 First public beta
  • V 0.9.1 November 2021 Fixed key 0 bug (Thanks Liu!)
  • V 0.9.2 November 2021 Scrollbars in Load/Save dialog boxes added, Linux tests
  • V 0.9.3 November 2021 Added CC65 format symboltable load, added search in symbol table, fixed label display error in disassembly
  • V 0.9.4 December 2021 emulated getch in kimsinrom.asm now returns with Y=$FF
  • V 0.10.0 January 2022 Added 10 breakpoints and 10 watch points in debugger
  • V 0.10.1 January 2022 Save memory bug solved
  • V 0.10.2 January 2022 Watchpoints on registers and Stackpointer added
  • V 0.11.0 January 2022 Profiler (count how much an opcode is executed) added, Windows main menu to get fast to one of the forms
  • V 0.12.0 February 2022 Console cursor control (not finished yet)
  • V 0.13.0 February 2022 Main screen updated, more help entries. Console updates (on screen menu for colors) and KIM-1 tape load and save emulation
  • V 0.13.1 February 2022 Tested on Ubuntu, small updates and bugs fixed
  • V 0.13.2 February 2022 Settings for work directory, KIM tape load/save added to Save/Load memory
  • V1.0 February 2022, all planned functionally implemented (the console is now ANSI color enabled)
  • V1.0.0.1 February 2022, NUM lock numeric keypad added, request for keyboard layout tests
  • V1.1.1 KIMDLE works: timer and KIM keyboard fixes (no key return $15)
  • V1.1.2 Settings for keyboard layout (US International and German for now), key handling KIM keypad and keyboard/console improved, free running timer
  • V1.1.4 April 2022 Improved design, use of debugger Run buttions stops main Run/Stop run state

HEXPAWN

A game by Robert Leedom, published in 6502 user notes #13, 1979. Typed in by Dominic Bumbaco so we can play it!

Paper tape and hex dump of the program
Original article

post

KIM Venture

A Colossal Cave Adventure on a KIM-1? Yes, within the limits of the seven segments LED, and the 1K RAM?
The late-70s labor of love by Bob Leedom to create a mini (nano?) version of Colossal Cave Adventure is not lost.
Like Micro-Chess, amazing what can be done with the unexpanded KIM-1!

The original document with (assembled by hand!) source from Bob Leedom has been OCR’ed and converted into loadable tape and papertape files by Dominic Bumbaca and also by Mark Bush.
Dominic also made a recording on Youtube of him playing the game.

Here I present what I have now on this game:
(with thanks to Bob Leedom, Dave Wiliams, Dominic Bumbaca, Mark Bush and Nils)

PDF with instructions, source code and map (from archive.org)
Game instructions in PDF
Papertape files by Dominic Bumbaca
tape recording by Dominic Bumbaca
HEX dumps of program Dominic Bumbaca
Youtube recording by Dominic Bumbaca
Local copy the Mark Bush Github repository
Papertape files by Mark Bush
Intel hex files by Mark Bush
Assembler sources files by Mark Bush
Corrected hexpawn100 papertape thanks to Nils

Notes by Mark Bush (see his repository here)

KIM-Venture

KIM-Venture is an adventure game based on Colossal Cave written for the KIM-1. The program and its documentation are Copyright © Robert Leedom and we make no claims to any of this material. I (Mark Bush) have gathered everything together here for posterity.

Installing and Running

Included here are both paper tape and HEX format files. The HEX files can be used on a KIM-1 clone from [Corsham Tech](https://www.corshamtech.com), especially if you have their SD card system.

Load the `Venture-ZeroPage`, `Venture-Game`, and `Venture-Extra` files in any order.

Start the game by going to address `$0100` and pressing `GO`.

When you are finished, load `Venture-Scoring` and run from `$0100` to see how you did.

Note that the scoring program overwrites some page zero locations. If you want to be able to go back to your game after seeing your score, then you will need to save page zero first, then run the scoring program, then load your saved file and also `Venture-Game` again and restart at `$0100`.

The original tape IDs of these files are:

ID | File
—|—–
A1 | Venture-ZeroPage
A2 | Venture-Game
A3 | Venture-Extra
06 | Venture-Scoring

Note for KIM-1 clone users

If you are using the KIM-1 clone, then you will not be able to load the `Venture-Game` or `Venture-Scoring` as HEX files from the SD card system completely because the extended monitor uses the stack. Load them from the paper tape files instead.

Saving a Game

You can save the state of your game by saving a copy of zero page (from `$00` to `$EE`) and making a note of the contents of location `$03BD`.

Return to the game by loading your saved file instead of the original zero page data when you load the program and setting the contents of `$03BD` to the value you noted.

For the full version mentioned below (in an expanded KIM-1), record and restore the contents of `$04BD` instead of `$03BD`.

Instructions

Included here are:

* The Instructions] for playing the game.
* The Game Manual containing information about how to load and run the game

Source Code

The `source` directory contains the original source code for the game with all original comments and formatting preserved. There is one change from the original, though. In `Game.asm` in the Main Move Loop, the original code used absolute addressing for the `INC NMBUTS` statement. [My assembler](https://github.com/markbush/6502-assembler) uses zero page addressing when possible which would make this a 2-byte instruction instead of 3-byte, so I have added a `NOP` to preserve addresses in the output.

The following files contain the source code:

File         | Content
-----        | ---------
ZeroPage.asm | data to be loaded into zero page
Light.asm    | The LIGHT subroutine which compiles into the start of zero page
Game.asm     | The actual game which loads into pages 1, 2, and 3
Extra.asm    | Some support subroutines which load into the 6530 RAM
Scoring.asm  | The scoring program

These source files (except `ZeroPage.asm`) are location agnostic.
This allows them to be recompiled into alternate addresses.

The above code can be compiled using the following files:

File                 | Content
-----                |---------
Venture-ZeroPage.asm | Combines LIGHT with the zero page data
Venture-Game.asm     | Creates the actual game
Venture-Extra.asm    | Creates the file loaded into 6530 RAM
Venture-Scoring.asm  | Creates the scoring program
Venture-Full.asm     | Creates a combined program for a KIM 
                       with extended memory (or the KIM-1 clone)

These files are necessary as the individual source files refer to locations and subroutines located in the other parts. They can only be assembled together. Each of the above files contains a directive causing only the relevant part to be output, enabling the separate program files to be created.

For the `Venture-Full` version, the game starts at `$0200` instead of `$0100` and avoids using any locations in page 1 (the 6502 stack). You can stop the program to view your score at any time. Press `ST` to stop the program and change to address `$0600` and `GO`. Press `ST` again and rejoin the game from `$0200`.

The `Venture-Full` file does not include the zero page data so that must be loaded separately and will update the location of the message table in POINTR when run. This is partly to avoid trying to load data through stack locations (which could mess up the loading process) and also to make it easier to keep copies of the zero page data in order to save the state of a game.

Saved copies of zero page from the original multi-part program can correctly be used by this full version (because it updates the location of the messages), but if you wish to use a copy of zero page from the full program with the original, then you will need to change the contents of location `$4B` to be `$03` after loading.

**NOTE**: The `Venture-Full` version is a work in progress – try it at your own risk!!

Tape copy

KIM Kenner 18 1981 Hans Otten, Translated by Hans Otten 2021

A program to duplicate a KIM-1 cassette tape with multiple files on it. Command driven. Requires enough memory above $2000 to hold the largest file on tape (32K for example)
Version 1.1 added the Check tape command.

Binary V1.1 can be downloaded here.

Requires two cassette recorders controlled via the Remote control, see below for the Micro Ade description of control via KIM PIA PB2 and PB3.

Source in Micro Ade format, also downloadable here.

************************************

TAPE COPYING PROGRAM
;
HJC OTTEN JULY 1981 V1.0
JULY 1982 V1.1
;
BASED ON SUPERDUPE FROM THE FIRST BOOK OF KIM
AND THE MICRO ADE CASSETTE ROUTINES
;
COPY WILL REPRODUCE A TAPE COMPLETELY AUTOMATIC
WHEN READ AND WRITE RECORDERS ARE CONNECTED
WITH THE MOTOR CONTROLS OF MICRO ADE
;
DURING READ OPERATIONS IT IS POSSIBLE TO STOP THE
COPYING BY MAKING PA7 OF PIA 1700 HIGH
REMOVE THIS BIT TESTS IF NOT AVAILABLE
AT O249, 02D6 AND 02E9
OR CHANGE FOR KIM TTY BREAK THE PIA LOCATION TO 1740
AND THE BRANCH FOLLOWING TO BMI
;
INSERT REWINDED READ AND WRITE CASSETTES
AND START AT 0200
;
FIRST THE WRITE CASSETTE IS RUN PAST THE LEADER
THEN A FILE IS READ , IF FOUND THE ID AND STARTADDRESS
ARE DISPLAYED . NEXT THE FILE IS WRITTEN.
IF READY THE DISPLAY LINE LOOKS LIKE
ID= 01 START= $3600 COPY !
THE DATA FROM THE FILE IS STORED IN A BUFFER AT $2000
WHERE ENOUGH RAM MUST BE AVAILABLE
;
THIS PROGRAM CAN EASILY BE MODIFIED TO
A CHECKING AND DIRECTORY OF ALL FILES ON A TAPE
BY REPLACING THE JUMP
02D0 4C 2A 02 JMP CREAD
THAT SKIPS THE WRITING OF A FILE
;
*******************************************************
;
COPY ORG $2000 ;
;
DEFINES :
;
BUFFER * $2300 ;
SYNC * $16 ; SYNCHRONISATION CHARACTER
EOD * $2F ; END OF DATA
EOF * $04 ; END OF FILE
SOD * $2A ; START OF DATA
FF * $0C ; FORM FEED
;
; ZERO PAGE USE
HELPL * $00DD ;
HELPH * $00DE ;
CHKCOP * $00DF ; CHECK OR COPY FLAG
;
RPTRL * $00E0 ; READ POINTER IN BUFFER
RPTRH * $00E1 ;
WPTRL * $00E2 ; WRITE POINTER IN BUFFER
WPTRH * $00E3 ;
STRPTL * $00ED ; POINTER IN PRINT STRING
STRPTH * $00EE ;
CC * $00F1 ; COUNT FIELDS IN WRITE
COUNT * $00F2 ;
CHKSUM * $00F6 ; CHECKSUM
CHKHI * $00F7 ;
GANG * $00F5 ; USED BY WRITE
ID * $00F9 ; ID OF FILE
STADRL * $00FA ; STARTADDRESS OF FILE
STADRH * $00FB ;
STARTA * $00FC ; CONSTANT FOR INDEXED WRITE
TRIB * $00FE ; USED BY WRITE
;
; PIA LOCATIES
;
PAD * $1700 ; BREAKKEY IN BIT 7
PBD * $1702 ; PB2 = READ, PB3 = WRITE MOTOR CONTROL
PBDD * $1703 ;
KPAD * $1740 ; LEDDISPLAY
KPADD * $1741 ;
KPBD * $1742 ; CASSETTE I/O
KPBDD * $1743 ;
TIMERT * $1744 ; TIMER
TIMER * $1747 ;
;
; KIM MONITOR ROUTINES
;
RDBIT * $1A41 ; READ BIT FROM TAPE
RDBTK * $19F3 ; READ BYTE FROM TAPE
RDCHTK * $1A24 ; READ CHARACTER FROM TAPE (2 BYTE)
PACKT * $1A00 ; PACK ASCII TO HEX
CHK * $1F91 ; COMPUTE CHECKSUM IN F6,F7
CHKT * $194C ; COMPUTE CHECKSUM IN 17E7,E8
INIT * $1E8C ; INIT KIM PIA'S
SPACE * $1E9E ; PRINT SPACE ON TTY
OUTCH * $1EA0 ; PRINT ACCU ON TTY
PRTBYT * $1E3B ; PRINT ACCU AS TWO HEX CHARACTERS ON TTY
CRLF * $1E2F ; PRINT CR + LF ON TTY
MNITOR * $1C00 ; KIM MONITOR ENTRY POINT
;
*******************************************************
;
MAIN FLOW OF PROGRAM :
;
PROGRAM COPY
;
INITCOPY
REPEAT
READ FILE TO BUFFER
WRITE BUFFER TO FILE
UNTIL FOREVER
;
END
;
*******************************************************
;
PROCEDURES :
;
START CLD ; PROCEDURE INITCOPY
LDAIM $0C ; INIT CASSETTE MOTOR CONTROL
STA PBDD ;
LDAIM $FF ;
STA PBD ;
LDAIM FF ; CLEARSCREEN
JSR OUTCH ;
LDXIM $FF ;
NEX DEX ;
BNE NEX ;
LDXIM HELLOM ; PRINTSTRING ('TAPE COPY')
LDYIM HELLOM /
JSR PRTSTR ;
LDXIM ANDMSG ;
LDYIM ANDMSG /
JSR PRTSTR ;
LDXIM CHKMSG ;
LDYIM CHKMSG /
JSR PRTSTR ;
LDXIM VRSMSG ;
LDYIM VRSMSG /
JSR PRTSTR ;
JSR CRLF ;
JSR CRLF ;
LDXIM CHKMSG ; PRINT ('CHECK OR COPY)
LDYIM CHKMSG /
JSR PRTSTR ;
LDXIM ONLMSG ;
LDYIM ONLMSG /
JSR PRTSTR ;
LDAIM $00 ; CHKCOP FLAG = COPY
STA CHKCOP ;
JSR GETCH ; WAIT FOR ANSWER
PHA ;
JSR OUTCH ; ECHO CHARACTER
JSR CRLF ;
PLA ;
CMPIM 'Y ;
BNE NOCHK ; IF CHAR <> Y THEN COPY
LDAIM $FF ;
STA CHKCOP ;
LDXIM CHKMSG ; PRINT CHECK
LDYIM CHKMSG /
JSR PRTSTR ;
JMP CREAD ;
NOCHK LDXIM COPYMS ;
LDYIM COPYMS /
JSR PRTSTR ; PRINT COPY
LDAIM $F7 ; TURN WRITE CASSETTE MOTOR ON
STA PBD ;
LDXIM $10 ; DELAY (LEADERCASSETTE)
JSR DELAY ;
LDAIM $FF ; TURN WRITE CASSETTE MOTOR OFF
STA PBD ; END INITCOPY

CREAD LDAIM BUFFER / PROCEDURE READ FILE TO BUFFER
STA RPTRH ; READPTR := BUFFERSTART
STA WPTRH ; WRITEPTR := BUFFERSTART
LDAIM $00 ; CHECKSUM := 0
STA CHKSUM ;
STA CHKHI ;
LDAIM BUFFER ;
STA RPTRL ;
STA WPTRL ;
LDAIM $FB ; TURN READ CASSETTEMOTOR ON
STA PBD ;
LDAIM $13 ; INIT CASSETTE I/O
STA KPBD ;
LDAIM $7F ; INIT LEDDISPLAY
STA KPADD ;

SYN BIT PAD ; REPEAT
BPL GOON ; WHILE NOT BYTE = SYNC DO
JMP MONRET ; READ(BYTE)
GOON JSR RDBIT ; IF BREAK EXIT TO MONITOR
LSR ID ; ENDWHILE
ORA ID ; READ(BYTE)
STA ID ; UNTIL BYTE = START OF DATA
STA KPAD ;
TST CMPIM $16 ;
BNE SYN ;
JSR RDCHT ;
STA KPAD ;
CMPIM $2A ;
BNE TST ;
JSR RDBYT ;
STA ID ; ID := READ(BYTE)
LDXIM $FE ; STARTADDRESS := READ(ADDRESS)
ADDR JSR RDBYT ;
STAZX STARTA ;
JSR CHK ;
INX ;
BMI ADDR ;
;
BYTE LDXIM $02 ; WHILE NOT BYTE = END OF DATA DO
DUBL JSR RDCHT ; BUFFER(RPOINTER) := READ(CHARACTER)
CMPIM EOD ; CHECKSUM := CHECKSUM + CHARACTER
BEQ WIND ; RPOINTER := RPOINTER + 1
JSR PACKT ; ENDWHILE
BNE ELNK ;
DEX ;
BNE DUBL ;
STAIX RPTRL ;
JSR CHK ;
INC RPTRL ;
BNE OVER ;
INC RPTRH ;
OVER BNE BYTE ;
WIND JSR RDBYT ; RCHECKSUM := READ(CHECKSUM)
CMP CHKHI ;
BNE ELNK ;
JSR RDBYT ;
CMP CHKSUM ;
PHP ;
LDAIM $FF ; TURN READ CASSETTE MOTOR OFF
STA PBD ;
PLP ; IF RCHECKSUM <> CHECKSUM GREAD FILE TO BUFFER
BNE ELNK ;
JSR CRLF ; PRINTSTRING ('ID=')
LDXIM IDMES ; PRINT (ID)
LDYIM IDMES /
JSR PRTSTR ;
LDA ID ;
JSR PRTBYT ;
LDXIM STMES ; PRINTSTRING (' START=')
LDYIM STMES /
JSR PRTSTR ; PRINT (STARTADDRESS)
LDA STADRH ;
JSR PRTBYT ;
LDA STADRL ;
JSR PRTBYT ;
LDXIM ENMSG ; PRINT ('END = ')
LDYIM ENMSG /
JSR PRTSTR ;
SEC ;
LDA RPTRL ; HELP := READPOINTER - BEGINBUFFER
SBCIM BUFFER ;
STA HELPL ;
LDA RPTRH ;
SBCIM BUFFER /
STA HELPH ;
CLC ; HELP := HELP + STARTADDRESS
LDA HELPL ;
ADC STADRL ;
STA HELPL ;
LDA HELPH ;
ADC STADRH ;
JSR PRTBYT ;
LDA HELPL ;
JSR PRTBYT ;
LDA CHKCOP ;
BNE ELNK ; IF CHECKCOPY FLAG <> THEN CHECK ONLY
JMP CWRITE ;
ELNK JMP CREAD ; END READ FILE TO BUFFER
;
; SUBROUTINE READBYTE
;
RDBYT BIT PAD ; PROCEDURE READ(BYTE)
BMI MONRET ; IF BREAKKEY THEN EXIT TO MONITOR
;
JMP RDBTK ; ENDIF
MONRET LDAIM $FF ; READ BYTE FROM CASSETTE
STA PBD ; END READ BYTE
JSR INIT ;
JMP MNITOR ;

RDCHT BIT PAD ; PROCEDURE READ(CHARACTER)
BMI MONRET ; IF BREAKKEY THEN EXIT TO MONITOR
JMP RDCHTK ; READ CHARACTER FROM TAPE

CWRITE LDAIM $F7 ; PROCEDURE WRITE BUFFER TO FILE
STA PBD ; TURN WRITE CASSETTE MOTOR ON
LDXIM $08 ;
JSR DELAY ; DELAY (FILEGAP)
LDAIM $27 ; INIT WRITE CASSETTE I/O
STA GANG ;
LDAIM $BF ;
STA KPBDD ;
LDXIM $FF ; COUNT := 255
LDAIM SYNC ; WHILE COUNT > 0 DO
JSR NWRITE ; WRITE(SYNCHRONIZATION CHARACTER)
LDAIM SOD ; COUNT := COUNT - 1
JSR OUTCHT ; ENDWHILE
LDA ID ; WRITE (START OF DATA )
JSR OUTBT ; WRITE (ID)
LDA STADRL ; WRITE (STARTADDRESS)
JSR OUTBT ;
LDA STADRH ;
JSR OUTBT ;
DATA LDYIM $00 ; WHILE WPOINTER < RPOINTER DO
LDAIY WPTRL ; WRITE (BUFFER(WPOINTER)0)
JSR OUTBT ; WPOINTER := WPOINTER + 1
INC WPTRL ; ENDWHILE
BNE SAMP ;
INC WPTRH ;
SAMP LDA WPTRL ;
CMP RPTRL ;
LDA WPTRH ;
SBC RPTRH ;
BCC DATA ;
LDAIM EOD ; WRITE (END OF DATA )
JSR OUTCHT ;
LDA CHKHI ; WRITE (CHECKSUM)
JSR OUTBT ;
LDA CHKSUM ;
JSR OUTBT ;
LDXIM $02 ;
LDAIM $04 ; WRITE (END OF FILE)
JSR NWRITE ;
LDAIM $FF ; TURN WRITE CASSETTE MOTOR OFF
STA PBD ;
JSR INIT ;
LDXIM COPYMS ; PRINT ('COPY !')
LDYIM COPYMS /
JSR PRTSTR ;
LDAIM '! ;
JSR OUTCH ;
JMP CREAD ; END WRITE BUFFER TO FILE
;
; SUBROUTINE NWRITE
;
NWRITE STX CC ; PROCEDURE NWRITE (N,CHARACTER)
HICA PHA ; WHILE N > 0 DO
JSR OUTCHT ; WRITE (CHARACTER)
PLA ; N := N - 1
DEC CC ; ENDWHILE
BNE HICA ; END NWRITE
RTS ;
;
; SUBROUTINE OUTBTC
;
OUTBTC JSR CHKT ; PROCEDURE WRITE(BYTE) AS TWO ASCII
OUTBT PHA ;
LSRA ; CHECKSUM := CHECKSUM + BYTE
LSRA ; CONVERT LEFT NIBBLE OF BYTE TO ASCII
LSRA ; WRITE(ASCII)
LSRA ; CONVERT RIGHT NIBBLE OF BYTE TO ASCII
JSR HEXT ; WRITE(ASCII)
PLA ; END WRITE BYTE
HEXT ANDIM $0F ;
CMPIM $0A ;
CLC ;
BMI HEXAT ;
ADCIM $07 ;
HEXAT ADCIM $30 ;

OUTCHT LDYIM $08 ; PROCEDURE WRITE (BYTE)
STY COUNT ; COUNT :=8
TRY LDYIM $02 ; WHILE COUNT > 0 DO
STY TRIB ; SEND 3 PULSES 3700 HZ
ZON LDXAY NPUL ; IF MSB BYTE = 1 THEN
PHA ; SEND 3 PULSES 3700 HZ
ZONA BIT TIMER ; ELSE
BPL ZONA ; SEND 2 PULSES 2400 HZ
LDAAY TIMG ;
STA TIMERT ; ENDIF
LDA GANG ; SEND 2 PULSES 2400 HZ
EORIM $80 ; SHIFT BYTE LEFT
STA KPBD ; ENDWHILE
STA GANG ; END WRITE BYTE
DEX ;
BNE ZONA ;
PLA ;
DEC TRIB ;
BEQ SETZ ;
BMI ROUT ;
LSRA ;
BCC ZON ;
SETZ LDYIM $00 ;
BEQ ZON ;
ROUT DEC COUNT ;
BNE TRY ;
RTS ;
;
; TIMING TABLE
;
NPUL = $02 ; NUMBER OF 2400 HZ PULSES
TIMG = $C3 ; TIMER COUNT
= $03 ; NUMBER OF 3700 PULSES
= $7E ; TIMER COUNT
;
; DELAY ROUTINE
;
DELAY LDYIM $FF ; PROCEDURE DELAY (NR)
YLOOP LDAIM $FF ; DELAY TIME * NR
ALOOP SEC ; END DELAY
SBCIM $01 ;
BNE ALOOP ;
DEY ;
BNE YLOOP ;
DEX ;
BNE DELAY ;
RTS ;
;
; SUBROUTINE PRINT STRING
;
PRTSTR STX STRPTL ; PROCEDURE PRINTSTRING(STRINGPTR)
STY STRPTH ;
PNEXT LDYIM $00 ; WHILE NOT END OF STRING DO
LDAIY STRPTL ; PRINT (MEMORY(STRINGPTR)
PHA ; STRINGPTR := STRINGPTR + 1
JSR OUTCH ; ENDWHILE
PLA ;
BMI LAST ;
INC STRPTL ;
BNE NEXTS ;
INC STRPTH ;
NEXTS JMP PNEXT ;
LAST RTS ;
;
; SUBROUTINE GET CHARACTER
;
GETCH BIT PAD ; PROCEDURE GETCHARACTER ( CHAR )
BPL GETCH ; WAIT FOR STROBE
GWAIT BIT PAD ; WAIT FOR END OF STROBE 
BMI GWAIT ;
LDA PAD ; GET CHARACTER
RTS ; END GETCHARACTER
;
; STRING DATA
;
IDMES = 'I
= 'D
= '=
= $A0
;
STMES = '
= 'S
= 'T
= '=
= $A0
;
ENMSG = '
= 'E
= 'N
= '=
= $A0
;
HELLOM = 'T
= 'A
= 'P
= 'E
COPYMS = '
= 'C
= 'O
= 'P
= 'Y
= $A0
;
;
CHKMSG = 'C
= 'H
= 'E
= 'C
= 'K
= $A0
ONLMSG = 'O
= 'N
= 'L
= 'Y
= '
= '?
= $A0
VRSMSG = 'V
= '1
= '.
= '1
= $A0
;
ANDMSG = 'A
= 'N
= 'D ;
= $A0



KIM-1 printer output RS232 H14

Original articles KIM Kenner 13 1980, 6502 Kenner 19 1981: Hans Otten PGJ de Beer Trasnlated Hans Otten 2021

In two articles a routine to send a character via serial to a printer (or any serial device) and interface this routine to Micro Ade.
The second version allows for handshake signal CTS.
Baudrate may vary from 300 to 9600 baud. Only one or two (handshake) PIA bits are nevcessary, the serial signal is composed with bit banging.
A simple hardware connection to RS232 in two variants: RS232C signal level compliant or a very simple resistor (sufficient for short distances and most printers).

Source in Micro Ade format.

First source with choice of baudrate, second fixed baudrate 4800 baud and CTS handshake.

Also a routine to read a character form a parallel keyboard connected to PIA A with strobe bit in bit 7.



Make MS Basic KB9 faster: the ROR bug

KIM Kenner 19 Patches op Basic Hans Otten, translated by Hans Otten, 20211

May 1981 Byte Magzine had an article in System Notes, Faster Basic for Ohio Scientific.
The article described how the first batch of the 6502 had a faulty ROR instruction, so the programmers of Microsoft Basic had to work around this missing instruction with a slower replacement, (Note 2021: this is well explained in the Pagetable MS Basic articles) and how to patch this to really use the ROR instruction and speed up things.

A letter to the editor in a later Byte (September 1981?) showed the patches required for the KB9 KIM-1 version.

Location $37DE to $3801 and $38D2 to $3903 are now unused.

This patch may speed up KB9 quite a bit for number crunching.

 

Cassette read and write indicator

KIM Kenner 10 March 1980, Dutch article by Hans Otten, English translation Hans Otten, 2021

Having an indication of how the reading and writing to the cassette recorder is going is nice. With the Micro Ade routines the LED display is used for this. the standard KIM-1 routines are mute.
This small hardware circuit gives either a visual or audible indication with the standard KIM-1 routines.

How does it work?
An indication for for the read process is the output signal of the PLL circuit, a stream of digital pulsed delivered at PB7 of the RRIOT 6530-002. During the reading pin PB7 is rpogrammed as input, during the wirte it is an output. Via a buffer the output signal signal is brought to Audio-Out and Audio-Out-High.
The use of PB7 as input and output during the read and write process means that during a read the decoded signal appears on Audio Out, and as it is meant to be, during writing also has the output signal. Collision is prevented by blocking the input signal during writing. So this means that during reading and during write the signal is present on Audio-Out. This enables a indication of both read and write processes.


The circuit

The signal on Audio-Out (application connector A-M) is brought to a transistor (general purpose type) and the alternating signal makes the LED blink quite fast. A miniature loudspeaker can be switched in and the signal can be heard, it is in the hearable audio range. The LED is not very informative, the loudspeaker is, but also can be annoying, so the switch is welcome.

Do not use a lower value than 33 ohm for R2, it will damage the transistor. The circuit does not represent a heavy load, so you can use the KIM-1 power supply.

Construction
A piece of stripboard is sufficient. See the figure below for the connections of transistor and LED. Red, green, yellow can all be used.
Other usage
By programming the output PB7 music or signals can be heard.

Reading tapes from other KIM-1

KIM kenner 6 1978 Hans Otten Dutch, translation to English Hans Otten 2021

Reading tapes recorded on another KIM-1 or bought like Tiny basic, Microsoft KB-9, Miccrochess and Micro Ade was not that easy. Many many errors, especially the hypertape format.

Reading and writing of my own tapes, after having configured the PLL following the guide in the User manual, and keeping the cassette recorder clean, now is flawless. With the motor control (see Micro Ade manual appendix) it is a pleasure!

I read and tried all advices, like adjusting the azimuth of the recorder head, cleaning etc. Maybe the variations in tape speed between recorder and my player and the resulting frequency shift was a problem?
What really helped was looking with an oscilloscope at the output of the PLL (pin 7 of the LM311) we can see clearly the problem:

No real problems with noise or dropouts, just deviations between different recordings, so the PLL does not operate correctly. Bought tapes showed the pictures Wrong 1 and Wrong 2. And that leads to reading problems, the software makes the wrong decisions on ‘0’s or ‘1’s.

The following procedure was developed to read the bought tape, store it and save the program on my own tapes:

  1. Start reading the problem tape, 1873G
  2. Connect a simple voltmeter to pin 7 of the LM311 or Expansion connector-X
  3. Now change the PLL variable resistor to a reading of 2.7V. A scope would show ‘Correct’
  4. Start the read again
  5. Save the program
  6. Repeat with your own recording or the user Manual PLL set procedure

This helped me to read the problem tapes. Only for Microsoft Basic I had to play with the output volume, large variations in the recorded signal. But it worked in the end and now I have my own recordings on tape, several stored and working copies. One can never have enough backups!

PLL Test


This program write alternate two low frequency or three high frequency tones to the tape recorder.
Record this for a couple of minutes.
When reading this tape the PLL should convert this to a symmetric block pulse.


This program shows on the first two digits on the KIM-1 LED display the number of ‘1’s read, on the second two digits the number of ‘0’s read.
When all is well this should 80/80 but anything between 60/A0 and A0/60 is fine.

ASCII parallel keyboard to KIM-1

Kenner 2 page 4 July 1977 Co Filmer, translated to english Hans Otten, 2021

A parallel ASCII keyboard is a nice addition to the KIM-1.

Connect to the PIA A of the KIM-1 on the Application connector.

Some keyboards may require a -12 V power supply.

The address 1700 now shows the ASCII keyboard code of (the last) key pressed. The high bit (PB7) is the strobe signal, the other 7 bits the ASCII code.

A program should poll the strobe bit, if activated wait for the strobe bit to be deactivated, and then read the key and return.
Testing for keypressed such as a break test means checking the strobe bit, if activated stop processing, etc..

Code fragments by Hans Otten

PAD * $1700 ; BREAKKEY IN BIT 7
   ; SUBROUTINE GET CHARACTER
   ;
GETCH BIT PAD ; PROCEDURE GETCHARACTER ( CHAR ) 
 BPL GETCH ;   WAIT FOR STROBE
GWAIT BIT PAD ;   WAIT FOR END OF STROBE 
 BMI GWAIT ;
 LDA PAD ;   GET CHARACTER
 RTS  ; END GETCHARACTER
   ;
   ; example of break test
   ;
SYN BIT PAD ;   REPEAT
 BPL GOON ;     WHILE NOT keypressed
 JMP MONRET ;      
GOON continue processing