Demo Videos

Before I get into some of the more technical details, I want to show some video captures of the emulator running. And if you happen to find yourself thinking that it looks like something you’d want to play with, I’m releasing it all as open source. There will be some links later in the post where you can download the emulator, and for the ambitious, all the files needed to build your own hardware ApOPL3xy are available as well.

VGM Player

One of the most iconic pieces composed for the OPL3 is “At Doom’s Gate,” the music for the first level (Episode 1 Mission1, or E1M1) of Doom. vgmrips.net has the VGM capture of this song available for download, and I can’t think of a better song to demonstrate the VGM player feature. Note that most, if not all, VGM files only use the first two output channels, since no 4-channel OPL3 sound cards were commonly available.

The numbered buttons below the display correspond to the colored buttons on the hardware, and the two groups of three buttons, labeled ↺, ↻, and ☟, represent the rotary encoders being turned counter-clockwise, turned clockwise, and pressed like a button, respectively. At some point, I may improve these to be a more skeuomorphic control, but the buttons get the job done.

MIDI Player

My last post showed the new MIDI file player feature on the hardware ApOPL3xy, but due to difficulties filming the backlit LCD screen, it wasn’t easy to see what was on the display. The next video shows the emulator playing a MIDI version of the Doctor Who theme music. As before, I arbitrarily assigned MIDI channels to output channels to make the VU meters a bit more interesting.

Loop Controls

Between the last post and this one, I added loop controls to both the VGM and MIDI players. It’s a small feature, but potentially useful. The loop indicator is just to the left of the total time in the player interface. It starts out as a right-pointing arrow, meaning no loop. The other loop modes are single loop, represented by an arrow that curves from the right to the left, and continual loop, represented by two arrows pointing at each other’s tail. The 5 button cycles through these modes.

This video demonstrates the single loop mode being used for a MIDI file with a version of the Pac-Man music. It also shows the page down menu navigation function, which is mapped to button 9.

MIDI Input

My primary motivation for building the ApOPL3xy was to enable MIDI input to control an OPL3 chip. So far, I’ve demonstrated playback functionality, but I want to show the live MIDI capability as well. Unfortunately, I’m not very skilled at the piano, so I just play a few scales in the following video. The piano keyboard in the video is an open source tool called VMPK (Virtual MIDI Piano Keyboard), which I did not write, but am simply using.

The video shows selecting a MIDI input source for the emulator and using the Channel Editor feature to show the patches assigned to MIDI channels. Then, a few scales are played using a few different patches.

MIDI Output

The ApOPL3xy also has a MIDI output port, which sends MIDI messages from the MIDI player to an external device. It also optionally echoes messages received from the MIDI input port, but that echoing is not demonstrated here. What is demonstrated is using VMPK as an external device to visualize the notes being played. In this video, VMPK is configured to display each MIDI channel with a different color. The MIDI file being played is the battle music from Final Fantasy VII.

Implementation Details

The ApOPL3xy firmware interacts with several pieces of hardware, all of which need to be emulated to be able to run the firmware purely in software.

Microcontroller

The hardware ApOPL3xy has an ATmega1284p microcontroller to run the firmware. Because the main goal of the emulator is to support debugging, this microcontroller is not emulated. Instead of running the compiled AVR firmware on an emulated ATmega1284p, the firmware is recompiled to native code for the computer running the emulator, with some conditionally-compiled hooks in a few places to tie in the other emulated hardware.

OPL3

This is probably the most important piece of hardware to emulate, and also the most daunting. Fortunately, the open source project DOSBox has code to emulate the OPL2 and OPL3 chips, so I adapted it for my use. This code exposes a function to set registers on the emulated OPL chip, which I used instead of the SPI interface I built for the hardware ApOPL3xy for that purpose. The DOSBox code also exposes a function to get output audio samples, which I used to populate the audio buffers (more on this later).

The OPL3 supports up to 4 channels of audio output, but sound cards incorporating the chip rarely if ever used more than 2. DOSBox didn’t bother implementing support for channels 3 and 4, so I modified it to add that support. It was actually easier than I expected. Since they had already gone to the trouble to implement 2 channels, most of the work involved increasing some array sizes and loop bounds from 2 to 4.

LCD Character Display

The standard 20×4 LCD character display used by the ApOPL3xy is based on a driver chip called the HD44780. I broke the emulation of this device up into two parts: the HD44780 emulation and the drawing of the LCD panel itself.

The HD44780 supports several commands which are sent by writing to its control and data registers. To emulate this chip, I wrote a C++ class to represent all of its internal registers, RAM, and ROM, and then implemented each command as a separate function that operates on the internal state. I then implemented a wrapper function which accepts commands or data, and dispatches to the correct underlying function(s). This is called by the emulated firmware instead of using SPI, similar to the OPL3.

For the HD44780 emulation, I also wrote a function to retrieve the output state, e.g., which pixels are on and which are off. This is used by the LCD panel emulation to actually display the pixels. I used the open-source, cross-platform GUI library wxWidgets to implement the emulator’s GUI, and the LCD panel is implemented as a custom widget that does its own drawing with the graphics routines provided by the library.

Audio Output

To implement audio output for the emulator, I used the open-source, cross-platform library PortAudio. This library abstracts all the platform-specific audio APIs and presents a unified interface to interact with the audio system. With it, the emulator is able to select audio output devices, sample rate, latency, and number of channels. (These options are exposed to the user via the Audio Settings dialog window.) To play the synthesized audio, the emulator extracts audio samples from the emulated OPL3 and sends them to the host audio system using PortAudio’s interface.

VU Meters and Gain Controls

Each output channel on the physical ApOPL3xy has a VU meter (well, not a true VU meter, just a linear amplitude display) and a gain control. Emulating this in wxWidgets was pretty straightforward. These are in separate tool windows that the user can display and dismiss.

The gain controls are slider widgets. To implement gain, the emulator reads the values from the sliders and uses them to adjust the audio samples before sending them to PortAudio for playback.

The VU meters are custom widgets that draw themselves based on a given amplitude. The emulator determines the current amplitude of each channel from the audio samples before sending them to PortAudio, and sends the amplitude values to their respective VU meter for display.

MIDI Input and Output

To emulate the MIDI input and output ports, I used the open-source, cross-platform library RtMidi. This library abstracts the host computer’s MIDI system, and enables enumeration of, reading from, and writing to system MIDI ports. The MIDI In and MIDI Out dialogs allow the user to select which, if any, MIDI ports to read from and write to.

If a MIDI input port is selected, MIDI events are read from it and injected into the firmware’s MIDI queue, instead of reading from the microcontroller’s serial interface. Similarly, instead of writing output MIDI events to the microcontroller’s serial interface, the emulator writes them to the host MIDI port selected for output.

MicroSD Card

The hardware ApOPL3xy includes a MicroSD card reader, which is read by the firmware using the open-source SdFat library. This library abstracts both the SPI messaging needed to interact with the card itself, as well as handling the FAT filesystem that keeps track of which files are where in the card’s storage.

To emulate this, I wrote a mock implementation of the subset of SdFat’s interface that the firmware uses, but instead of accessing an SD card, it uses the standard C++ std::filesystem library to access the host’s filesystem through the host OS. The user can “insert” a virtual SD card by using the Mount SD Card dialog window to select the directory to serve as the root directory of the virtual card. The user can “eject” a virtual SD card by using the Unmount SD Card menu option.

SRAM and EEPROM

The ATmega1284p microcontroller has 16 kiB of RAM and 4 kiB of EEPROM storage built in. This isn’t enough for everything I wanted the ApOPL3xy to be able to do, so I added SPI SRAM and EEPROM chips (128 kiB each) to the design. The SRAM on the microcontroller itself doesn’t need to be emulated; the emulator just uses the host’s system RAM for that. The microcontroller’s EEPROM isn’t used by the firmware at all, so that doesn’t need to be emulated either. The add-on chips, however, do need to be emulated.

The SRAM chip was very simple to emulate. I simply allocated an array of the right size and provided functions to read from and write to it. The emulator uses these functions instead of sending SPI commands like the firmware does on physical hardware. The EEPROM was very similar, except that a file is used instead an in-memory array, since EEPROMs are nonvolatile.

If the emulator finds no EEPROM file in the expected location on startup, it generates a default one and uses that. This has turned out to be useful for setting up a hardware ApOPL3xy. Since the format of the EEPROM is identical between the emulator and the hardware, one can copy the EEPROM file from the emulator to a MicroSD card and load it onto the hardware.

Input Controls

The ApOPL3xy has 10 buttons and 2 rotary encoders (which can also act as buttons) which are used to navigate menus and issue commands. The hardware version of these are connected to a shift register, which the firmware reads via SPI, interprets, debounces, and adds to an input event queue. The emulator instead provides GUI buttons for these, and pressing a button injects an input event directly into the queue. These buttons are also mapped to (hopefully) intuitive keyboard shortcuts.

Miscellaneous

There were a few other things that needed to be replaced or mocked to be able to compile and run the firmware in an emulated context.

• The microcontroller framework used by the ApOPL3xy’s firmware provides functions for timing that use the microcontroller’s on-chip timers. These were replaced with versions that use the standard C++ std::chrono library instead.
• The AVR architecture used by the ATmega1284p requires the use of special functions to read data out of program code (e.g. constant string data) instead of SRAM. These were replaced with simple pass-through functions, since the host machine for the emulator doesn’t have this restriction.
• Various utility functions like min() and max() provided by the framework needed to be reimplemented.

Download Links

Emulator

If you’re interested in trying out the ApOPL3xy emulator, you can download pre-compiled binaries here:

• ApOPL3xy Emulator v1.0.1 (Windows)
• ApOPL3xy Emulator v1.0.1 (MacOS)
• ApOPL3xy Emulator v1.0.1 (Ubuntu 24.04)
• ApOPL3xy Emulator v1.0.1 (Fedora 42)

Note that on Windows and MacOS, the fact that this binary isn’t signed may cause the operating system to complain. To get past this on MacOS, see https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unknown-developer-mh40616/mac. Microsoft doesn’t seem to have a good page on this, but here’s a potentially helpful google search.

Music Files

Here are some music files that you can play using the ApOPL3xy:

• VGM Files
• MIDI Files

Source Code

The combined source code for the emulator and firmware is available below. It’s released under the terms of the MIT License, except for the OPL emulation code from DOSBox, which is released under the LGPL 2.1 license. I’ll probably post this to github at some point, but the code is a bit messy at the moment, and I might like to clean it up first.

• ApOPL3xy Emulator and Firmware v1.0.1 (Source Code)

Hardware Design Files

If you’re interested and brave enough to want to build your own hardware ApOPL3xy, here are the files you’ll need. Note that the documentation is rather lacking at the moment, but I think someone determined enough could figure it out. If you try and have difficulties, let me know and I’ll be happy to help.

• ApOPL3xy PCB rev3 (Gerbers)
• ApOPL3xy PCB rev3 (Bill of Materials)
• ApOPL3xy PCB rev3 (Schematic)
• ApOPL3xy PCB rev3 (KiCad Design Files)
• ApOPL3xy Firmware v1.0.1 (HEX File)
• ApOPL3xy EEPROM Image v1.0.1 (BIN File)
• ApOPL3xy User Manual v1.0.1 (PDF File)

Closing Thoughts

I’m quite pleased with how this project turned out. What began as an attempt to make debugging easier grew into something kinda cool on its own. It also enables me to share the ApOPL3xy with more people than I would have otherwise. If you do try it out, I’d love to hear what you think. I have my own ideas of what could be improved, but there’s no substitute for real user feedback.

MIDI Player

One of the things I’ve added to the firmware recently is the ability to play MIDI files from the SD card. Here are a few videos of this in action. These videos are a little dark. It was hard to find a balance between blowing out the display and making the videos way too dark, so I did the best I could. I mapped the MIDI channels to somewhat arbitrary output audio channels to make the VU meters a little more interesting.

PCB Photos

Here are some high(ish) resolution photos of the assembled Rev 3 board, for those who are into that sort of thing. Also included is a photo of the bodges necessary on the Rev 2 board. To view the images at full resolution, right-click (or long-press) the image and select “Open Image in New Tab ” or similar.

Future Work

Now that the ApOPL3xy has reached this milestone, I’ll probably leave it alone for a while. But, such things are never truly finished. I have several ideas for user interface improvements, such as patch and bank copying, M3U playlist support, and most interesting to me, a drum machine mode (suggested by a co-worker). I’m sure I’ll come back to this eventually to make these and other improvements, but it sure feels good to be able to call it done (for now)!

Microcontroller

The microcontroller that drives the system is the Microchip ATmega1284. (It used to be made by Atmel, before Microchip bought them.) The ATmega1284 is an 8-bit AVR microcontroller, similar to but more powerful than the ATmega328P at the heart of the Arduino Uno R3.

Hardware

Chips in the AVR line of microcontrollers have integrated flash memory for storing programs, SRAM for program variables and stack, and an EEPROM for non-volatile data storage. Most have hardware implementations of several communication protocols, such as SPI, I²C, and TTL Serial (basically RS-232 but with different voltage levels).

Whereas the ATmega328P has 32 kB of flash, 2 kB of SRAM, and 1 kB of EEPROM, the ATmega1284 has 128 kB of flash, 16 kB of SRAM, and 4 kB of EEPROM. I had initially designed the ApOPL3xy around the ATmega328P, but soon found the memory constraints too limiting, especially the 2 kB of SRAM. So, I upgraded to the ATmega1284. 128 kB of program flash and 16 kB of on-chip SRAM should be more than enough for the initial version, and leave plenty of room for future expansion.

The microcontroller in the ApOPL3xy runs at 5V and 20 MHz. A quartz crystal is used to generate the clock signal. 20 MHz is the maximum clock frequency for which the ATmega1284 is rated, and so far, it seems to be sufficient.

Programming

Arduino boards each have a USB port connected to a USB-to-serial bridge chip, which is used by special bootloader code on the microcontroller to receive new program code, so that all one needs to program an Arduino is a USB cable. When using a bare microcontroller as the ApOPL3xy does, the way to program it is ISP (In-circuit Serial Programming), sometimes called ICSP. This uses the SPI bus to upload code to the microcontroller (configured as the slave). However, to do this, one needs a separate device to act as the SPI master and upload the code to the microcontroller. I’m using the AVRISP-mkII programmer for this project. There are many others, but I have read that some of them have trouble with chips that have more than 64 kB of flash. I have, so far, not had any problems with the AVRISP-mkII, but note that the compiled firmware is still less than 64 kB in size, so that’s not entirely conclusive.

I’m using the PlatformIO IDE to edit, compile, and upload code to the microcontroller. This could be done with the official Arduino IDE as well (with the MightyCore board definitions added), and I was doing it that way for a while. However, the Arduino IDE is not very developer-friendly for large projects, and it makes simple things like having multiple source files much more difficult than they should be. PlatformIO, on the other hand, is much easier to use and I find myself fighting with it much less than with the Arduino IDE. PlatformIO is a Visual Studio Code extension, so you’ll need that installed, but it’s cross-platform, supports a large number of microcontrollers, and can use libraries written for the Arduino IDE. In theory, it even supports debugging over JTAG if the chip supports it. I haven’t tried that yet, but the ATmega1284 does claim to support it. PlatformIO is still a tad rough around the edges, but it’s so much better than the Arduino IDE experience that I highly recommend it.

Peripheral Devices

The ApOPL3xy has several peripheral devices attached to the microcontroller. “Peripheral” here means that the device is separate from the microcontroller chip, not necessarily that it’s detachable from the circuit board. Each of these peripherals communicates with the microcontroller using the SPI protocol. The one exception to this is the MIDI input port, which communicates using TTL Serial and is therefore connected to one of the microcontroller’s USART (i.e. hardware serial) interfaces.

The ApOPL3xy contains the following peripheral devices:

• OPL3 FM synthesis chip (Yamaha YMF262)
• 20×4 LCD character display module (with Hitachi HD44780-compatible controller)
• Input controls
  • 2 EC11 incremental rotary encoders
  • 10 tactile push buttons
• MicroSD card module
• 128 kB SRAM (Microchip 23LCV1024)
• 128 kB EEPROM (Microchip 25AA1024)
• MIDI 5-pin DIN input port
  • I’m thinking about adding a MIDI thru port as well
• Reset button

Reset Circuit

The reset button is connected to the reset pins of both the ATmega1284 and the OPL3. Since this signal is not being handled by a GPIO pin, software debouncing is not really an option. I also wanted the reset signal to start out active, so that the chips connected to it would be reset at power on. So, I designed a simple RC (resistor-capacitor) circuit, with its analog output converted to digital by means of two gates from a 74HC14 (six Schmitt-trigger inverters).

The reset signal for both chips is active low (as it is for most chips with a reset pin), so the way this circuit works is as follows. One lead of a 10 μF capacitor is connected to GND (0V), so the other lead starts out at 0V as well. The second lead is connected to V_CC (+5V) through a 10kΩ resistor and a 1kΩ resistor in series, so the capacitor gradually charges to +5V over time. After about 60 ms, the voltage at the second lead becomes high enough to trigger the first inverter, which goes low, and then the second inverter goes high, deactivating the reset signal.

When the reset button is pressed, it connects the second lead of the capacitor to ground through just the 1kΩ resistor, allowing it to discharge quickly, bringing the reset signal low (active). The signal stays low until the reset button is released, at which time, it takes about another 60 ms for the capacitor to charge up enough to bring the reset signal high again. If the button bounces when pressed, that high frequency oscillation is filtered out by the slow-charging capacitor, which is acting as a low-pass filter.

Here are a couple of captures from my oscilloscope illustrating the behavior of the circuit. In these images, the yellow trace measures the voltage across the capacitor, the pink trace measures the output of the first inverter, and the blue trace measures the output of the second inverter, which is the reset signal itself. The first image shows the behavior as the system is powered on. You can see the capacitor charging and how the schmitt-trigger inverters react to it.

The second image shows the behavior when the reset button is pressed. In this capture, you can see the capacitor quickly discharging as soon as the button is pressed, and remain discharged until the button is released, then start slowly charging again.

Custom SPI Interface

Three of the peripherals (MicroSD, SRAM, EEPROM) connected to the microcontroller natively communicate using SPI. The others do not, but in order to conserve GPIO pins, I built an SPI interface for them (except for the MIDI port) using shift registers. In a recent post, I described how this works in more detail. I could have used something a bit fancier, like the Microchip MCP23S17 SPI I/O expander. But they’re more expensive and more proprietary than standard 74HC shift registers, and the shift registers work just fine.

The SPI interface is built from one 74HC595 (serial-in / parallel-out shift register), two 74HC165‘s (parallel-in / serial-out shift registers), and one gate each from a 74HC14 and a 74HC125 (four tri-state buffers). I could have used a 74HC04 instead of a 74HC14, as I’m not using the Schmitt trigger functionality, but I already had a 74HC14 in the design for the reset button circuit, and I wasn’t using all of its gates. This setup provides eight output pins and sixteen input pins, and uses only three of the microcontroller’s pins. Two of these pins, SCK and MOSI, are shared among all SPI devices, so this really only uses one extra pin: SS.

Since the LCD character display and the OPL3 sound chip are controlled independently from one another, I was able to use the same eight output pins from the 74HC595 for both, and so they’re connected to each of these peripherals’ data busses. The sixteen input pins are connected to the two rotary encoders (three pins each) and the ten push buttons (one pin each).

OPL3 FM Synthesis Chip

If the ATmega1284 is the heart of the ApOPL3xy (and if you’ll forgive my briefly waxing poetic), then the Yamaha YMF262 (a.k.a. OPL3) is its soul. Well, perhaps brain and larynx would be a better metaphor; it just doesn’t have the same ring. But I digress…

The OPL3 is a sound synthesizer chip that implements frequency modulation (FM) synthesis. It was used in Creative Labs’ popular Sound Blaster 16 sound card released in 1992 for IBM-compatible PC’s, and many PC games of that era used it to produce their in-game music.

FM Synthesis

FM synthesis is a method of producing sound waves by combining simpler waves. The basic sound-producing unit in a synthesizer is the oscillator. An oscillator takes a few parameters: frequency/pitch, amplitude/volume, and waveform, and produces the sound wave with those characteristics. In the OPL line of synthesizer chips, and often with FM in general, oscillators are referred to as operators. The reason for this is the way FM synthesis uses oscillators.

Each voice, or independently controlled sound source, in FM is built from two or more oscillators. However, usually only one of these oscillators, called the carrier, actually produces sound. The other oscillators, called modulators for reasons which will soon be apparent, modulate the carrier by adjusting the carrier’s frequency up or down based on the amplitude of the waveform produced by the modulator. This can produce a wide variety of sounds, many of which approximate different musical instruments fairly well. With more than two oscillators, there may be multiple carriers sounding at once, and/or multiple modulators, modulating carriers or even other modulators. The reason FM oscillators are often called operators is that they operate on each other in this way.

The OPL3 contains thirty-six operators, which are paired together to provide eighteen independent two-operator voices. Up to six pairs of voices can be combined to create four-operator sounds, at the cost of a corresponding decrease in the number of simultaneous voices. If percussion mode is enabled, three two-operator melodic voices are exchanged for five percussion voices—one two-operator voice and four one-operator voices, for a total of twenty independent voices. (One-operator voices are not technically FM, since there’s no modulation happening, but they can be produced by the OPL3.)

Microcontroller Interface

The microcontroller interface to the OPL3 consists of a chip select pin (CS), a write enable pin (WR), a read enable pin (RD), two address pins (A0, A1), eight data pins (D0–D7), an interrupt request output pin (IRQ), and a reset pin (IC, or Initial Clear). To control the behavior of the synthesizer (e.g. play a note, adjust sound settings, etc.), the microcontroller uses these pins to set the value(s) of one or more registers within the chip. I won’t go into detail about the specific registers and their values, because the unofficial OPL3 Programmer’s Guide has already done an excellent job of that. They’re also described in the datasheet, but I find that does a rather poorer job.

To set a register, the microcontroller first needs to set the CS pin low (if it’s not already) to select the chip, the A0 pin low to indicate it’s selecting a register, the A1 pin either high or low to select one of the two banks of registers, and the D0–D7 pins to the index of the register to set. The WR pin is then pulsed low then high to write the register index. Next, A0 is set high to indicate the register’s value is being set, and D0–D7 are set to the new value for the register. The WR pin is once again pulsed low then high, this time to write the register value. Finally, if the microcontroller is done setting registers, it can set the CS pin high to deselect the chip.

The ApOPL3xy connects the OPL3’s pins as follows. CS is connected to GND to permanently select the chip. A0, A1, IC, and WR are connected to individual GPIO pins on the ATmega1284, configured as output pins. (A0 actually shares a GPIO pin with the LCD module’s RS pin.) D0–D7 are connected to the eight shared output pins from the custom SPI interface built from shift registers. This pin sharing works because the OPL3’s WR is only brought low (active) when any other device using the shared pins is inactive. When WR is high, the OPL3 doesn’t care what the values of the address and data pins are (except for setup and hold times, but those are so short that, even at 20 MHz, it’s hard to violate them; see the datasheet for more details on that).

The IRQ and RD pins are rarely used. The OPL3 can generate timer interrupt signals on the IRQ pin to let the microcontroller know when a certain amount of time has elapsed, and the RD pin is only able to be used to get information about these interrupts. The Sound Blaster 16 did not use this feature, nor does the ApOPL3xy. Therefore, the ApOPL3xy connects the RD pin to V_CC to permanently disable reads, and leaves the IRQ pin disconnected.

Digital-to-Analog Conversion

The OPL3 doesn’t generate sound directly. Rather, it produces digital representations of waveform amplitude (called samples) at a rate of 49,716 samples per second. The samples are represented as 16-bit offset binary numbers, where 0 represents the most negative value, and 65,535 represents the most positive value. These samples are sent serially to a Digital-to-Analog Converter (DAC) chip, the YAC512, which was designed as a companion chip to the YMF262.

The YAC512 takes the digital samples and converts them to an analog waveform which can be sent to an amplifier and then to a loudspeaker. Each YAC512 supports two audio channels, and the YMF262 can connect to two YAC512’s, giving four audio channels. Each of the OPL3’s voices can be configured to be output to any combination of the four audio channels.

LCD Character Display Module

This is a pretty standard component for a lot of homebrew projects. It’s a twenty-column by four-row character display module with an LED backlight and an integrated controller (Hitachi HD44780). It also comes in a sixteen-column by two-row variety, but I wanted the little bit of extra space afforded by the larger module. Ben Eater has an excellent video (to be honest, all of his videos are excellent) in which he connects a 16×2 version to his 65C02-based breadboard computer. The datasheet for the HD44780 is surprisingly good, and details all of the instructions that can be sent to the module.

The microcontroller interface consists of eight data pins (D0–D7) and three control pins: enable (E), register select (RS), and read/write (RW). There are five other pins, two for power, two for backlight power, and one to set the contrast of the display, for a total of sixteen pins, but only eleven need to be connected to the microcontroller.

To send instructions to the LCD module, a microcontroller first needs to set RW low, to signal a write, and RS low, to signal an instruction. Next, D0–D7 are set to the instruction to send, and finally E is pulsed high then low to send the command. Sending data (i.e.characters) follows the same process except that RS is set high to signal data rather than an instruction, and D0–D7 are set to the ASCII value of the character to send.

The LCD module also supports a four-bit mode, in which only D4–D7 need to be connected. This would be one way to conserve GPIO pins, but the ApOPL3xy doesn’t take this approach. This mode takes twice as long to send instructions and data. Because each instruction and character is still eight bits, each one takes two cycles to send. However, the main reason the ApOPL3xy uses the eight-bit mode is that it simplifies the code to do so, and the GPIO pressure is dealt with another way (see below).

Character data can be read back out of the LCD module, if desired, by setting RS and RW high, pulsing E high then low, and reading the value of D0–D7. There is also a “busy” flag which can be read by setting RS low, setting RW high, pulsing E high then low, and reading the value of D7. The busy flag indicates that the HD44780 is still processing the last instruction it received.

If an instruction is sent while the busy flag is high, the instruction will not execute, and the HD44780 will take longer to complete its current action, so this should be avoided. However, the datasheet lists the maximum duration for each instruction, so another way to avoid this situation is simply to wait long enough between instructions. This can be slightly slower, but the longest delay needed is about 1.5 ms, and most are less than 50 µs, so it’s not terrible, and it simplifies the connections if reading doesn’t need to be supported. Therefore, this is the approach the ApOPL3xy takes.

The ApOPL3xy connects the LCD module’s pins as follows. RS and E are connected to GPIO pins on the ATmega1284, configured as outputs. (RS shares a pin with the OPL3’s A0 pin.) D0–D7 are connected to the eight shared output pins from the custom SPI interface built from shift registers. As with the OPL3, this pin sharing works because the LCD’s E pin is only brought high when any other device using the shared pins is inactive. When E is low, the LCD doesn’t care what the values of RS, RW, and D0–D7 are.

Some readers might be wondering whether the ApOPL3xy uses the Arduino LiquidCrystal library to control the LCD module, and if not, why not. The ApOPL3xy doesn’t use this library because the library expects all of the LCD’s pins to be connected directly to the microcontroller’s GPIO pins, and that’s not how the module is connected in this case. To do so would have used more GPIO pins than I would have liked. The LCD control code in the ApOPL3xy’s firmware has an API modeled after LiquidCrystal, because it has a decent design, and because that might be more familiar to some developers.

Input Controls

The user interface for the ApOPL3xy consists of the LCD character display module previously discussed, and a number of input controls. Specifically, two EC11 rotary encoders, and ten momentary tactile push buttons. Each encoder has three output pins, and the ten push buttons have one each, for a total of sixteen. These outputs are connected to the sixteen inputs provided by the 74HC165’s in the custom SPI interface.

The shift registers in the SPI interface are part of the reason there are so many buttons. With six inputs needed for the two encoders, a single 74HC165 would only provide enough inputs for two more buttons. I felt that this wouldn’t be enough, so I added another 74HC165 with another eight inputs. Rather than let some of them go unused, I connected a button to each of them, for a total of ten. At present, the firmware only uses five of the buttons, but I’m sure I’ll be able to find uses for the others.

The buttons each have two pairs of pins, but the pins in each pair are shorted together, so there are effectively only two pins per button. I believe, but I’m not 100% certain, that the redundant pins are there to provide structural support when soldered to a circuit board. While the button is pressed, all four pins are shorted together.

EC11 rotary encoders are knobs that can be turned in arbitrarily many discrete steps in either direction, unlike a potentiometer, which turns continuously, but has limited extents. The encoders send a signal for each clockwise and counter-clockwise step, and they also serve as push buttons when pressed. If you’re curious to know how these work in more detail, check out my recent post on the topic.

These controls are all wired up in the ApOPL3xy to produce active-low signals. This means that each shift register input pin sees a low signal while, for example, the connected button is pressed, and a high signal otherwise. I don’t have a strong reason for making the controls’ outputs active-low rather than active-high. It would have worked just as well the other way.

The ApOPL3xy deals with the problem of contact bounce by applying a software debouncing algorithm. This algorithm acts as a state machine which only transitions states after a configured minimum time is spent in each state. In this case, the states are (effectively) idle, idle wait, active, and active wait. The wait states are the ones that require minimum durations before transitioning to its non-wait counterpart. If there’s interest, I could make another post going into detail about the various hardware and software debouncing solutions, and the pros and cons of each.

MicroSD Card Module

The ApOPL3xy includes a MicroSD card module to allow it to read VGM (and eventually MIDI) files for playback, as well as to load and save data to and from the EEPROM. I’m looking into the possibility of using a bootloader for the ATmega1284 that can load new firmware from the SD card, so an ISP programmer wouldn’t be required, but my investigation into that is not yet complete.

The MicroSD module I’m using was meant for Arduinos. It’s a small board with a slot for the card, a pin header to connect to the microcontroller, and a few extra components to shift voltage levels between the 5V the microcontroller uses and the 3.3V that the card uses. I may, in some future version of the ApOPL3xy, ditch the separate module and just incorporate a card slot and a level shifter chip directly. The card itself contains all the circuitry needed for the actual control and data interface, so it would be relatively straightforward. The module is convenient however, so that’s what I’m using for now.

SD (and MicroSD) cards natively use a four-bit parallel protocol, and that’s the way most modern devices (e.g. computers, smartphones, etc.) talk to them. Using this mode enables the highest transfer rates that the card can support. However, these cards also provide an SPI interface, which is how most smaller microcontrollers, including the ApOPL3xy, talk to them. This method is slower, but still fast enough for how the ApOPL3xy uses the card, it’s supported in hardware by the microcontroller, and it only uses up one additional GPIO pin for the SPI SS signal.

One issue I ran into is that SD cards are not particularly well-behaved when it comes to SPI. Specifically, the cards don’t seem to release the MISO line when its SS line is brought high, interfering with all the other devices on the SPI bus. At least this is the case with the module I’m using, but I believe this is a general phenomenon. To fix this, I used a 74HC125 tri-state buffer chip to disconnect the SD card’s MISO line when its SS line is high. In fact, I already had a 74HC125 with unused gates in the circuit, because I needed to do the same thing with the 74HC165 shift registers as well.

The SPI interface to the SD card provides raw read/write access to the bytes stored on the card. However, that’s not really sufficient to be able to read and write files on the card. At least, not if the card needs to be able to be read and written by other devices as well. Most storage devices, including SD cards, organize the large amount of data stored on them by using a filesystem. Filesystems keep track of file metadata like filenames and file size and provide controllers with a way to work with files instead of just raw data.

The topic of filesystems is vast, and well outside the scope of this article, but a common filesystem used on SD cards is called FAT32. FAT32 was developed by Microsoft for Windows 95, as an extension to their earlier filesystems FAT16 and FAT12, developed for MS-DOS. FAT32 has become a de facto standard for removable media, as its relative simplicity compared to other filesystems has enabled many different computer operating systems and embedded systems to implement support for it. This is slowly being superseded by Microsoft’s more modern exFAT filesystem, but support for this is still far from ubiquitous.

The ApOPL3xy expects its SD card to be formatted with the FAT32 filesystem, and rather than implementing a FAT32 filesystem driver from scratch, it makes use of the SdFat library. This library takes care of both the low-level SD card interface for handling raw data and the FAT32 filesystem interface. It’s been in development for many years, and at the time of this writing, is still in active development. It manages to pack a tremendous amount of capability into a surprisingly small amount of space, and does so very efficiently. It even has optional support for exFAT, but ApOPL3xy doesn’t enable that, at least not yet.

External SRAM and EEPROM

Even though the ATmega1284 has much larger memory capacities than the ATmega328P, it’s still not enough to store as many synthesizer patches (i.e. sound settings to emulate various instruments) as I want to be able to. Each patch for the OPL3 (at least as I have currently implemented it) is 23 bytes, plus a 24-byte name string, giving 47 bytes per patch. The General MIDI specification includes 128 melodic instruments, and 61 percussive instruments, for a total of 189 * 47 = 8,883 bytes, more than half of the available SRAM space, and more than double the available EEPROM space. Furthermore, I’d eventually like to be able to store and select from multiple banks of patches.

To deal with this, the ApOPL3xy includes an external (i.e. not part of the microcontroller) SRAM chip (Microchip 23LCV1024) and an external EEPROM chip (Microchip 25AA1024), each with 128 kB of space. These chips, like most of the other peripherals in the ApOPL3xy, communicate via the SPI protocol. The specific details of the command interface can be found in the datasheets for these chips, but the basic structure for both chips is: write a command byte (i.e. “read”, “write”), write a three-byte address, then read or write as many bytes as desired. Because these chips hold 128 kB of data, only seventeen bits are needed to encode an address, and the seven most significant bits of the three-byte address are ignored.

Writing to the EEPROM is slightly more complicated. Its storage is organized into 256-byte pages, and each write operation can only modify a single page. To write to multiple pages, multiple write operations must be performed. To write to a page, first the status register must be checked to ensure that the chip has completed its last operation. Then a “write enable” command byte must be sent, then the chip select line must be brought high and then low before the “write” command is sent, followed by the 3-byte address, followed by up to 256 bytes of data. Once the last byte of the page is written, the chip select is brought high, and the cycle is repeated for any additional pages.

MIDI Port

The ApOPL3xy uses the MIDI protocol to allow an instrument (like a keyboard) to control the FM synthesis chip. MIDI is a fairly straightforward protocol, and the electrical interface is reasonably simple to implement. The MIDI port itself is a female 5-pin DIN jack, and there are a few other components, such as an optocoupler and a few resistors to provide isolation and level-shifting. The data signals transmitted via this port are essentially RS-232 serial signals, at 31,250 baud with eight data bits, one stop bit, and no parity bits per frame. The USARTs built into the ATmega1284 can directly process this kind of signal, so the data line from the MIDI-In port is connected to one of these.

At present, the breadboard version of the ApOPL3xy includes a single port for MIDI-In, but I will likely add a MIDI-Thru port as well. MIDI-Thru ports are ports which simply output whatever signals came in on the MIDI-In port. They’re also pretty simple electrically, and require no software support in the microcontroller, so it’s probably worth adding one, just in case it turns out to be useful.

Conclusion

This covers almost all of the hardware used in the ApOPL3xy. I did leave out the amplifier circuits, because I’m still fiddling around with their design. Once I sort that out to my satisfaction, I’ll likely make another post about that. As always, I hope this has been interesting and informative. Let me know if anything is unclear, or if you’d like more detail on anything in particular.

EC11’s look similar to potentiometers, but they’re very different devices. A potentiometer turns smoothly through a limited range of motion, but an EC11 turns in discrete steps, and its range of rotation is unlimited. A potentiometer is a variable resistor divider, but an EC11 has nothing to do with resistance. Instead, when it rotates, it produces signals that indicate the direction of rotation. EC11’s can also function as push buttons.

As a side note, I’m not sure why they’re called “EC11” encoders. My web search on this topic has turned up nothing useful. I’ve also seen references to EC12 and EC16 encoders, that presumably differ in some important way. There are likely other types as well. The best I’ve been able to come up with is that “EC” stands for “EnCoder”, and the 11 means 11 mm, for (I guess) the shaft length. However, apparently, EC12’s and EC16’s don’t have the push button feature that EC11’s have, so I’m not convinced that’s the whole story. If you know more about this, please let me know.

Electrical Interface

An EC11 has five pins. There is no standard pin labeling, at least not that I could find, but it’s common for the pins to be labeled A, B, C, D, and E. The pinout diagram below is one possible labeling, and is the one I’ll use for this post. Note, however, that some documents have the A and B pin labels swapped.

Pins D and E are used for the button functionality. They are normally disconnected from each other, but are shorted together when the shaft is pressed like a button. This is relatively straightforward, and behaves just like almost any other push button. The other signals are a little more surprising. Pins A, B, and C provide information about rotations, but they’re not simply “clockwise,” “counterclockwise,” and “ground” pins, as I initially expected.

C serves as a common pin, and A and B work together to indicate whether the shaft is being turned, and in which direction. They do this by connecting and disconnecting from C using something called quadrature encoding. When the EC11 is not being turned, A, B, and C are all disconnected from each other. As the shaft is turned clockwise through one step, the following connections and disconnections happen in sequence:

1. A is connected to C,
2. B is connected to C,
3. A is disconnected from C,
4. B is disconnected from C.

For counter-clockwise rotations, the roles of A and B are reversed. Note that only one of the two signals changes at any one time. This encoding enables a simple mechanical design for the device, and also eliminates ambiguous transition states that could arise if both signals changed at nearly, but not exactly, the same time.

To illustrate these signals a little better, I connected an EC11 to an oscilloscope and took some captures. (An oscilloscope shows a graph of voltage on the vertical axis vs. time on the horizontal axis.) In all of these images, A is the yellow trace, and B is the blue trace. For the first two images, C was connected to V_CC (+5V), and A and B were each pulled down to GND (0V) with 10kΩ pull-down resistors. This means that A and B are normally low, but are high while connected to C. The first image shows clockwise rotation, and the second image shows counter-clockwise rotation.

For the next two images, C was connected to GND, and A and B were each pulled up to V_CC with 10kΩ pull-up resistors. This means that A and B are normally high, but are low while connected to C. As before, the first image shows clockwise rotation, and the second image shows counter-clockwise rotation.

The choice of connection method may depend on various factors in the larger circuit, but often it will work just fine either way, and the choice is made arbitrarily or by personal preference of the circuit designer.

Mechanism

Before we dig into this section, I should point out that I haven’t actually taken one of these devices apart, so what follows about the specifics of their construction is speculation and educated guesses on my part. The precise nature and arrangement of the internal parts may differ from what I describe. However, I believe the basic principles are correct.

My understanding is that inside the body of an EC11 are two wipers, or conductive contacts—one connected to pin A and one to pin B. The shaft is attached to a rotating plate with a pattern of conductive pads that can make electrical connections to the wipers. These pads are connected to pin C. It’s a bit hard to explain with words, so here’s a diagram:

This diagram is very approximate. For instance, actual EC11’s have many more than four positions. The ones I’m using have twenty. However, it should communicate the basic idea. As the shaft and plate rotate, but the wipers stay stationary, one wiper will connect to a pad, then the other wiper will, and then the first wiper will disconnect, then the second will, just as described above. The mechanism also includes detents that cause the shaft and plate to snap into place with the wipers between pads.

As I said, some of the details above may not be exactly correct. It’s possible that the wipers move with the shaft over stationary pads. It’s possible that the pads are not on a plate perpendicular to the shaft, but actually placed on the surface of the shaft itself, with the wipers oriented sideways. It’s possible all these methods, and others, could be used by different models of encoders. However, I’m reasonably confident that the general principles outlined above are correct. I welcome feedback and/or corrections from anyone who knows more about this than I do.

Contact Bounce

Things like switches, buttons, and rotary encoders are all subject to a phenomenon known as contact bounce. This means that the physical conductors inside the mechanism can actually bounce off of each other and introduce spurious connections and disconnections before finally settling down to the correct state. This can make it appear as though, for example, a button was pressed several times when the user only meant to press it once.

To demonstrate contact bounce with the EC11, I took another oscilloscope capture, this time significantly zoomed in on the time (horizontal) axis. In the previous captures, the oscilloscope was set to 20 ms per division (i.e. background grid cell). To be able to show the bouncing, I set the oscilloscope to 100 μs, or 0.1 ms, per division. There is some inherent randomness to the bouncing. Sometimes the contacts don’t bounce at all. Sometimes they bounce a great deal. I ended up turning the EC11 a few times to get a good example of bouncing to capture. The following image was taken with the EC11 connected with positive polarity, and the shaft was rotated clockwise.

There are several ways to deal with contact bounce, including both hardware and software solutions, with varying levels of complexity. It might be worth going into this topic in more detail in a future post. However, one simple software solution is to keep track of the previously read value of the input pin, and introduce a delay between reads. The software can then react when there’s a difference between the previous value and the current value. If the delay is sufficiently short, the user won’t notice it, and if the delay is sufficiently long, the bouncing will have stopped by the time the pin is read again. In practice, I’ve found that delays of a few milliseconds work pretty well.

Arduino Sketch

I’ve put together a simple circuit and Arduino sketch to demonstrate how to use these devices. Feel free to use or adapt this code in your own projects. We’ll first take a look at the hardware setup, then we’ll discuss the code.

This example uses an Arduino Uno R3, but it should work with almost any Arduino. Similarly, while this example (somewhat arbitrarily) uses Arduino pins 2, 3, and 4 to connect to the EC11, any free GPIO pins should do. The EC11 is connected with positive polarity. (Changing the hardware connections and sketch code to use the EC11 with negative polarity is relatively straightforward, and is left as an exercise for the reader.)

Connect the Arduino’s 5V pin to the positive breadboard rails and connect the Arduino’s GND to the negative breadboard rails. Connect EC11 pins C and E to the positive rails as well. Connect EC11 pins A, B, and D to the negative breadboard rails through 10kΩ resistors. (Since these are pull-down resistors, the resistor values themselves don’t matter too much, as long as they’re large-ish.) Connect EC11 pin A to Arduino pin 3, EC11 pin B to Arduino pin 4, and EC11 pin D to Arduino pin 2.

Now that the circuit is hooked up, we can move on to the code. The following code uses a simple polling loop with a basic software debouncing scheme, and simply prints messages over the serial connection when the EC11 is rotated or pressed. It should be straightforward to adapt this code to do other things on these events instead.

To read the rotation state, we first check to see if pin A is going from low to high. This rising edge occurs every time the EC11 is rotated. The direction is then determined by looking at the B pin at the moment of A‘s rising edge. In a clockwise rotation, A goes high before B does, so while A is going high, B will still be low. In a counter-clockwise rotation, B goes high before A, so while A is going high, B will already be high. If this isn’t clear, it might help to take another look at the oscilloscope captures above.

We only need to check B when we’ve already determined there’s a rising edge on A, so the code below omits that check in other cases. Also note that we don’t need to debounce B, because bouncing happens right after a state change, and we only read B well before or after its state changes.

The button press events are handled slightly differently from the rotation events. We check for both rising and falling edges on the button input. A rising edge corresponds to the button being pressed, and a falling edge corresponds to the button being released. It’s sometimes useful to track both types of button events, so they’re included in the example.

//
// ec11_example.ino
//
// Example Arduino sketch to demonstrate reading an EC11 rotary encoder
//

// Pin definitions
#define EC11_PIN_A 3
#define EC11_PIN_B 4
#define EC11_PIN_D 2

// Number of milliseconds to wait between pin reads, for software debouncing
#define DEBOUNCE_DELAY_MILLIS 3

// Global variables to hold the previous state of the EC11 pins, initialized
// to LOW. We don't need to track the previous state of B to debounce it
// because we don't read it near an edge, and any bouncing should already
// have stopped by the time we do read it.
int prevA = LOW;
int prevD = LOW;

// Runs once at beginning of sketch
void setup()
{
  // Set pins to input
  pinMode(EC11_PIN_A, INPUT);
  pinMode(EC11_PIN_B, INPUT);
  pinMode(EC11_PIN_D, INPUT);

  // Initialize serial connection
  Serial.begin(9600);
}

// Runs continually in a loop after setup is complete
void loop()
{
  // Local variables to hold the current state of the pins
  int currentA;
  int currentB;
  int currentD;

  // Wait a bit to allow any contact bounce to settle
  delay(DEBOUNCE_DELAY_MILLIS);

  // Process rotation pins
  currentA = digitalRead(EC11_PIN_A);
  if ((prevA == LOW) && (currentA == HIGH))
  {
    // There's a rising edge on A, so the EC11 is being rotated. The state
    // of B at the rising edge of A indicates the direction. If B is low,
    // then A went high first, and the rotation is clockwise. If B is high,
    // then B went high first, and the rotation is counter-clockwise.
    currentB = digitalRead(EC11_PIN_B);

    if (currentB == LOW)
    {
      Serial.println("Clockwise");
    }
    else
    {
      Serial.println("Counter-clockwise");
    }
  }

  // Process button pin
  currentD = digitalRead(EC11_PIN_D);
  if ((prevD == LOW) && (currentD == HIGH))
  {
    Serial.println("Pressed");
  }
  else if ((prevD == HIGH) && (currentD == LOW))
  {
    Serial.println("Released");
  }

  // update previous state globals
  prevA = currentA;
  prevD = currentD;
}

After building this circuit and compiling and uploading the sketch to the Arduino, open the serial monitor and set it to 9600 baud. Then, turn and press the EC11. You should see output similar to the following in the serial monitor:

Clockwise
Counter-clockwise
Pressed
Released
Pressed
Clockwise
Counter-clockwise
Released

Summary

So, that’s about as much as I can say about the EC11 rotary encoder. It’s a cool little device, and can be used to build pretty nice user interfaces for hobbyist projects using Arduino’s, or Raspberry Pi’s, or any other microcontroller. Feel free to reach out if you have any questions/comments/corrections about anything in this post.

When using microcontrollers, like the ATmega line of chips, or boards based on them, like the Arduino series, General Purpose Input/Output (GPIO) pins are often at a premium. The Arduino Uno R3 (based on the ATmega328P), for example, has a maximum of fourteen GPIO pins, and that’s if you’re not using some of the pins’ special functions.

It’s very easy to run out of these GPIO pins if multiple devices are connected directly to them. Each LED uses one pin, configured as an output. Each button uses one pin, configured as an input. A seven-segment display uses eight outputs (there’s a decimal point that’s not counted in the name for some reason). In its most minimal configuration, an LCD character display module uses six pins, but can be configured to use as many as eleven pins. All this quickly adds up.

Shift Registers

A common solution to the problem of too few GPIO pins is to use one or more shift registers. Simply put, a shift register is a chip that converts a single signal changing over time (i.e. serial) to multiple signals at the same time (i.e. parallel), or vice-versa. This solution is so common that the Arduino core library has functions specifically to support their use, and there are lots of Arduino/shift-register tutorials to be found on the internet. (I guess I’m adding to that list.)

There are many different types of shift register available, but two of the most popular are the 74HC595 (to add output pins) and the 74HC165 (to add input pins). These chips are easy to use, inexpensive, and readily available. You can get them from electronics suppliers like Mouser and DigiKey, and they’re even available from Amazon.

The basic principle behind shift registers, and the reason for their name, is that each chip holds a number of bits (typically eight) in a small memory circuit called a register, and these bits shift from one to the next when a clock pulse is applied. Bit 0 shifts into bit 1, bit 1 shifts into bit 2, and so on. The new value for bit 0 comes from a serial input pin at the time of the clock pulse. The last bit falls out of the shift register, and is made available on one of the chip’s output pins, called serial output. Typically, the shift happens on the rising edge of the clock pulse (i.e. from low to high).

The fact that each shift register has a serial input pin that feeds into bit 0 and a serial output pin that holds the value of the last bit as it’s shifted out means that these chips may be cascaded, or chained together, by connecting the serial output of one chip to the serial input of another, and by connecting their clocks together. Two 8-bit shift registers cascaded together, for example, behave as if they were a single 16-bit shift register. The number of chips that can be cascaded into a single effective register is typically limited only by things like available power and the capacitance of the connecting wires, but the chain would need to be pretty long for those things to start to matter.

There are a few disadvantages to using shift registers for GPIO expansion. First, it’s slower. Instead of reading or writing several pins at once, the microcontroller has to process them one at a time. Second, the pins can’t be read or written independently. To read/write bit 4, for example, bits 0-3 must first be read/written. When the shift register is being used to add output pins, this means the software needs to keep track of what bits have been written. Third, most shift registers are unidirectional. That is, each type of chip provides either inputs or outputs, but not both. (The 74HC299 is one exception to this.) In practice, however, these disadvantages are often easily overcome and are more than made up for by the added inputs and/or outputs.

74HC595

The 74HC595 is an 8-bit Serial-In / Parallel-Out (SIPO) shift register. It shifts in one bit from its serial input pin (pin 14) on each rising edge of its serial clock pin (pin 11), and has eight parallel output pins (pins 15 and 1-7). However, the bits in the shift register are not immediately made available on the output pins.

The 74HC595 internally has two registers: the shift register and the storage register (sometimes called the latch register). The shift register behaves as described above. However, the parallel output pins are not connected directly to the shift register, but rather to the storage register. The contents of the shift register are transferred to the storage register (and therefore the output pins) on the rising edge of a second clock pin (pin 12), called the storage clock pin (or sometimes the latch pin).

This dual-register configuration may seem like a needless complication. Worse, instead of just two GPIO pins (serial input and serial clock), it uses those plus a third (storage clock). However, there is a good reason for this design. Some devices connected to the 75HC595’s output pins may not react well to the data shifting along one bit at a time. The two-register approach allows data bits to be shifted in while keeping the output pins unchanged, then all made available effectively simultaneously once the complete set of bits is ready.

If a device can tolerate seeing the data shift one bit at a time, the serial clock and storage clock pins may be connected together. This causes the 74HC595 to behave (more or less) as if the outputs were connected directly to the internal shift register, and it only requires a total of two GPIO pins instead of three.

To interface a 74HC595 with an Arduino (or similar microcontroller), connect the serial input, serial clock, and storage clock pins of the 74HC595 to GPIO pins on the microcontroller, with all three configured as outputs. Then, in the microcontroller code (i.e. Arduino sketch), write each bit to the shift register as follows.

1. Set the serial input pin to the value of the data bit.
2. Bring the serial clock pin low, then high, to create a rising edge and shift the bit.
3. Repeat steps 1 and 2 until all bits have been shifted.
4. Once all bits have been shifted, bring the storage clock low then high to transfer the bits to the parallel output pins.

Step 4 can be omitted if the serial clock and storage clock are tied together. The Arduino core library function shiftOut() performs steps 1 and 2 in a loop to write eight bits.

The 74HC595 has a few other useful features, including tri-state outputs and a reset pin. The datasheet has more information about these if you’re interested, but they’re not particularly relevant to this post, so that’s all I’ll say about them here.

74HC165

The 74HC165 is an 8-bit Parallel-In / Serial-Out (PISO) shift register. Data bits are loaded into the chip all at once from eight parallel input pins (pins 11-14 and 3-6) while the parallel load pin (pin 1) is set low. Once the bits are loaded, they can be shifted out one at a time to the serial output pin (pin 9) by pulsing the serial clock pin (pin 2). Bits are shifted on the rising edge of the clock pulse, and the serial input pin (pin 10) provides a new value for bit 0 on each pulse.

The process to interface the 74HC165 with a microcontroller is very similar to the process for the 74HC595. Connect the 74HC165’s serial clock and parallel load pins to output pins on the microcontroller, and connect the 74HC165’s serial output pin to a microcontroller input pin. Then, in software, perform the following:

1. Bring the parallel load pin low, then high to latch the inputs into the shift register.
2. Bring the serial clock pin low.
3. Bring the serial clock pin high to create a rising edge and shift out a bit.
4. Read and process the data bit from the serial output pin.
5. Bring the serial clock pin back low to prepare for the next bit.
6. Repeat steps 3 through 5 for each bit.

The Arduino core library function shiftIn() performs steps 3 through 5 in a loop to read eight bits.

Like the 74HC595, the 74HC165 has additional features, such as clock inhibit and complementary serial output, that I’m not going to discuss here. For more information, see the datasheet.

Serial Peripheral Interface (SPI)

The Serial Peripheral Interface (SPI) protocol is another way to reduce the number of microntroller GPIO pins needed for a project. There are many devices that support SPI natively, and there are quite a few available on Amazon, for instance. The protocol is relatively simple, and it’s straightforward to implement in software. Ben Eater has an excellent video in which he interfaces an SPI device with a 65C02 microprocessor using assembly code. However, most microcontrollers, including Arduinos, have hardware support for communicating via SPI. This enables much faster speeds than would be possible with a software implementation.

SPI is, as its name implies, a serial protocol. This means that one bit is transferred at a time. Actually, that’s not quite true, since SPI supports full-duplex bidirectional communication. This means that one bit is sent and one bit is received at the same time. It’s also a sychronous protocol, which means that the timing is controlled by a dedicated clock signal. Finally, it’s an asymmetric protocol. This means that the communication is entirely controlled by one device, called the master (sometimes controller). This is usually the microcontroller. The other device is called the slave (sometimes peripheral), and it sends and receives data only as directed by the master. Multiple slave devices can be connected to a single master.

The basic setup for SPI uses four different signals, each on a separate pin:

• Serial Clock (SCK): This is the signal that controls the rate of the data transfer, and is driven by the master. One bit is transferred in each direction when this signal is pulsed. SPI doesn’t specify whether the bit is transferred on the rising or falling edge of the clock signal. Instead, that’s left up to the individual implementation. Most microcontrollers will have an option to specify this as part of the SPI mode setting. SPI modes 0 and 3 transfer on the rising edge, and modes 1 and 2 transfer on the falling edge. Mode 0 differs from 3, and 1 from 2, in the level of the clock signal when idle. Modes 0 and 1 keep the clock low when idle, and 2 and 3 keep it high. The datasheet for the slave device will specify which mode(s) it expects, but mode 0 is typical.
• Master Out / Slave In (MOSI): This is a data transmission signal over which the master sends data bits to the slave, at the rate dictated by the SCK signal. Note that this way of naming the signal is unambiguous about direction, and can be labeled the same on both master and slave devices. If the slave device is read-only (e.g. a sensor of some sort), this signal may be omitted. This signal is also sometimes called Controller Out / Peripheral In (COPI). On slave devices, this signal may also be called Data In (DI, DIN) or Serial Data In (SDI).
• Master In / Slave Out (MISO): This is a data transmission signal over which the slave sends data bits to the master, at the rate dictated by the SCK signal. If the slave device is write-only (e.g. a display of some sort), this signal may be omitted. This signal is also sometimes called Controller In / Peripheral Out (COPI). On slave devices, this signal may also be called Data Out (DO, DOUT) or Serial Data Out (SDO).
• Slave Select (SS): This is a control signal which activates the slave (i.e. tells it to pay attention to the other signals). The overbar on the abbreviation indicates that this signal is active low, and is pronounced by adding “bar” after the abbreviation (i.e. “ess ess bar”). In contexts where overbars are typographically difficult, this may be rendered as /SS or SSB (“B” for “Bar”). Active low means that the slave is selected when this signal is low, and deselected when the signal is high. When multiple slave devices are connected, each device is assigned its own SS signal. The other signals are shared among all slave devices. Usually, only one slave is selected at any one time. This signal is also sometimes called Chip Select (CS, /CS, CSB).

To perform SPI transfers in software, make sure the relevant signals are connected between the master and slave, and perform the following:

1. Bring the SS pin low to select the slave device.
2. Set the MOSI pin to the value of the outgoing bit. (Omit for read-only slave.)
3. Pulse the SCK pin (high then low, or low then high, depending on mode).
4. Read the incoming bit from the MISO pin. (Omit for write-only slave.)
5. Repeat steps 2 through 4 until all bits are transferred.
6. Bring the SS pin high to deselect the slave device.

As previously mentioned, most microcontrollers have SPI support built in hardware. The SPI hardware in the Arduino Uno’s ATmega328P can run the serial clock at up to half the rate of the system clock, which is 16 MHz on an Arduino Uno, so the Arduino can do SPI at up to 8 MHz. This is significantly faster than would be possible with a pure software implementation. Some microcontrollers can run the SPI serial clock at 10’s or even 100’s of MHz.

To use the microcontroller’s SPI hardware to perform transfers, MOSI, MISO, and SCK on the slave should be connected to the corresponding SPI pins on the microcontroller. On the Arduino Uno R3, MOSI is pin 11, MISO is pin 12, and SCK is pin 13. The slave’s SS pin can be connected to any free GPIO pin on the master, configured as an output. The Arduino has a pin labeled SS (pin 10), but it’s only necessary to use that when connecting the Arduino as a slave to another SPI master.

Once everything is connected, issue the microcontroller instructions to enable and use the SPI hardware. In an Arduino sketch, this can be done with the SPI library, specifically the functions SPI.begin() (called once to enable the SPI hardware), SPI.beginTransaction() (called once before each batch of transfers), SPI.transfer() (called any number of times to transfer a batch of eight bits each time), and SPI.endTransaction() (called once after each batch of transfers). If you need to disable the SPI hardware again for some reason, that can be done with function SPI.end(). The SS pin must still be handled explicitly by the software, but the others will be taken care of by the hardware.

Using Shift Registers with SPI

You may have noticed that the protocols for shift registers and SPI are remarkably similar, and wondered if they could be used together. In fact, they can! (If you didn’t notice, don’t worry too much; it took me way longer than I care to admit to notice it myself.) With just a few extra chips, 74HC595 and 74HC165 can be used to build a hardware SPI interface for a device which normally uses a parallel interface, thereby significantly reducing the number of GPIO pins used by the design, while only sacrificing a little bit of speed.

Shift registers and SPI each have serial clock signals, so those can simply be connected together. Similarly, SPI’s MOSI signal can be connected to the serial input signal of a 74HC595 shift register, and SPI’s MISO signal can be connected to the serial output signal of a 74HC165 shift register (although there’s a complication with MISO that we’ll discuss a little later). This takes care of three of the four SPI signals, and two of the three signals needed for each shift register.

The remaining signals, SPI’s SS, the 74HC595’s storage clock, and the 74HC165’s parallel load require just a little more thought. Recall that SS is brought low before an SPI transfer, and high after the transfer is complete. Recall also that the 74HC595’s storage clock needs a rising edge to move the data from the shift register to the storage register. That rising edge can be provided at just the right time by connecting SS to the 74HC595’s storage clock pin. This does mean that the slave device must be deselected after transferring each set of bits, but in practice, that’s not a significant disadvantage, just something to be aware of.

Before each transfer, the 74HC165’s parallel load pin needs to be set low to load data into the shift register, and high to enable that data to be shifted out. This is the inverse of the SS signal, which is set high then low before each transfer. To correct this, we can use an inverter (a.k.a. a NOT gate) to flip the SS signal to be what we need for the parallel load pin. The 74HC04 has six inverters, which is more than we need, but will work for our purposes. (The inverters we’re not using could be used in other parts of a larger circuit, or their inputs can simply be connected to GND or V_CC to keep them from floating and introducing noise into the circuit.) If we connect SS to the input of one of these inverters, and the output of that inverter to the 74HC165’s parallel load pin, the 74HC165 will continually load data into its shift register until it’s selected, at which point it will latch that data and make it ready to be shifted out by the other SPI signals.

If this SPI interface that we’ve built out of shift registers is the only slave connected to the SPI pins, then we’re done; all that’s left is to connect the shift registers’ parallel inputs and outputs to the device. However, recall that if the SPI hardware is shared, MOSI, MISO, and SCK are also shared among all slave devices. For the 74HC595, this is no problem. It will shift bits in and out of its shift register even while another slave is selected, but its parallel output pins will stay latched, because they are controlled by its SS signal. The 74HC165 is another matter. If another slave is selected and SCK is pulsed, the 74HC165 will still shift bits out into the MISO pin, interfering with the signal coming from the other slave.

To fix this, we need to connect the 74HC165’s serial output to MISO only while its SS signal is low. This can be accomplished with a tri-state buffer. A tri-state buffer is a logic gate that has a data input, a control input, and a data output. The control input is active low, and when it’s low, the value on the data input is propagated to the data output. When the control input is high, the data output is set to high impedance, which basically means it’s not connected. The 74HC125 contains four tri-state buffers. Again, we only need one, but that’s okay. We connect the 74HC165’s serial output to the data input of one of the 74HC125’s tri-state buffers, connect the output of that tri-state buffer to MISO, and connect SS to the tri-state buffer’s control input. Now, the 74HC165 can only send data on MISO when it’s selected, which is exactly what we want.

As previously mentioned, shift registers of the same type may be cascaded together to create shift registers that hold more bits. This remains true when using them with SPI. If you’re building an SPI interface for a device that has sixteen inputs and twenty-four outputs, you can cascade two 74HC595’s together and three 74HC165’s. The principles are the same; there are just more bits. If the cascaded chains are of unequal length, then each transfer should include enough bits for the longest chain. The extra bits for the shorter chain can safely be ignored by the software. If the device is read-only or write-only, the interface can be built using only one of the two types of shift registers.

Conclusion

Both SPI and shift registers are useful ways to reduce the number of microcontroller GPIO pins needed for a design. Combining them (and adding a bit of glue logic) is a great way to do so without sacrificing much speed. I’ve used this technique in some of my projects and it’s worked very well. If you use this in your projects, I’d enjoy hearing about what went well or not so well. I hope that this post has been informative and enjoyable. If I’ve made any errors or left out important details, please do let me know.

I’ve added some new features to the ApOPL3xy synthesizer project I talked about in my last post. Some technical details follow, but first, let’s check out what the new version can do. Specifically, MIDI files can now be played from a computer (or other sequencer) into the ApOPL3xy to be synthesized.

Demo Songs

Here are some example songs. These songs were recorded by playing MIDI files from a computer into the ApOPL3xy’s MIDI-In port, running its audio output into the computer’s line-in jack, and capturing the line-in signal with Audacity. None of these files were post-processed in any way, other than to crop off leading and trailing silence. Links to the source MIDI file and the recorded MP3 are available for each song.

Harold Faltermeyer – Axel F (Beverly Hills Cop Theme) [MIDI] [MP3]

Toto – Africa [MIDI] [MP3]

Alan Menken – Under the Sea (from The Little Mermaid) [MIDI] [MP3]

Europe – The Final Countdown [MIDI] [MP3]

Finally, I would be remiss not to include this masterpiece [MIDI] [MP3]

New Features

Non-Volatile PATCH Storage

In my previous post, I discussed the Fat Man’s General MIDI 2-operator and 4-operator OPL3 patch sets. I’ve added the patches from the 2-operator set into the system, so they’re readily available without laboriously entering them using the UI.

They’re stored on an EEPROM chip (Microchip 25AA1024) for non-volatile storage, and cached in an SRAM chip (Microchip 23LCV1024). From there, they can be loaded into the ATmega1284’s system RAM as needed and sent to the OPL3 synth chip for use. I updated the patch editor UI to allow the user to select which patch to edit, and whether to save the edits in SRAM only or also in EEPROM.

OMNI MODE

Previously, the ApOPL3xy only processed MIDI messages on MIDI channel 1. Messages from other channels were ignored. This was enough to get the keyboard controller to be playable, but to play multiple instruments simultaneously, a synthesizer needs to be in omni mode. In this mode, the synthesizer processes messages from all 16 MIDI channels.

I’ve implemented support for omni mode in the latest version. (In fact, omni mode is always on now, as I have not yet added a UI option to turn it off.) A separate patch selection (a.k.a. “program”) can be made for each channel, allowing multiple different but concurrent instruments to be synthesized.

Soon, I plan to add a UI utility to select patches for each channel, but for now, I’ve implemented handling for the Program Change MIDI message to allow an input MIDI device to make the selection.

PERCUSSION CHANNEL

I’ve also implemented a percussive channel mode, which is commonly used for MIDI channel 10. This mode is special because the patch that gets used when a note is played depends not on the channel program setting, but on the note number itself. For instance, note 35 (B0) is for an acoustic bass drum sound, and note 40 (E1) is for an electric snare sound.

The Fat Man’s patch set includes a bank of percussion sounds for this purpose, and I’ve uploaded them to the EEPROM as well. I haven’t yet updated the patch editor to be able to edit these, but I will soon.

Note that this is distinct from OPL3’s percussion mode, which I also plan to support in the future. This mode was not often used, and in fact, none of the patches in the Fat Man’s sets use it. It’s therefore a lower priority. But it’s something the chip can do, so I want the ApOPL3xy to support it.

Update / Bug Fix

I was looking through the code yesterday, and I found a bug with pitch bend that would cause a pitch bend on one channel to bend new notes on all channels. The careful listener might have noticed something off with Africa and The Final Countdown. I’ve since fixed it and uploaded new recordings for the two affected songs, but I’m putting the original broken versions below for posterity.

Toto – Africa (Pitch Bend Bug) [MP3]

Europe – The Final Countdown (Pitch Bend Bug) [MP3]

It’s been a while since I’ve posted anything about electronics projects. I have not been idle, however. My current project is finally starting to come together enough to be able to show it off a little. It’s a MIDI synthesizer powered by the Yamaha YMF-262 (a.k.a. OPL3) FM synth chip, the successor to the YM3812 (a.k.a OPL2) I’ve talked about previously, and the Microchip (née Atmel) ATmega1284, a bigger brother of the ATmega328P used in the Arduino Uno. I’m calling the project “ApOPL3xy”, because I think apoplexy is a cool word, and it lets me put the OPL3 string in the middle.

Demo

I just got the patch editor working yesterday, so I’m excited to be able to show it off. It’s a bit rough around the edges, but it’s the first time the ApOPL3xy has felt like a real(ish) synth. Note that I don’t have 4-operator patches working yet, and there are a lot of menu items that you’ll see that don’t actually do anything. But 2-operator patches work.

I downloaded a 2-op patch set for the OPL3 authored by The Fat Man and used by the ADLMIDI project. I also used OPL3BankEditor to extract the parameters I needed to enter into the ApOPL3xy. The following videos show me entering in a few of these patches and demoing them with a MIDI controller keyboard.

Here’s an example of pitch bend working. This was a lot more difficult than I expected, and the details deserve their own post, but it seems to work pretty well now.

I also implemented a VGM player. VGM (Video Game Music) is a file format that stores commands to send to various synth chips. People have captured songs from lots of retro video games and uploaded them to vgmrips.net. I downloaded several, uncompressed them, and put them on the SD card for the ApOPL3xy to read. Here are a few examples:

Features and Limitations

There’s a lot of work left to be done, but the core is working. Current features include:

• MIDI Input
  • Currently limited to MIDI channel 1
  • Currently, the only messages supported are Note On, Note Off, and Pitch Bend
  • Velocity is not yet supported
• 2-channel audio output
  • The final product will have 4 output channels, but the breadboard version only has 2
• 18-voice polyphony when using 2-operator mode
• 10-segment LED VU meters per output channel
• Gain control potentiometer knob per output channel
• Menu-driven user interface
  • 20×4 LCD character display
  • 2 rotary encoders and 10 push buttons
• Micro SD card reader
• VGM player
  • Both OPL2 and OPL3 VGM files are supported
  • VGM file must be uncompressed. VGZ files are not supported.

There are several things I plan on adding in the future:

• 4-operator patch support
• Patch bank – currently the system only knows about one patch at a time
• Persistent patch/bank storage on EEPROM
• Import/export of patches and banks to SD card
• User interface improvements
• Support more MIDI messages
• Support MIDI velocity
• MIDI through output
• MIDI omni mode
• MIDI file playback
• VGM / MIDI file playlist support
• Printed circuit board
  • Split into two boards: the OPL3 board and the MIDI board. They’ll be connected with an IDC ribbon cable I think. This will allow the OPL3 board to be connected to other things in the future, like my homebrew 6502 computer, or a Commodore 64, etc.
  • ISP and JTAG headers for programming/debugging and headers for SPI, I2C and unused GPIO pins. This project was intended from the start to be hackable and upgradable.

Development Environment

I started out using the Arduino IDE to write the code for the firmware. That’s fine for small projects, but this quickly outgrew it. I recently switched to PlatformIO, and that’s been much more pleasant. It’s an extension for Visual Studio Code, and it supports a large number of microcontrollers and libraries. I’m using the AVR-ISP mkII programmer to upload the compiled firmware to the microcontroller. To access the micro SD card, I’m using the excellent SdFat library.

Closing Thoughts

This project has been a much larger undertaking than I initially envisioned. I’m excited that it’s starting to come together. I may post other articles about various technical details of the design and implementation another time, if there’s interest. When I get the PCB’s made, I plan to make the CAD files for the boards and the source code for the firmware available so people will be able to build one and mess with it if they want to.

The first step was to find some sheet music for the song. I found this, but MuseScore wouldn’t let me download it without registering for an account. I’m not about to do that. But, it’s pretty short, so I just entered it into my local install of MuseScore. Here it is for the curious:

And this is what it sounds like, in case you don’t remember:

Listening to this, I felt like it was pretty plain. I wanted to spice it up a bit. So, I added some drums (some tweaks were suggested by Donnett). Also, a retro video game shouldn’t sound like a piano. A square wave would be much more appropriate. With those changes, we get this:

That’s more like it! Much more fun to play Tetris to, IMO. But, it needs just a little bit more. Donnett has been teaching me some music theory, and I wanted to see if I could figure out what chords would sound good in a bass line. With one slight tweak from her (change first chord in second phrase to a 2 instead of a 7), I’m really happy with how it sounds in MuseScore (the chords start at 0:42):

For the musically inclined, here’s the updated sheet music and MuseScore files:

But we’re not done yet! Remember, the point of this whole exercise is to get it running on a 6502 computer with an OPL2 sound chip. To that end, I started looking at tracker programs. I found one called Adlib Tracker 2 that I liked pretty well, and set it up in DOSBox. It’s got a fantastic 90’s-era look, and it’s pretty powerful.

After a little learning curve, I was able to pick out some instruments, tweak them to get them sounding the way I want, and enter the notes. Here’s a video capture of the tracker playing the OPL2 version of my arrangement. (Note that the tempo is a bit slower. I didn’t notice when I was first doing this, but now listening to both speeds, I think I prefer the slightly slower version.)

The last step is to get this ported over to run on the homebrew machine. This was easier said than done. Eventually, I’ll probably write something to process the A2M file format created by Adlib Tracker 2, but this time, I used DOSBox’s OPL capture feature to capture a DRO file. Then I downloaded and compiled the utilities in the vgmtools github repository. It has two utilities I needed: dro2vgm, and vgmtrim. I had previously written a python script to extract the OPL2 commands I need from a VGM file. (By the way, vgmrips.net has a fantastic collection of music from old video games, using OPL2, OPL3, and many other chips.) So, finally, I have this song playing on my homebrew computer!

Pretty good for a 47-year old CPU!

I’ve made some changes from Ben’s design. I’m using CPLD‘s for address decoding, an 8k ROM instead of 32k (but I can adjust the address decoding to support up to 32k ROM), 64k RAM (not all addressable due to ROM and I/O), 4 65C22 VIA’s, and a 4 MHz clock. So far I’ve added a 20×4 character LCD, a YM3812 (OPL2) sound chip, and a NES controller. I have plans to add a PS/2 keyboard, an SD card reader, upgrade the clock frequency to 8 MHz, upgrade the OPL2 to an OPL3, and add a composite video display using the TMS9918A video chip.

I’ll make a bunch of posts in the future about various technical topics related to this, but I wanted to start with this general post introducing the project.