# RaspiElf < Cosmac < TWiki

Tags: create new tag view all tags
Raspberry Pi Interface to Cosmac Elf

Intro
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.
Contents

# 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) |  |  |

--
Peter Schmid - 2017-11-26

## Comments

Attachments Attachments

Topic attachments
I | Attachment | History | Action | Size | Date | Who | Comment
--- | --- | --- | --- | --- | --- | --- | ---
bin | LBR_8000.bin | r1 | manage | 0.1 K | 2017-12-26 - 22:48 | PeterSchmid |
png | gpio-numbers-pi2.png | r1 | manage | 53.2 K | 2017-11-26 - 18:46 | PeterSchmid |
jpg | harness.jpg | r1 | manage | 276.2 K | 2017-12-18 - 17:46 | PeterSchmid |
jpg | raspi-elfmemcard-s.jpg | r2 r1 | manage | 55.2 K | 2017-12-18 - 17:49 | PeterSchmid |
jpg | raspi-elfmemcard.jpg | r1 | manage | 396.7 K | 2017-12-18 - 18:00 | PeterSchmid |

Edit | Attach | Watch | Print version | History: r37 < r36 < r35 < r34 < r33 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r37 - 2019-02-11 - PeterSchmid

- Edit
- Attach

Copyright © 2008-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback