Amanuensis is a command-line interface to control EEPROMs like the 28c256 used in Ben Eater's 6502 8-bit PC course. It can:
- Read individual addresses.
- Read blocks of memory.
- Write to specific addresses.
- Write a
.bin
file into the EEPROM. - Erase the memory.
Note: Software tested on macOS. It might be compatible with Linux-based systems with minor or no changes.
Warning: Developped for 28c256 EEPROM which has 32K addresses each storing 8-bit values. Use for other parallel EEPROMs might be possible. Check section Use with other EEPROMs.
- Installation
- Use Guide
- How It Works
- DIY Shield
- Recommended Writting Procedure
- Use with other EEPROMs
-
Clone this repo:
git clone https://github.com/ignigoliz/amanuensis.git
-
Install Python requirements:
pip install -r requirements.txt
-
In a terminal, go to the cloned repo and execute the install file:
./install.sh
Note: Restart the Terminal window after the installation to apply the changes
-
Test the installation by opening a new terminal window and typing:
nuensis -h
Warning Moving the repo folder will break the paths of the binaries. To avoid this, follow the steps in Moving the
amanuensis
folder.
- Add the Amanuensis Library to Arduino by copying the
AmanuensisLib
folder located insrc/Arduino/
to~/Documents/Arduino
:
- Upload
EEPROM_interface.ino
located insrc/EEPROM_interface/
to your Arduino board.
To see all available options:
nuensis read --help
nuensis write --help
nuensis write --file program.bin
program.bin
should hold its contents in a bytearray. Example of creation of such a file:
#!/usr/bin/python3
rom = bytearray([0xea]*32768)
rom[0x0000] = 0xaa
rom[0x002b] = 0xbb
with open("program.bin", "wb") as file:
file.write(rom)
This results in data 0xaa
stored in address 0x0000
and 0xbb
stored in 0x002b
.
Note Before writing an address, its content is retrieved. If it coincides with the desired value, the write operation is skiped. This is to avoid unnecessary write cycles, which are relatively slow (~10ms).
nuensis write --value 0123 ef # Writes value 0xef to address 0x0123
nuensis write --whole ea # Writes value 0xea in all addresses.
Warning This operation may take a while:
nuensis read --address 0123 # Reads address 0x0123
nuensis read --range 0000 004f # Reads from address 0x0000 to 0x004f
nuensis read --whole # Reads from 0x0000 to 0x7fff
Note EEPROM 28c256 has 15-bit memory registers. They range from 0 (
0x0000
) to 32767 (0x7fff
).
Your laptop connects to Arduino, which drives the EEPROM through the appropriate electric pulses. Depending on the read or write operation, Arduino then passes the information received from the EEPROM back to your laptop.
The pulse cycles needed to drive the EEPROM can be found in the official datasheet of the 28c256 parallel EEPROM.
The shield conveniently maps certain Arduino Mega pins to the correct EEPROM pins. A custom PCB design is available to recreate the shield. Alternatively, the shield can be soldered on a regular protoboard.
The hardware components needed are:
- Custom PCB.
- 28 pin ZIF socket.
- 2x 220 ohm resistors
- 1x red LED, 1x green LED.
- 32x right angle pin headers.
The PCB maps Arduino Mega pins to the ZIF socket where the EEPROM is connected. The Gerber files can be found at pcb/
.
The shield can be crafted on a protoboard as well:
The Shield performs the following pin mapping:
EEPROM | Pin | Arduino |
---|---|---|
Write Enable | WE | 32 |
Output Enable | OE | 52 |
Chip Enable | CE | 29 |
Data 0 | D0 | 49 |
Data 1 | D1 | 41 |
Data 2 | D2 | 39 |
Data 3 | D3 | 35 |
Data 4 | D4 | 33 |
Data 5 | D5 | 23 |
Data 6 | D6 | 25 |
Data 7 | D7 | 27 |
Address 0 | A0 | 47 |
Address 1 | A1 | 45 |
Address 2 | A2 | 51 |
Address 3 | A3 | 50 |
Address 4 | A4 | 44 |
Address 5 | A5 | 46 |
Address 6 | A6 | 48 |
Address 7 | A7 | 40 |
Address 8 | A8 | 24 |
Address 9 | A9 | 26 |
Address 10 | A10 | 53 |
Address 11 | A11 | 28 |
Address 12 | A12 | 38 |
Address 13 | A13 | 32 |
Address 14 | A14 | 36 |
A different mapping might be defined in ./src/Arduino/Amanuensis/Amanuensis.cpp
.
The Command Line Interface (CLI) relies on finding the PATH of the amanuensis
folder, which was set when running install.sh
. Therefore, if the folder is moved around, the CLI commands will fail. To solve it:
- Move the
amanuensis
folder to the new desired destination. - Open
./bash_profile
and delete the entrysource [your-path]/nuensis.sh
- cd to the new folder location and re-run
./install.sh
.
-
Erase all memory contents and set them to a known value, like No-Operation
0xea
:nuensis write --whole ea
-
Create your own
program.bin
as described in Writting a Filenuensis write --file program.bin
-
Check that the contents are what you wanted them to be:
Amanuensis
should work with other parallel EEPROMs as long as they respond to the same read/write pulse cycles as the 28c256 (for example the 28c64):
However, the code might have to be changed to fit your particular EEPROM needs. This is a quick checklist:
- Confirm that the working voltage of your EEPROM is correctly set (in this case, Vcc of 5V is provided by Arduino).
- Revisit the pin mapping, defined in
amanuensis/src/Amanuensis.cpp
. - Set
MAX_ADDRESS
of your EEPROM in./src/ArduinoInterface.py
and in./src/EEPROM_interface.ino
(e.g., for 15-bit addresses,MAX_ADDRESS=32767
).