CircuitPython Code

Dave Astels

Like the hardware, the software is very modular:

  • Overall setup, and control, including handling the rotary encoder
  • A class representing a directory on the SD card with the ability to navigate up and down the tree
  • A class to manage the emulator
  • A helper class to properly debounce the encoder push switch (this is usable for any use of input switches)

Main

Main is simple enough:

  • Initialize things
  • Helper functions
  • Loop, handling the rotary encoder and its switch and using the results to manipulate the current directory node and the emulator
Download: Project Zip or main.py | View on Github 
"""
The MIT License (MIT)

Copyright (c) 2018 Dave Astels

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

--------------------------------------------------------------------------------

EPROM emulator UI in CircuitPython.
Targeted for the SAMD51 boards.

by Dave Astels
"""

import adafruit_sdcard
import adafruit_ssd1306
import board
import busio
import digitalio
import storage
from adafruit_debouncer import Debouncer
from directory_node import DirectoryNode
from emulator import Emulator

# pylint: disable=global-statement
# --------------------------------------------------------------------------------
# Initialize Rotary encoder

# Encoder button is a digital input with pullup on D2
encoder_switch = digitalio.DigitalInOut(board.D2)
encoder_switch.direction = digitalio.Direction.INPUT
encoder_switch.pull = digitalio.Pull.UP
button = Debouncer(encoder_switch)

# Rotary encoder inputs with pullup on D3 & D4
rot_a = digitalio.DigitalInOut(board.D4)
rot_a.direction = digitalio.Direction.INPUT
rot_a.pull = digitalio.Pull.UP

rot_b = digitalio.DigitalInOut(board.D3)
rot_b.direction = digitalio.Direction.INPUT
rot_b.pull = digitalio.Pull.UP

# --------------------------------------------------------------------------------
# Initialize I2C and OLED

i2c = busio.I2C(board.SCL, board.SDA)

oled = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c)
oled.fill(0)
oled.text("Initializing SD", 0, 10)
oled.show()

# --------------------------------------------------------------------------------
# Initialize SD card

# SD_CS = board.D10
# Connect to the card and mount the filesystem.
spi = busio.SPI(board.D13, board.D11, board.D12)  # SCK, MOSI, MISO
cs = digitalio.DigitalInOut(board.D10)
sdcard = adafruit_sdcard.SDCard(spi, cs)
vfs = storage.VfsFat(sdcard)
storage.mount(vfs, "/sd")

oled.fill(0)
oled.text("Done", 0, 10)
oled.show()

# --------------------------------------------------------------------------------
# Initialize globals

encoder_counter = 0
encoder_direction = 0

# constants to help us track what edge is what
A_POSITION = 0
B_POSITION = 1
UNKNOWN_POSITION = -1  # initial state so we know if something went wrong

rising_edge = falling_edge = UNKNOWN_POSITION

PROGRAM_MODE = 0
EMULATE_MODE = 1

current_mode = PROGRAM_MODE
emulator = Emulator(i2c)


# --------------------------------------------------------------------------------
# Helper functions

def is_binary_name(filename):
    return filename[-4:] == ".bin"


def load_file(filename):
    data = []
    with open(filename, "rb") as f:
        data = f.read()
    return data


def display_emulating_screen():
    oled.fill(0)
    oled.text("Emulating", 0, 0)
    oled.text(current_dir.selected_filename, 0, 10)
    oled.show()


# pylint: disable=global-statement
def emulate():
    global current_mode
    data = load_file(current_dir.selected_filepath)
    emulator.load_ram(data)
    emulator.enter_emulate_mode()
    current_mode = EMULATE_MODE
    display_emulating_screen()


# pylint: disable=global-statement
def program():
    global current_mode
    emulator.enter_program_mode()
    current_mode = PROGRAM_MODE
    current_dir.force_update()


# --------------------------------------------------------------------------------
# Main loop

current_dir = DirectoryNode(oled, name="/sd")
current_dir.force_update()
rising_edge = falling_edge = UNKNOWN_POSITION
rotary_prev_state = [rot_a.value, rot_b.value]

while True:
    # reset encoder and wait for the next turn
    encoder_direction = 0

    # take a 'snapshot' of the rotary encoder state at this time
    rotary_curr_state = [rot_a.value, rot_b.value]

    # See https://learn.adafruit.com/media-dial/code
    if rotary_curr_state != rotary_prev_state:
        print("Was: {}".format(rotary_prev_state))
        print("Now: {}".format(rotary_curr_state))
        if rotary_prev_state == [True, True]:
            if not rotary_curr_state[A_POSITION]:
                print("Falling A")
                falling_edge = A_POSITION
            elif not rotary_curr_state[B_POSITION]:
                print("Falling B")
                falling_edge = B_POSITION
            else:
                continue

        if rotary_curr_state == [True, True]:
            if not rotary_prev_state[B_POSITION]:
                rising_edge = B_POSITION
                print("Rising B")
            elif not rotary_prev_state[A_POSITION]:
                rising_edge = A_POSITION
                print("Rising A")
            else:
                continue

            # check first and last edge
            if (rising_edge == A_POSITION) and (falling_edge == B_POSITION):
                encoder_counter -= 1
                encoder_direction = -1
                print("%d dec" % encoder_counter)
            elif (rising_edge == B_POSITION) and (falling_edge == A_POSITION):
                encoder_counter += 1
                encoder_direction = 1
                print("%d inc" % encoder_counter)
            else:
                # (shrug) something didn't work out, oh well!
                encoder_direction = 0

            # reset our edge tracking
            rising_edge = falling_edge = UNKNOWN_POSITION

        rotary_prev_state = rotary_curr_state

        # Handle encoder rotation
    if current_mode == PROGRAM_MODE:  # Ignore rotation if in EMULATE mode
        if encoder_direction == -1:
            current_dir.up()
        elif encoder_direction == 1:
            current_dir.down()

    # look for a press of the rotary encoder switch press, with debouncing
    button.update()
    if button.fell:
        if current_mode == EMULATE_MODE:
            program()
        elif is_binary_name(current_dir.selected_filename):
            emulate()
        else:
            current_dir = current_dir.click()

Directories

The DirectoryNode class provides the ability to navigate a file system. It was written with an SD filesystem in mind, but just relies on the os module so should work with any storage that os uses.

The class provides public properties to get the name and full path of the selected file, as well as methods to force a screen update, move up and down in the displayed list, and do the appropriate thing in response to a selection event (in this case pushing the rotary encoder's switch).

When you create the root level instance, you provide an oled instance to display on, as well as the name of the root (which defaults to "/").

Download: file 
i2c = busio.I2C(board.SCL, board.SDA)
oled = adafruit_ssd1306.SSD1306_I2C(128, 32, i2c)
...
vfs = storage.VfsFat(sdcard)
storage.mount(vfs, "/sd")
...
current_dir = DirectoryNode(oled, name="/sd")
current_dir.force_update()

Use of the DirectoryNode is straightforward as well, We can call up(), down(), and click() in response to activity on the rotary encoder, the DirectoryNode instance takes care of maintaining the display: 

Download: file 
if current_mode == PROGRAM_MODE:      # Ignore rotation if in EMULATE mode
        if encoder_direction == -1:
            current_dir.up()
        elif encoder_direction == 1:
            current_dir.down()

    # look for a press of the rotary encoder switch press, with debouncing
    button.update()
    if button.fell:
        if current_mode == EMULATE_MODE:
            program()
        elif is_binary_name(current_dir.selected_filename):
            emulate()
        else:
            current_dir = current_dir.click()

Notice that the click() method returns a DirectoryNode which is assigned to the current node. That's because clicking could result in moving to a child or parent directory.

Download: Project Zip or directory_node.py | View on Github 
"""
The MIT License (MIT)

Copyright (c) 2018 Dave Astels

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

--------------------------------------------------------------------------------

Manage a directory in the file system.
"""

import os


class DirectoryNode:
    """Display and navigate the SD card contents"""

    def __init__(self, display, parent=None, name="/"):
        """Initialize a new instance.
           :param adafruit_ssd1306.SSD1306 on: the OLED instance to display on
           :param DirectoryNode below: optional parent directory node
           :param string named: the optional name of the new node
        """
        self.display = display
        self.parent = parent
        self.name = name
        self.files = []
        self.top_offset = 0
        self.old_top_offset = -1
        self.selected_offset = 0
        self.old_selected_offset = -1

    def __cleanup(self):
        """Dereference things for speedy gc."""
        self.display = None
        self.parent = None
        self.name = None
        self.files = None
        return self

    @staticmethod
    def __is_dir(path):
        """Determine whether a path identifies a machine code bin file.
           :param string path: path of the file to check
        """
        if path[-2:] == "..":
            return False
        try:
            os.listdir(path)
            return True
        except OSError:
            return False

    @staticmethod
    def __sanitize(name):
        """Nondestructively strip off a trailing slash, if any, and return the result.
           :param string name: the filename
        """
        if name[-1] == "/":
            return name[:-1]
        return name

    # pylint: disable=protected-access
    def __path(self):
        """Return the result of recursively follow the parent links, building a full
           path to this directory."""
        if self.parent:
            return self.parent.__path() + os.sep + self.__sanitize(self.name)
        return self.__sanitize(self.name)

    def __make_path(self, filename):
        """Return a full path to the specified file in this directory.
           :param string filename: the name of the file in this directory
         """
        return self.__path() + os.sep + filename

    def __number_of_files(self):
        """The number of files in this directory, including the ".." for the parent
            directory if this isn't the top directory on the SD card."""
        self.__get_files()
        return len(self.files)

    def __get_files(self):
        """Return a list of the files in this directory.
           If this is not the top directory on the SD card, a
           ".." entry is the first element.
           Any directories have a slash appended to their name."""
        if len(self.files) == 0:
            self.files = os.listdir(self.__path())
            self.files.sort()
            if self.parent:
                self.files.insert(0, "..")
            for index, name in enumerate(self.files, start=1):
                if self.__is_dir(self.__make_path(name)):
                    self.files[index] = name + "/"

    def __update_display(self):
        """Update the displayed list of files if required."""
        if self.top_offset != self.old_top_offset:
            self.__get_files()
            self.display.fill(0)
            min_offset = min(self.top_offset + 4, self.__number_of_files())

            for i in range(self.top_offset, min_offset):
                self.display.text(self.files[i], 10, (i - self.top_offset) * 8)
            self.display.show()
            self.old_top_offset = self.top_offset

    def __update_selection(self):
        """Update the selected file lighlight if required."""
        if self.selected_offset != self.old_selected_offset:
            if self.old_selected_offset > -1:
                old_offset = (self.old_selected_offset - self.top_offset) * 8

                self.display.text(">", 0, old_offset, 0)

            new_offset = (self.selected_offset - self.top_offset) * 8
            self.display.text(">", 0, new_offset, 1)
            self.display.show()
            self.old_selected_offset = self.selected_offset

    @staticmethod
    def __is_directory_name(filename):
        """Is a filename the name of a directory.
           :param string filename: the name of the file
        """
        return filename[-1] == '/'

    @property
    def selected_filename(self):
        """The name of the currently selected file in this directory."""
        self.__get_files()
        return self.files[self.selected_offset]

    @property
    def selected_filepath(self):
        """The full path of the currently selected file in this directory."""
        return self.__make_path(self.selected_filename)

    def force_update(self):
        """Force an update of the file list and selected file highlight."""
        self.old_selected_offset = -1
        self.old_top_offset = -1
        self.__update_display()
        self.__update_selection()

    def down(self):
        """Move down in the file list if possible, adjusting the selected file
        indicator and scrolling the display as required."""
        if self.selected_offset < self.__number_of_files() - 1:
            self.selected_offset += 1
            if self.selected_offset == self.top_offset + 4:
                self.top_offset += 1
                self.__update_display()
        self.__update_selection()

    def up(self):
        """Move up in the file list if possible, adjusting the selected file indicator
           and scrolling the display as required."""
        if self.selected_offset > 0:
            self.selected_offset -= 1
            if self.selected_offset < self.top_offset:
                self.top_offset -= 1
                self.__update_display()
        self.__update_selection()

    def click(self):
        """Handle a selection and return the new current directory.
           If the selected file is the parent, i.e. "..", return to the parent
           directory.
           If the selected file is a directory, go into it."""
        if self.selected_filename == "..":
            if self.parent:
                p = self.parent
                p.force_update()
                self.__cleanup()
                return p
        elif self.__is_directory_name(self.selected_filename):
            new_node = DirectoryNode(
                self.display, self, self.selected_filename)
            new_node.force_update()
            return new_node
        return self

Emulator

The emulator class manages the emulator circuit. Its public interface is simple enough:

  • enter program mode, to allow the RAM to be loaded
  • enter emulation mode, giving control of the emulator RAM to the host
  • load the emulator RAM with data

The load_ram method takes care of the controlling the the address counters and multiplexers. By decomposing into a handful of private methods, the class is quite straight forward:

Download: Project Zip or emulator.py | View on Github 
"""
The MIT License (MIT)

Copyright (c) 2018 Dave Astels

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

--------------------------------------------------------------------------------
Manage the emulator hardware.
"""

import adafruit_mcp230xx
import digitalio

# control pin values

PROGRAMMER_USE = False
EMULATE_USE = True

WRITE_ENABLED = False
WRITE_DISABLED = True

CHIP_ENABLED = False
CHIP_DISABLED = True

CLOCK_ACTIVE = False
CLOCK_INACTIVE = True

RESET_INACTIVE = False
RESET_ACTIVE = True

LED_OFF = False
LED_ON = True

ENABLE_HOST_ACCESS = False
DISABLE_HOST_ACCESS = True


class Emulator:
    """Handle all interaction with the emulator circuit."""

    def __init__(self, i2c):
        self.mcp = adafruit_mcp230xx.MCP23017(i2c)
        self.mcp.iodir = 0x0000  # Make all pins outputs

        # Configure the individual control pins

        self.mode_pin = self.mcp.get_pin(8)
        self.mode_pin.direction = digitalio.Direction.OUTPUT
        self.mode_pin.value = PROGRAMMER_USE

        self.write_pin = self.mcp.get_pin(9)
        self.write_pin.direction = digitalio.Direction.OUTPUT
        self.write_pin.value = WRITE_DISABLED

        self.chip_select_pin = self.mcp.get_pin(10)
        self.chip_select_pin.direction = digitalio.Direction.OUTPUT
        self.chip_select_pin.value = CHIP_DISABLED

        self.address_clock_pin = self.mcp.get_pin(11)
        self.address_clock_pin.direction = digitalio.Direction.OUTPUT
        self.address_clock_pin.value = CLOCK_INACTIVE

        self.clock_reset_pin = self.mcp.get_pin(12)
        self.clock_reset_pin.direction = digitalio.Direction.OUTPUT
        self.clock_reset_pin.value = RESET_INACTIVE

        self.led_pin = self.mcp.get_pin(13)
        self.led_pin.direction = digitalio.Direction.OUTPUT
        self.led_pin.value = False

    def __pulse_write(self):
        self.write_pin.value = WRITE_ENABLED
        self.write_pin.value = WRITE_DISABLED

    def __deactivate_ram(self):
        self.chip_select_pin.value = CHIP_DISABLED

    def __activate_ram(self):
        self.chip_select_pin.value = CHIP_ENABLED

    def __reset_address_counter(self):
        self.clock_reset_pin.value = RESET_ACTIVE
        self.clock_reset_pin.value = RESET_INACTIVE

    def __advance_address_counter(self):
        self.address_clock_pin.value = CLOCK_ACTIVE
        self.address_clock_pin.value = CLOCK_INACTIVE

    def __output_on_port_a(self, data_byte):
        """A hack to get around the limitation of the 23017
        library to use 8-bit ports"""
        self.mcp.gpio = (self.mcp.gpio & 0xFF00) | (data_byte & 0x00FF)

    def enter_program_mode(self):
        """Enter program mode, allowing loading of the emulator RAM."""
        self.mode_pin.value = PROGRAMMER_USE
        self.led_pin.value = LED_OFF

    def enter_emulate_mode(self):
        """Enter emulate mode, giving control of the emulator
        ram to the host."""
        self.mode_pin.value = EMULATE_USE
        self.led_pin.value = LED_ON

    def load_ram(self, code):
        """Load the emulator RAM. Automatically switched to program mode.
           :param [byte] code: the list of bytes to load into the emulator RAM
        """
        self.enter_program_mode()
        self.__reset_address_counter()
        for data_byte in code:
            self.__output_on_port_a(data_byte)
            self.__activate_ram()
            self.__pulse_write()
            self.__deactivate_ram()
            self.__advance_address_counter()
AN ASIDE: THE OCTAL 3-STATE BUFFERS Series Index
This guide was first published on May 14, 2018. It was last updated on May 14, 2018. This page (CircuitPython Code) was last updated on Jan 28, 2020.