KIM programs

Downloads:
KIM Programs

– Farmer Brown
– Lunar Lander
– Sample extension for XKIM

;=====================================================
; A sample extension for the Extended KIM monitor.
; This is a very simple example of how to write an
; extension (adding a new command) for the
; Extended KIM monitor.
;
; How can you test this? Easy. First, use the “?”
; command in the extended monitor and verify the
; “Z” command is not listed, then load the binary
; version of this file. Do “?” again and you’ll see
; the new command has been added and can be used.

Memory test

;***********************************************************
; This memory test was originally based on Jim Butterfield’s
; memory test program in the First Book of Kim, but has
; grown a bit.
;
; This now tests every memory location using a rolling 9-bit
; pattern. Ie the pattern repeats every 9 bytes, so this
; will detect most shorted address line problems. I use
; this to test memory boards, so it will run forever unless
; an error is detected. At the end of each pass, a ‘.’ is
; printed.
;
; This does output to the TTY port, so if you’re only using
; the default KIM display, the output functions will need to
; be tweaked. Not hard to do, but I didn’t need it.
;
; Written February 2006 by Bob Applegate, but it uses some
; bits of code from Jim Butterfield, and Ross Archer
; (http://www.6502.org/source/io/primm.htm).
;
; bob@applegate.org
; www.k2ut.org – look for my KIM page
;
; Rev 1.0 – 02/02/2006

Downloads:
Memory test for the KIM-1

SS-50 65C02 CPU Board

As many of you know, I started my journey in microcomputers with a KIM-1 in 1978 which was a 6502 based system. My next machine was an OSI SuperBoard, then an Atari 800, and Apple ][, and my first full-time job was at Franklin Computer Corp where I spent most every day doing 6502 programming., etc.

There was at least one commercial board for the SS-50 bus with a 6502, but it was never very popular. Given my interest in this processor I decided to create my own CPU board:

Basic specifications:

  • WDC65C02 processor running at 2 MHz. This is a genuine WDC chip, nothing with an unknown history that came from who knows where.
  • Full memory map of RAM. 0000-7FFF is always RAM while each 4K block in the upper 32K can be turned on or off.
  • EEPROM from F000 to FFFF.
  • Optionally, EEPROM can be enabled from E200-EFFF via a DIP switch.
  • We include a 28C64 (8K) EEPROM with CTMON65, but the socket can support 32K EEPROMs and two jumpers select which 8K region is visible.
  • A single-step switch is on top of the board. When an opcode fetch occurs outside of the EEPROM, an NMI is generated. Great for writing a single-step monitor.
  • The baud rate generator products x16 clock for 1200, 2400, 4800 and 9600 baud.
  • Power-on reset.
  • The monitor source code CTMON65 is available on our Github repository

This is an experimenter’s board as there was no code that I am aware of for a 6502 on the SS-50 bus. It uses the standard SS-30 I/O bus and most of those devices have plenty of example code for the 6800 and/or 6809 to use as templates for writing 65C02 code.



Microchess for the KIM clone

(see also the Microchess page)

Downloads:

The hex file MicroChessOut can be loaded directly into the KIM CLONE and run from $2000
Archive with source.

Following the header "Peter Jennings, www.benlo.com" I was pleasantly surprised to see the website still active:
http://benlo.com/microchess/index.html
http://benlo.com/files/Microchess6502.txt
The source code Microchess6502.txt contains the additional note on line 35:
"; Updated with corrections to earlier OCR errors by Bill Forster, August 2005."
Line 73 comments on the cross-assembler used:
"BMCC    =    $E5         ; was BCC (TASS doesn't like it as a label)"
Looking for information about TASS led me to:
https://www.c64-wiki.com/wiki/Cross_Assembler
Reading from "64Tass/6502Tass: Another native "Turbo Assembler", developed for DOS (6502Tass), later also for Unix, Linux and Windows32 (64Tass)," I suspect the 1996-2002 code by Peter Jennings used the DOS version, but I am running Windows 10 on a modern laptop and I can't find a way to run 16-bit applications without using third party tools like DosBox or an emulator in VirtualBox.
So I decided to try out Tass64.  I found a link to the Windows version on sourceforge, https://sourceforge.net/projects/tass64/.  The documentation is included in the zip file, and also here http://tass64.sourceforge.net/.
Without really reading the documents, I just ran Microchess through the Assembler and got errors.  Below are the errors I got, and how I fixed/hacked/patched each one.
First Attempt:
Error messages:    31
Warning messages:  3
Passes:            2
....Oof.....
Error Group 1:
MicroChessSource:37:8: error: general syntax
cpu 65c02
^
MicroChessSource:38:9: error: general syntax
page 0,132
^
Correction:
Change 37 to: .cpu "65c02"
Change 38 to ; page 0,132
Line 38 is commented out because 'page' "gives an error on page boundary crossing, e.g. for timing sensitive code" and I am simply going to put my faith in Peter Jennings and hope for the best here.
Line 37 can be changed to reflect the CPU you are using.  I got my parts assembled by Bob, and leaving "65c02" as the cpu version works for me on the KIM CLONE.  
Error Group 2:
MicroChessSource:729:6: error: general syntax
db      $2c             ; used to skip over LDA #$20
^
MicroChessSource:859:12: error: general syntax
Hexdigdata     asc     "0123456789ABCDEF"
Correction:
For all the lines that use "db" or "asc," change the pseudo-op to ".text"
Now I got:
-----------------------------------------------------------------------------
C> 64tass.exe -o MicroChessOut MicroChessSource
64tass Turbo Assembler Macro V1.55.2200
64TASS comes with ABSOLUTELY NO WARRANTY; This is free software, and you
are welcome to redistribute it under certain conditions; See LICENSE!
Assembling file:   MicroChessSource
Error messages:    None
Warning messages:  None
Passes:            2
Memory range:      $1000-$1524   $0525
Memory range:      $1580-$15dc   $005d
-----------------------------------------------------------------------------
I think I'd like to run Microchess from $2000 up in one block, so I will modify line 95 and 869:
Change line 95 to ";*= $1580"
and comment out line 869.
-----------------------------------------------------------------------------
Memory range:      $2000-$2581   $0582
-----------------------------------------------------------------------------
Now the source will assemble, but it won't work yet.  The Peter Jennings code with TTY was written for the "6551 Asynchronous Communications Interface Adapter (ACIA)," not the "standard TTY" routines built into the KIM monitor that we see in the First Book of KIM etc.  
http://archive.6502.org/datasheets/mos_6551_acia.pdf
https://en.wikipedia.org/wiki/MOS_Technology_6551
First, I comment out the ACIA addresses from line 42.
;ACIADat    =     $7F70
;ACIASta    =    $7F71
;ACIACmd    =    $7F72
;ACIACtl    =    $7F73
Then, I add in the addresses of the KIM monitor TTY routines for getting (blocking) and outputting 1 character.
; http://www.zimmers.net/cbmpics/cbm/kim1/kim-hints.txt - See "KIM SUBROUTINES"
TTY_GETCH = $1E5A  ; Register States: In to A, X preserved, Y = FF
TTY_OUTCH = $1EA0  ; Register States: X preserved, Y = FF, A = FF
Now, I move to line 822 and start making changes to the I/O Routines.
(1) Comment Out the Init function 825-829, don't need.  I leave the label and rts to allow it to work as a dummy sub routine rather than deleting all references to it in the code.
(2) Replace the meat of "syskin" on 833 with code to push the affected registers, call TTY_GETCH, and restore affected registers.
(3) Replace the meat of "syschout" on 842 to push the affected registers, call TTY_OUTCH, and restore affected registers.
Now the code after line 822 looks like:
;
; 6551 I/O Support Routines
; Replaced with KIM Monitor Routines for KIM Clone - Neil 2020
;
;
Init_6551      ;lda   #$1F               ; 19.2K/8/1
;sta   ACIActl            ; control reg
;lda   #$0B               ; N parity/echo off/rx int off/ dtr active low
;sta   ACIAcmd            ; command reg
rts                      ; done
;
; input chr from ACIA1 (waiting)
;
syskin         ;lda   ACIASta            ; Serial port status             
;and   #$08               ; is recvr full
;beq   syskin             ; no char to get
;Lda   ACIAdat            ; get
PHY
JSR TTY_GETCH
PLY      
RTS                    ;
;
; output to OutPut Port
;
syschout       ;PHA                      ; save registers
ACIA_Out1      ;lda   ACIASta            ; serial port status
;and   #$10               ; is tx buffer empty
;beq   ACIA_Out1          ; no
;PLA                      ; get chr
;sta   ACIAdat            ; put character to Port
PHA
PHY
JSR TTY_OUTCH
PLY
PLA
RTS                      ; done
IMPORTANT: I make use of the 6502 commands to push X and push Y, pop X, pop Y - PHX, PHY, PLY, PLX which work on the 65c02 but not the old-school 6502.  This probably won't be an issue for the KIM Clone, but if it is, it will be necessary to change the way you push and pop using your favorite method from back in the day, of one of the examples here:
http://6502.org/tutorials/register_preservation.html
Now I re-assemble the source code, adding the flag to output INTEL HEX format.  This is because Bob added support for intel hex to the [L] command on the KIM-1.  There are programs on-line (somewhere) for converting and dealing with the KIM paper tape format, but being allowed to Load in INTEL HEX format allows us to output something the KIM CLONE can read without no trouble at all.
-----------------------------------------------------------------------------
C> 64tass.exe --intel-hex -o MicroChessOut MicroChessSource
64tass Turbo Assembler Macro V1.55.2200
64TASS comes with ABSOLUTELY NO WARRANTY; This is free software, and you
are welcome to redistribute it under certain conditions; See LICENSE!
Assembling file:   MicroChessSource
Error messages:    None
Warning messages:  None
Passes:            2
Memory range:      $2000-$256e   $056e
-----------------------------------------------------------------------------
Now, I could use SecureCRT or Tera Term or some other fancy terminal to send the file as ASCII when I press the [L]oad command on the KIM-1.  Today, however, I will use the humble PuTTy terminal emulator.  And simply copy the hex to my clipboard, and paste it in PuTTy after pressing the [L] command.
KIM Clone v1.0B
237A 24 0000
:00000001FF52250D45350455220643330FCC8F02020299250B25010033250736340D3434CD
KIM Clone v1.0B
0000 00 2000
2000 A9 G
MicroChess (c) 1996-2005 Peter Jennings, www.benlo.com
00 01 02 03 04 05 06 07
-------------------------
|BP|**|  |**|BP|**|  |**|00
-------------------------
|**|  |**|  |**|  |**|  |10
-------------------------
|BB|WP|  |**|  |**|  |**|20
-------------------------
|BP|  |**|  |**|  |**|  |30
-------------------------
|BP|**|  |**|  |**|  |**|40
-------------------------
|**|  |**|  |**|  |**|  |50
-------------------------
|  |**|  |**|  |**|  |**|60
-------------------------
|**|  |**|  |**|  |**|  |70
-------------------------
00 01 02 03 04 05 06 07
20 00 00
?C
MicroChess (c) 1996-2005 Peter Jennings, www.benlo.com
00 01 02 03 04 05 06 07
-------------------------
|WR|WN|WB|WK|WQ|WB|WN|WR|00
-------------------------
|WP|WP|WP|WP|WP|WP|WP|WP|10
-------------------------
|  |**|  |**|  |**|  |**|20
-------------------------
|**|  |**|  |**|  |**|  |30
-------------------------
|  |**|  |**|  |**|  |**|40
-------------------------
|**|  |**|  |**|  |**|  |50
-------------------------
|BP|BP|BP|BP|BP|BP|BP|BP|60
-------------------------
|BR|BN|BB|BK|BQ|BB|BN|BR|70
-------------------------
00 01 02 03 04 05 06 07
CC CC CC
Personal Notes:
-The extended monitor on the KIM Clone has extra for string printing and more, so if I was doing a serious "KIM CLONE" port, I might look at rewriting a lot of the drawing functions.  
-It is really clunky how the screen re-draws after every CHARACTER -- which means I have to sit through 4 board redraws just to enter a move.  I want to update that code, because I don't have pre-digital age patience.
-My cross compiler of choice is ca65, part of the cc65 C compiler for the 6502.  Maybe a ca65 port of the syntax is something I might try.
There are great usage notes for this version of the game here:
https://obsolescence.wixsite.com/obsolescence/kim-uno-microchess
Too late now, but I notice he went through the exact same process changing the UART routines for his version of MicroChess for the Arduino KIM-1 emulator.

KIM Monitor KIM clone

KIM monitor as modified for the Corsham Tech KIM Clone board.

Notable changes:
* Removal of the code to save/load from cassette tape.
* Lunar Lander (First Book of KIM) added.
* Famer Brown (First Book of KIM) added.
* New X command from TTY to enter the Corsham Technologies xKIM extended monitor.

See also the Corsham github page.

Download the KIM Monitor repository copy here.

Note that you can use the standard KIM ROMs also, the KIM Clone is a KIM-1.

Extended KIM Monitor

# xKIM

xKIM is an extended monitor for KIM computer systems. Commonly used in Corsham Technologies KIM-1 add-on boards.
It is a 6502 based monitor which has basic tools as well as some additional commands for working
with the Corsham Tech SD Card system.

## Features
* Pure 6502 code.
* Many subroutines available for external programs to use.
* Can auto-run Intel hex files upon loading.
* Can be placed in read-only memory.
* Has all low-level subroutines for talking to the SD Card.
* New commands can be added at run-time to the command handler.

## Command Summary (not a complete list)
* Examine/edit memory.
* Jump to code.
* Load Intel hex file from console or SD card.
* Directory of SD card.
* Get clock from RTC.
* Memory test.
* Branch offset calculator, also within memory editor.
* Type SD file.
* Save memory to SD file.

Downloads:
xKIM-master 2021
xKIM older versions

xKIM Manual 1.6

Parallel port adapter

A small project to convert the connector on the KIM I/O board to a Parallel Port adapter (2021).


KIM-1 Software

Bob Applegate published quite a lot of 6502 code.

Basic interpreters for the 6502

Getting enough memory and bringing up a BASIC interpreter were early goals of many personal computer users back in the 1970s.  While Dr Dobb’s Journal was printing a new small BASIC interpreter for the 8080 almost every month, 6502 users were left out in the cold.  Fortunately, Tom Pittman produced a Tiny BASIC that he charged $5 for.  Microsoft also ported their full floating point BASIC but it was not cheap.

Nowadays the source code for these and other BASIC interpreters are freely available on the internet but usually require the user to jump through some hoops to use them. Ie, setting up a build environment. To make things a bit easier, I’ve put binaries and some sources on this page. These are all quite runnable on a KIM-1 with extra memory. There are no interpreted languages that I am aware of that will run in the 1K KIM-1 although Tiny PILOT from Compute magazine can run in 2K, that’s what I used.

Tom Pittman’s Tiny BASIC

Tom distributed a very small BASIC that needed about 3K to run, and was available on paper tape for $5!!! He has quite a bit about it at:

http://www.ittybittycomputers.com/IttyBitty/TinyBasic/

On there is a KIM-1 version that annoys me a bit. Tom and I worked about 10 years ago to disassemble and produce a really good source code package with a lot of my reverse engineering and his comments about portions of the code he could remember details of. For some reason he put up a poorly commented version Here is the source code, listing, and binary to my disassembly which includes a lot of comments and notes from Tom:

Tiny Basic by Corsham

A ready-to-run binary which loads at $0200 and should have RAM up to $13FF

tinybasic.hex

(see also the Tiny Basic page)

Microsoft 8K BASIC

First, here are complete instructions for building your own version Install the CC65 package, then run the make.sh command, then look at the file tmp/kb9.bin, You’ll need to convert that raw binary image to a file suitable for downloading to the KIM.
Or just use my binary. All of these needs at least 12K of RAM starting at $2000.

(see also the Microsoft Basic page)

Create your own Version of Microsoft BASIC for 6502” — pagetable.com

Binaries

Here is a file suitable for downloading onto a KIM-1. It loads at $2000 but to run it you’ll need to start at $4065. Use the L command in KIM-1’s monitor, then upload the file.  I strongly suggest that you change your terminal emulator so it adds a 200 ms pause at the end of each line.  Once it loads, run it by going to 4065 and running it at $4065 G; To see the easter egg, answer “A” when it asks for memory size.

Original KIM-1 Microsoft BASIC: kb9

This is still experimental but I have a version which uses functions in the xKIM monitor (present on the KIM Clone or on the 60K RAM/EPROM board) to save/load from the SD Card System. It also has a DIR command. This is an Intel HEX file and must be loaded from the xKIM “L” command:

xkim

This loads and runs at $2000.

Bob’s Tiny BASIC

All the early issues of Dr Dobb’s Journal discussed using using an intermediate language (IL) to write a general interpreter, then writing a BASIC interpreter using the IL language.  Nobody used this except for Tom Pittman. I liked the idea and about five years ago wrote my own BASIC using that approach. It is buggy, but the sources are on github so anyone can take them, hopefully debug things, and put fixes back in place. My version also has commands to save/load programs to/from a Corsham Technologies’ SD Card System.

Source code:

Github Corsham

And a binary version that can be run starting at address 0200:

mytb.hex

Versions:
2019 archive
2021 archive

Bob’s_Tiny BASIC

SD Card Shield

When we began building the first of our SS-50 series of cards, the most common request was for a mass storage option. Those old disk controllers are hard to find on the surplus market and the old disk drives are getting harder to maintain. While we like vintage equipment, sometimes it’s worth using some modern technology to do updates.

Enter our SD Card System.
This is a two board system that provides a very inexpensive, flexible, and long-lasting storage option for our KIM Clone , SS-50 based designs, or almost any third party system.

The main board is our SD Shield. It plugs into an Arduino Mega and provides for insertion of a micro SD card, and also includes a DS3231 based real time clock (RTC). The Arduino does the hard work of providing an interface between the host processor (6502, 6800, 6809, etc) and the SD card and RTC. It connects to the host via a ribbon cable.

The board also contains three LEDs used for status, a RESET switch, a four position DIP switch, a DS3231 RTC, backup battery, and it maintains the Arduino Mega headers so additional shields can be placed on top. Since the source code is available you can add additional drivers for whatever shields you add. Want to add an LCD shield that displays which files are mounted? Just plug in the shield and modify the user interface class in the source code. Only one of the DIP switches has a defined purpose, so the rest are free for you to add your own logic.

The protocol between the host and the SD Card System is completely defined in The Remote Disk Protocol Guide.

In order to use this card on an SS-50 based system, you will also need a parallel card such as ours.



SD Card System 2015
SD Card System 2017
SD Card System 2021
The Remote Disk Protocol Guide August 2015 V0.1
The Remote Disk Protocol Guide April 2017 V1.1

Downloads
Drivers for 6502, 6800 and 6089 Flex, Arduino Mega Firmware, SD Images Flex, older versions also
Firmware 2021
Test program for SD Shield
Clock utilities set time and date from KIM-1
Reproduction and uptodate SD Shield by Eduardo Casino (Github copy)


The schematic above is the only version posted. It is not the latest schematic used by Bob (see below). Eduardo Casino (see the download above) reverse engineered the SD Shield and produced an uptodate version 9.

April 5, 2021 New Version of SD Card Shield

This is another board done entirely with KiCad and rolls in a few changes from the previous boards. It is completely compatible with the rev 8 boards, which were compatible with rev 7, which were compatible with… etc, etc, etc.There is no new revision of Arduino code for this board.

No new features but a few changes:

  • The CR1220 battery has been replaced with a much more common CR2032 to keep the RTC (Real Time Clock) chip alive.  I did extension market research (ie, I emailed all my nieces and nephews) and found they all had 2032 batteries at home, while none of them had 1220s.My family is used to getting odd emails from Uncle Bob.  The local hardware store was surprised  when I asked about CR1220s, so going to a more common battery makes sense.
  • A different micro SD socket. The old one was push-in, pull-out, but this one is pop-in, pop-out.  It also has alignment pins on the bottom making it much easier to get seated exactly in the right spot before soldering. The solder connections are at the back of the socket, not in the front like the old board.  So far every surface mount solder job with the new socket has been perfect the first time, whereas the old sockets needing to be touched-up about 15% of the time.
  • The old 5-pin header for an external RTC board has been removed, allowing the LEDs to be aligned in a row.  With the RTC on-board there was little reason to keep the header.
  • Added a clearly labeled 4-pin area for adding external I2C devices.
  • For those buying the bare board, the LED colors are labeled on the silk screen. BTW, the “bare board” has the DS3231 RTC and the microSD socket already soldered.

The rev 9k1A will eventually be changed to just rev 9, as there is no need to keep KiCad revisions uniquely identified.

March 21, 2018 What’s On the Bench

Sometimes it’s nice to just enhance an existing product, especially when the supply of blank boards starts running low and more need to be ordered.  I’m running low on the SD shields so it was a good time to make some improvements. This is a prototype:

The changes from the Rev 4 boards:

  • A DS3231 RTC and backup battery are now on-board instead of having the plug-in RTC.; Too many of those plug-in boards had batteries that died within a year or two, so I decided to just put the chip directly on the board and have a battery connector.  It takes a very common LR44 battery which can be replaced easily when it fails.
  • DIP switches are clearly labeled as to which is which, and which direction is on and off.
  • A pull-down resistor is temporarily added here to fix a problem where the green and red LEDs don’t work right until the host computer initializes the interface to the SD shield. A pin was left floating and confused the software into thinking the host was sending a byte when it wasn’t.
  • Two I2C pull-up resistors were added but do not seem to be necessary.

There will eventually be a Rev 6 with the new pull-down resistor and maybe the two pull-ups removed, but I’ll use the current Rev 5 boards and manually add the pull-down for now.

The RTC is completely software compatible with the current boards so any version of our Arduino code will work with it.