The Unix philosophy emphasizes building simple, short, clear, modular, and extensible code that can be easily maintained and repurposed by developers other than its creators. The Unix philosophy favors composability as opposed to monolithic design.

This is a good opportunity to merge old SBC technology (COSMAC Elf e.g. Elf Membership Card) with a new one (Raspberry Pi and GNU/Linux). If you are new to GNU/Linux get involved! I have always admired the UNIX philosophy, I hope this project achieves some of these UNIX goals.

elf2bin (download tool)

NAME

elf2bin - Copies the Elf (Membership Card) memory to a binary file on the Raspberry Pi.

SYNOPSIS

elf2bin [-s hexadr] [-e hexadr] [-w] [-r] [file]

DESCRIPTION

Copies the Elf memory to a binary file (or stdout) on the Raspberry Pi. The Raspberry Pi GPIO is used as interface to the Cosmac Elf SBC (e.g. Elf Membership Card parallel port). The generated data is written to the standard output stream or to a file. Caution: Overwrite file if it exists. Use > for redirecting (save the file) or | for piping to another command (e.g. hexdump). All toggle switches on the Elf Membership Card have to be on the up position except for the READ switch, the READ switch has to be on the down position.

OPTIONS

Non argument options that are duplicated on the command line are not harmful. For options that require an argument, each duplication will override the previous argument value.

-s hexadr

start address in hex (0 is default)

-e hexadr

end adress in hex (0xFFFF is default)

-w

write enable when copying is finished

-r

go to run mode when copying is finished

bin2elf (upload tool)

NAME

bin2belf - Copies the content of binary file on the Raspberry Pi to Elf (Membership Card) memory .

SYNOPSIS

bin2elf [-s hexadr] [-e hexadr] [-w] [-r] [file]

DESCRIPTION

Copies the content of binary file on the Raspberry Pi to Elf (Membership Card) memory. The Raspberry Pi GPIO is used as interface to the Cosmac Elf SBC (e.g. Elf Membership Card parallel port). Use < for redirecting or | for piping from another command. All toggle switches on the Elf Membership Card have to be on the up position except for the READ switch, the READ switch has to be on the down position.

OPTIONS

Non argument options that are duplicated on the command line are not harmful. For options that require an argument, each duplication will override the previous argument value.

-s hexadr

start address in hex (0 is default)

-e hexadr

end adress in hex (0xFFFF is default)

-w

write enable when copying is finished

-r

go to run mode when copying is finished

elf (command line tool)

NAME

elf - Controls the mode, sets data switches and gets LED data of an Elf (Membership Card).

SYNOPSIS

elf [-s hexadr] [-i] [-n] [-v] [load|run|wait|reset|read|get|put] [switch]

DESCRIPTION

Controls the mode, sets data switches and gets LED data of an Elf (Membership Card). The Raspberry Pi GPIO is used as interface to the Cosmac Elf SBC (e.g. Elf Membership Card parallel port). If a command is missing, the default command is then get. All toggle switches on the Elf Membership Card have to be on the up position except for the READ switch, the READ switch has to be on the down position.

load

sets the mode to load (WAIT and CLR active, is equivalent to switches down)

run

sets the mode to run (WAIT and CLR inactive, is equivalent to switches up)

wait

sets the WAIT to active (is equivalent to switch down), option -n inverts the WAIT to inactive (is equivalent to switch down)

reset|clear

sets the CLR to active (is equivalent to switch down), option -n inverts the CLR to inactive (is equivalent to switch down)

read

sets the WE to active (is equivalent to switch down), option -n inverts the CLR to inactive (is equivalent to switch down)

get

gets the mode and the switch data and the LED data

put switch

puts the switch data to the data switches. The data is in hex.

OPTIONS

Non argument options that are duplicated on the command line are not harmful. For options that require an argument, each duplication will override the previous argument value.

-s hexadr

start address in hex (0 is default). Pre increment to the start address before the data is read and written.

-i

post increment. The IN is set active for > 100 us after the data is read and written

-n

not, invert the command. No effect for load, run, get, and put.

-v

verbose, output looks like "LED:01 Q:1 Rx:1 IN:0 WAIT:1 CLR:1 READ:0 SWITCH:0c"

elfdisplay (controls hex-display and hex-keypad)

NAME

elfdisplay - Reads a hex keypad and sets the data and gets LED data of an Elf (Membership Card) and shows address and data on micro dot pHAT display.

SYNOPSIS

elfdisplay [-v] [<device-filename>]

DESCRIPTION

Reads a hex keypad and sets the data and gets LED data of an Elf (Membership Card) and shows address and data on micro dot pHAT display. The console (stdin) can be used as keyboard or the EV_KEY events from USB keypad (e.g. /dev/input/event0).

OPTIONS

Non argument options that are duplicated on the command line are not harmful. For options that require an argument, each duplication will override the previous argument value.

-v

verbose, output looks like "LED:01 Q:1 Rx:1 IN:0 WAIT:1 CLR:1 READ:0 SWITCH:0c"

Function Keys

Short	Mode	Key	Keycode	Notes
IN	Input	I, [CR]	96	Increment address, in LOAD mode causes the data byte shown to be written to the address shown
LD	Load	L, +	78	Goes to the LOAD mode. In the LOAD mode goes to the address entry mode
R/S	Run/Wait	R, .	83	Toggles between Run and Wait. R/S is a reminiscence of HP pocket calculators
MP	Memory Protect	M, -	74	Shows data byte from the address shown
SW	Switch/Keypad	S, [BS]	14	Toggles between front panel switches and keypad

To upload BASIC3 and the knightrider chase light and start the elfdisplay at boot add following to the /etc/rc.local:

# RaspiElf Tools init
# -------------------
printf "Upload BASIC3 to membership card\n"
bin2elf -s 8000 /home/pi/elf/basic/MCSMP20J.bin
printf "Upload knightrider to membership card\n"
bin2elf /home/pi/elf/RaspiElf/chase/knightrider.bin
#printf "Start BASIC\n"
#bin2elf /home/pi/elf/basic/LBR_8000.bin
printf "Start ElfDisplay\n"
elfdisplay /dev/input/by-id/usb-046a_0014-event-kbd &

How to get and build the RaspiElf tools

Get the source from the GIT repository (if you have not installed GIT yet, then install it with sudo apt-get install git), type only the bold text after the $ sign:

pi@cosmac:~/elf $ git clone https://github.com/spyren/RaspiElf
Cloning into 'RaspiElf'...
remote: Counting objects: 68, done.
remote: Compressing objects: 100% (37/37), done.
remote: Total 68 (delta 32), reused 62 (delta 29), pack-reused 0
Unpacking objects: 100% (68/68), done.
Checking connectivity... done.
pi@cosmac:~/elf $

Build (compile) from the sources:

pi@cosmac:~/elf $ cd RaspiElf
pi@cosmac:~/elf/RaspiElf $ cd tools/
pi@cosmac:~/elf/RaspiElf/tools $ make
cc -g -c elf2bin.c
cc -g -c raspi_gpio.c
cc -g -o elf2bin -lwiringPi elf2bin.o raspi_gpio.o
cc -g -c bin2elf.c
cc -g -o bin2elf -lwiringPi bin2elf.o raspi_gpio.o
cc -g -c elf.c
cc -g -o elf -lwiringPi elf.o raspi_gpio.o
pi@cosmac:~/elf/RaspiElf/tools $ 

Install the binaries into /usr/local/bin

pi@cosmac:~/elf/RaspiElf/tools $ sudo make install
install -m 557 elf2bin bin2elf elf /usr/local/bin

Install wiringPi (GPIO Interface library for the Raspberry Pi), details see http://wiringpi.com/download-and-install/

Enable the I2C interface

@cosmac:~/elf/RaspiElf/tools $ sudo raspi-config

• 5 Interfacing Options Configure connections to peripherals
• P5 I2C Enable/Disable automatic loading of I2C kernel module

Sample session

Type only the bold text after the $ sign.

Initialise the Elf memory with 00H (32 Kib):

pi@cosmac:~/elf/RaspiElf/chase $ bin2elf -e 7fff </dev/zero
0x8000 bytes written

Upload and run the chase lighting program (details see ChaseLighting):

pi@cosmac:~/elf/RaspiElf/chase $ bin2elf -w -r chase.bin
0x002d bytes written

Stop the program an go into the load state:

pi@cosmac:~/elf/RaspiElf/chase $ elf load
01 1 0 0 1 1 0 0c

Hexdump the Elf memory until address 0x3f (hexdump is standard UNIX tool and is included in Raspbian and other GNU/Linux'):

pi@cosmac:~/elf/RaspiElf/chase $ elf2bin -e 3f | hexdump -C
0x0040 bytes read
00000000  c0 00 03 e3 90 b3 f8 30  a3 f8 01 53 64 6c 23 fa  |.......0...Sdl#.|
00000010  fe 3a 1a f0 f6 c7 f8 80  30 1f f0 fe c7 f8 01 53  |.:......0......S|
00000020  f8 14 b2 22 92 3a 23 c5  7a 38 7b 30 0c 00 00 00  |...".:#.z8{0....|
00000030  04 ff 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
00000040

Get the mode and the data (LEDs and swiches)

pi@cosmac:~/elf/RaspiElf/chase $ elf
02 1 1 0 1 1 1 ff
pi@cosmac:~/elf/RaspiElf/chase $ elf -v 
LED:01 Q:1 Rx:1 IN:0 WAIT:1 CLR:1 READ:0 SWITCH:0c

Write enable (not READ)

pi@cosmac:~/elf/RaspiElf/chase $ elf -n read
02 1 1 0 1 1 0 ff

Run mode (starts the chase lighting again)

pi@cosmac:~/elf/RaspiElf/chase $ elf run

Put 0000'0000B to the switches (chase LEDs from right to left)

pi@cosmac:~/elf/RaspiElf/chase $ elf put 0
40 1 1 0 0 0 0 00

Put 1000'0000B to the switches (chase LEDs from left to right)

pi@cosmac:~/elf/RaspiElf/chase $ elf put 80
10 1 1 0 0 0 0 80

Get the mode and data while the program is running (LEDs and Q are changing)

pi@cosmac:~/elf/RaspiElf/chase $ elf -v
LED:40 Q:1 Rx:1 IN:0 WAIT:0 CLR:0 READ:0 SWITCH:80
pi@cosmac:~/elf/RaspiElf/chase $ elf -v
LED:02 Q:0 Rx:1 IN:0 WAIT:0 CLR:0 READ:0 SWITCH:80

Start BASIC3 without EPROM

There are BASIC3, Tiny BASIC, and Chuck's Super Monitor EPROM binaries on Lee Hart's The COSMAC ELF Membership Card http://www.sunrise-ev.com/membershipcard.htm website for his famous Membership Card. I have got some old 27C256 EPROMs but no programmer nor eraser.

But the MSC needs to have 64 KiB RAM, the standard 62256 RAM in the U2 socket and the CY7C199 (or IDT71256) soldered in U8.

First of all you need a serial console (terminal program) to communicate with the Elf. I prefer to use microcom (minicom or putty are good alternatives)

pi@cosmac:~/elf/basic $ sudo apt-get install microcom

The Raspberry Pi UART is used as console (default setting). Change this with raspi-config:

pi@cosmac:~/elf/basic $ sudo raspi-config

Select option 5, Interfacing options, then option P6, Serial, and select No for Would you like a login shell to be accessible over serial? and select Yes for Would you like the serial port hardware to be enabled? . Exit raspi-config. Reboot Raspi now.

Add user pi to the tty group (give user pi the right to write to /dev/ttyS0):

pi@cosmac:~/elf/basic $ sudo usermod -a -G tty pi

Get the binary from The COSMAC ELF Membership Card http://www.sunrise-ev.com/membershipcard.htm

pi@cosmac:~/elf/basic $ wget http://www.sunrise-ev.com/MembershipCard/MCSMP20J.bin
...
2017-12-26 23:08:09 (140 KB/s) - 'MCSMP20J.bin' saved [32768/32768]
pi@cosmac:~/elf/basic $ 

Upload the EPROM binary to the Membership Card at starting address 0x8000:

pi@cosmac:~/elf/basic $ bin2elf -s 8000 MCSMP20J.bin
0x8000 bytes written

Get the binary for LBR 8000 from my site:

pi@cosmac:~/elf/basic $ wget http://spyr.ch/twiki/pub/Cosmac/RaspiElf/LBR_8000.bin
...
2017-12-26 23:49:28 (102 KB/s) - 'LBR_8000.bin' saved [3/3]
pi@cosmac:~/elf/basic $ ls -l
total 36
-rw-r--r-- 1 pi pi     3 Dec 26 22:51 LBR_8000.bin
-rw-r--r-- 1 pi pi 32768 Dec 13 17:59 MCSMP20J.bin

Start from address 0x8000:

pi@cosmac:~/elf/basic $ bin2elf -w -r LBR_8000.bin
0x0003 bytes written

Start the serial console and connect to the Membership Card

pi@cosmac:~/elf/basic $ microcom -s 9600
connected to /dev/ttyS0
Escape character: Ctrl-\
Type the escape character followed by c to get to the menu or q to quit

Membership Card's Serial Monitor Program Ver. 2.0
Enter "H" for Help.
>N 


C RCA 1981
BASIC3 V1.1
C/W?
C
 READY
:PRINT "Hello Raspberry Pi"
Hello Raspberry Pi

READY
:

For other than US keyboards you can use Ctrl-4 instead of Ctrl-\.

Remote access the Elf Membership Card with a GNU/Linux PC and SSH (or a Windows PC and PUTTY):

psi@homer:~> ssh -l pi -X 192.168.1.111
pi@192.168.1.111's password: 

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Tue Jan  2 15:53:08 2018 from homer.home
pi@cosmac:~ $ cd elf/basic/
pi@cosmac:~/elf/basic $ bin2elf -w -r LBR_8000.bin
0x0003 bytes written
pi@cosmac:~/elf/basic $ microcom -s 9600
connected to /dev/ttyS0
Escape character: Ctrl-\
Type the escape character followed by c to get to the menu or q to quit

Membership Card's Serial Monitor Program Ver. 2.0
Enter "H" for Help.
>

If your ISP supports DMZ, static IP addresses, port forwarding and dynamic DNS you have remote access to your Elf from everywhere.

RCA 1802 BASIC level 3 ver. 1.1 User Manual

Wiring

Diodes on Veroboard, additional Socket for EEPROM

The red wires are for the EEPROM

The Raspberry Pi ARM processor supply voltage is 3.3 V and the GPIOs are not 5 V tolerant. The Elf supply voltage is 5 V. This means that the GPIOs (input) have to be protected from Elf. The easiest way is to use diodes e.g. 1N4148 to protect the GPIOs from the 5 V, but the GPIOs need then pullup resistors. Thankfully the Raspi GPIOs have internal pullups and they can be controlled by software. The cathode has to be on the Elf side.

It is possible that the Elf works with 3.3 V supply voltage, but this is not within the specifications. In this case the diodes are not needed. Connect the Raspi Pin 1 to P4 Pin 3 (do NOT connect Raspi Pin 2!).

• Elf Membership Card
• https://pinout.xyz/#
• http://wiringpi.com/the-gpio-utility/
• http://raspberrypiguide.de/howtos/raspberry-pi-gpio-how-to/

Bill of materials

Description	Mouser Part#
Ribbon Cable 40 conductors	517-3365/40FT
D-Sub 25P male	523-L717SDBH25P
Header Connector 40 pol	571-4-215911-0
9 x 1N4148	512-1N4148
Socket 6 pin

Veroboard Variant

Description	Mouser Part#
Veroboard
Ribbon Cable 40 conductors	517-3365/40FT
D-Sub 25P male for Ribbon Cable	571-1658613-2
2 x Header Connector 40 pol	571-4-215911-0
Header Connector 34 pol	571-3-215911-4
9 x 1N4148	512-1N4148
Socket 1x6 pin
Pin Header 40 pol	571-2-826925-0
Pin Header 34 pol	571-2-826925-0
DIL8 Socket, optional	571-2-1571552-2
100 nF Capacitor, optional
1N4148, optional	512-1N4148
25LC1024, optional	579-25LC1024-I/P

Cable

Pi Pin#	Pi Function	Elf Pin DSUB J2	POWER P4	Elf Function
1	3.3 V	(18)	(3)	(VIN, +)
2	5 V	(18)	3	VIN, +
3	BCM 2, SDA
4	5 V
5	BCM 3, SCL
6	GND	(19)	1	GND, -
7	BCM 4	1, in		IN- (EF4)
8	BCM 14, TXD	(20)	4, in	RXD, RX (EF3)
9	GND		6	GND, /ON
10	BCM 15, RXD	(15)	5, out, Cathode	TXD, TX (Q)
11	BCM 17	14, in		WAIT-
12	BCM 18	16, in		CLR-
13	BCM 27	17, in		WE-
14	GND
15	BCM 22	2, in		IN0
16	BCM 23	3, in		IN1
17	3.3 V
18	BCM 24	4, in		IN2
19	BCM 10, MOSI	5, in		IN3
20	GND
21	BCM 9, MISO	6, in		IN4
22	BCM 25	7, in		IN5
23	BCM 11,SCLK	8, in		IN6
24	BCM 8, CE0	9, in		IN7
25	GND
26	BCM 7, CE1	25, out, Cathode		O0 (*)
27	BCM 0
28	BCM 1
29	BCM 5	24, out, Cathode		O1 (*)
30	GND
31	BCM 6	23, out, Cathode		O2 (*)
32	BCM 12	22, out, Cathode		O3 (*)
33	BCM 13	13, out, Cathode		O4 (*)
34	GND
35	BCM 19	12, out, Cathode		O5 (*)
36	BCM 16	10, out, Cathode		O6 (*)
37	BCM 26	11, out, Cathode		O7 (*)
38	BCM 20
39	GND
40	BCM 21 (shutdown)