The YM3812 Class

In the last article, we built a simple circuit to get our YM3812 up and running on a breadboard. To do that, we used code from the GitHub repo and just kind of glossed over how the it works. In this article, let’s delve into the sea of complexity that is c++ programming. Obligatory disclaimer: c++ is an incredibly flexible language with MANY ways of writing code from the simplest to the most enigmatic. I chose one way—not the best way, nor the simplest, nor the most elegant—just the way I thought to do it. If you have recommendations on how to improve the code, please leave a comment!

Code Structure

For now, the code resides in three files—though we will add a couple more before this project concludes:

• YM3812_Breadboard.ino will be our primary “program”—that is, where the setup and main loop functions reside
• YM3812.h header file defines the YM3812 library that wraps the chip’s functionality into a class
• YM3812.cpp provides implementations for functions defined in the header file

Inside of the YM3812 class are two different types of functions. The Chip Control Functions instruct the microcontroller to send data to (or reset) the YM3812. Their implementation depends entirely on the type of microcontroller used and how its pins are configured. The Register Functions utilize these Chip Control Functions to manipulate register settings in the YM3812. By coding things this way, if you want to use an Arduino or Teensy instead of the AVR128DA28, then you only need to change the sendData and reset functions. Everything else stays the same.

The last piece of our class is the Register Cache. Because we want to manipulate pieces of bytes in the registers at a bit level, we need to know the current state of all of the bits that we don’t want to change. The YM3812 doesn’t allow us to read registers on the chip, so instead, we have to store their current values in the microcontroller’s memory. At some point, we will discuss how to circumvent this, but that’s a few articles away.

Chip Control Functions

Let’s start with the lowest level functions that electrically manipulate the pins on the YM3812. The good news is that there are only two of them: sendData and reset.

sendData( reg, val )

If you read the first article, this should feel pretty familiar. sendData directly implements the timing diagram at the end of that article—but with one small change. “Putting data on the bus” requires sending the byte over SPI and then latching it onto the 74HC595. Let’s take a look:

//Port Bits defined for control bus:
#define YM_WR    0b00000001  // Pin 0, Port D - Write
#define YM_A0    0b00000010  // Pin 1, Port D - Differentiates between address/data
#define YM_IC    0b00000100  // Pin 2, Port D - Reset Pin
#define YM_LATCH 0b00001000  // Pin 3, Port D - Output Latch
#define YM_CS    0b00010000  // Pin 4, Port D - Left YM3812 Chip Select

...

void YM3812::sendData( uint8_t reg, uint8_t val ){
  PORTD.OUTCLR = YM_CS;     // Enable the chip
  PORTD.OUTCLR = YM_A0;     // Put chip into register select mode

  SPI.transfer(reg);        // Put register location onto the data bus through SPI port
  PORTD.OUTSET = YM_LATCH;  // Latch register location into the 74HC595
  delayMicroseconds(1);     // wait a tic.
  PORTD.OUTCLR = YM_LATCH;  // Bring latch low now that the location is latched

  PORTD.OUTCLR = YM_WR;     // Bring write low to begin the write cycle
  delayMicroseconds(10);    // Delay so chip completes write cycle
  PORTD.OUTSET = YM_WR;     // Bring write high
  delayMicroseconds(10);    // Delay until the chip is ready to continue

  PORTD.OUTSET = YM_A0;     // Put chip into data write mode

  SPI.transfer(val);        // Put value onto the data bus through SPI port
  PORTD.OUTSET = YM_LATCH;  // Latch the value into the 74HC595
  delayMicroseconds(1);     // wait a tic.
  PORTD.OUTCLR = YM_LATCH;  // Bring latch low now that the value is latched

  PORTD.OUTCLR = YM_WR;     // Bring write low to begin the write cycle
  delayMicroseconds(10);    // Delay so chip completes write cycle
  PORTD.OUTSET = YM_WR;     // Bring write high
  delayMicroseconds(10);    // Delay until the chip is ready to continue

  PORTD.OUTSET = YM_CS;     // Bring Chip Select high to disable the YM3812
}

The pin definitions at the top of the code provide a name for each pin of PORT D on the microcontroller. The sendData function then uses those definitions to directly manipulate the registers and turn on and off those pins.

If you are more accustomed to the digitalWrite() function on an Arduino, then OUTSET and OUTCLR might look a little strange. These map to registers in the AVR128DA28 microcontroller that directly manipulate the output pins. By writing a byte to OUTSET, any bits in that byte that are 1 will turn the corresponding pins on. Bits that are 0 will just be ignored. OUTCLR does the opposite. Any bits that are 1 in the byte will turn off their corresponding pins and, again, the 0s get ignored. While maybe a little less intuitive, directly manipulating these registers makes things MUCH faster.

Take note that in order for SPI.transfer() to work, you first have to run SPI.begin() at some point prior in the code. I got stumped by this bug while reducing the module code for this article. When I removed the code for the TFT screen—which also uses the SPI bus—the microcontroller locked up when it ran the SPI.transfer() function. This is because the TFT screen’s initialization function runs SPI.begin(). Once I added SPI.begin() to the YM3812’s reset function, everything worked perfectly!

void reset()

void YM3812::reset(){
  SPI.begin();                                            // Initialize the SPI bus

  //Hard Reset the YM3812
  PORTD.OUTCLR = YM_IC; delay(10);                        // Bring Initialize / Clear line low
  PORTD.OUTSET = YM_IC; delay(10);                        // And then high

  //Clear all of our register caches
  reg_01 = reg_08 = reg_BD = 0;                           // Clear out global settings
  for( uint8_t ch = 0; ch < YM3812_NUM_CHANNELS; ch++ ){  // Loop through all of the channels
    reg_A0[ch] = reg_B0[ch] = reg_C0[ch] = 0;             // Set all register info to zero
  }
  for( uint8_t op = 0; op < YM3812_NUM_OPERATORS; op++ ){ // Loop through all of the operators
    reg_20[op] = reg_40[op] = reg_60[op] = 0;
    reg_80[op] = reg_E0[op] = 0;                          // Set all register info to zero
  }

  regWaveset( 1 );                                        // Enable all wave forms (not just sine waves)
}

The reset function does four main tasks. First it initializes the SPI bus, then it hard-resets the YM3812 by bringing its reset line low and then high. The delays ensure the chip is ready before continuing. Third, it resets the register cache variables stored in the class to zero (so they match what should be in the chip now). And finally, it sets the “Waveset” flag to allow for all waveform types.

Twiddling Bits

The register functions build upon the chip control functions and follow a very similar pattern:

1. Mask the new value to ensure it has the correct number of bits for the property you want to change
2. Look up the current value of the register containing the property
3. Erase the bits associated with the property that you want to overwrite
4. Insert the masked property value‘s bits into the register
5. Save the new combined register value into the register cache and send it to the YM3812

Bit manipulation turns out to be the most complicated part of this process. So let’s start with a macro that, once written, will allow us to tuck all of those details away and not worry about them any more:

SET_BITS( regVal, bitMask, offset, newVal )

This macro takes a register value (regVal) and combines a new property value (newVal) into it. The bitMask determines which of the bits from newVal to include, and offset determines where inside of regVal to insert those bits.

Looking at the left side of the chart above, we can see binary versions of newVal as well as bitMask. In this case, we want to insert a two-bit number into bits 4 and 5 of an existing register value without accidentally overwriting any of the other bits. A two-bit value should only ever have 1s in the lowest two bits, but of course, nothing prevents a developer from accidentally pushing a bigger value. So, to solve this, we use a bitMask that has 1s in the two lowest bits—the ones we want to keep—and then AND it with newVal. This way, we block out any rogue bits (like that 1 in red).

In order to insert those two bits into the current register value, we need to first set any bits we want to overwrite to zero. To create this “hole,” we shift the bitMask to the left by offset and then invert it (with the ~ operator). This puts a 1 in all of the bits we want to keep (as shown on the right side of the chart above). If we logically AND this new mask with regVal then those two bits will be zero.

Now, to insert our trimmed newVal into the two bit hole in regVal, we need to shift the value over by offset so it is in the right spot. Then we just logically OR the repositioned value with the masked regVal and presto! We get a new regVal with newVal inserted into just the right spot, and without altering any other bits.

Representing this as a single formula looks something like this:

regVal = (regVal & (~(bitMask<<offset))) | ((newVal & bitMask) << offset))

In this case, regVal will be overwritten with the new combined value. And, because assigning one value to another returns the assigned value, you could wrap this entire thing in parenthesis and think of it like a function that both updates regVal and returns the updated value.

This is fairly complicated bit-math, so if its confusing, that’s OK. We are going to use this formula a lot though, so let’s tuck away all of that complexity into a macro:

#define SET_BITS( regVal, mask, offset, newVal) ((regVal) = ((regVal) & (~((mask)<<(offset)))) | (((newVal) & (mask)) << (offset)))

Macros are a little like functions, except they aren’t executed at runtime. Instead, before compiling the code, the pre-compiler looks for any macro calls and replaces them with their associated code. For example, when the pre-compiler finds:

SET_BITS( reg_20[op], 0b00000001, 7, val )

It replaces that text with:

((reg_20[op]) = ((reg_20[op]) & (~((0b00000001)<<(7)))) | (((val) & (0b00000001)) << (4)))

We could write all of our functions without the macro using this expanded format, but personally, I find the first version easier to read. Also, we can combine this with our sendData function to write a single line of code for each of our register update functions. Let’s dive into those next.

Global Register Fns

Let’s put our sendData function and SET_BITS macro together to actually modify a register. There are three types of these register update functions—global, channel and operator. The Global registers are the simplest, so we’ll start there. Let’s write a function that sets the Tremolo Depth for the chip.

Looking at the Register Map, we see that the Deep Tremolo flag is located at bit B7 of register address 0xBD. To update this, we have to fetch the current value of register 0xBD from our register cache and then update bit B7.

What is this register cache? Well, there isn’t any way to read the current value of a register on the YM3812. So in order to update only a few bits of a register value, we need to keep track of the current values for all of the registers in memory on the microcontroller. Global registers only have one instance of their value, so they can be represented with integers. Channels and Operators both have multiple instances of their registers so we use integer arrays to store them. Here are the global register caches:

// Global Level Caches
uint8_t reg_01 = 0;  // Wave Select Enable
uint8_t reg_08 = 0;  // Speech Synthesis Mode / Note Select
uint8_t reg_BD = 0;  // Deep AM/VB, Rythm flag, BD, SD, TOM, TC, HH (Drum stuff)

As a convention, I’ve named each register cache variable after its base address. For global registers that have only one setting per base address, these are simply integers. Channel and Operator caches have multiple settings, so they are stored in arrays. Ok, let’s start piecing together our function.

void regTremoloDepth( uint8_t val ){ sendData( regAddress, value ); }

We know that our function is going to call sendData to set the register value on the YM3812, and that the function requires both a register location and a value to set it to. regAddress comes from the chart above—0xBD—so that’s easy to fill in. value needs to combine the current value of our register cache with the val that was passed into the function. Good thing we have that SET_BITS macro, let’s pop that in:

void regTremoloDepth( uint8_t val ){ 
  sendData(0xBD, SET_BITS( regVal, bitMask, offset, newVal ) ); 
}

Filling in the blanks above, we first swap regVal for the variable containing the current value of the register we want to modify—reg_BD in this case. Then, because we are updating only a single bit, we swap bitMask for the constant, 0b00000001. Then, because the DeepTrem flag sits in bit 7, we swap offset for the constant, 7. Finally, we swap newVal for the variable that was passed into the function—val.
Here’s what the formula looks like once you make all of those changes:

void regTremoloDepth( uint8_t val ){ 
  sendData(0xBD, SET_BITS( reg_BD, 0b00000001, 7, val ) ); 
}

And there you have it, our one-liner function that allows the user to update the global tremolo depth value.

Channel Register Fns

Updating the channel registers works much the same way, but with one new wrinkle. Instead of one register per base address, we now have 9—one for each channel. Let’s look at the register caches to see how they are affected:

uint8_t reg_A0[YM3812_NUM_CHANNELS] = {0,0,0,0,0,0,0,0,0}; // frequency (lower 8-bits)
uint8_t reg_B0[YM3812_NUM_CHANNELS] = {0,0,0,0,0,0,0,0,0}; // key on, freq block, frequency (higher 2-bits)
uint8_t reg_C0[YM3812_NUM_CHANNELS] = {0,0,0,0,0,0,0,0,0}; // feedback, algorithm

Instead of simple integers, we use integer arrays to store our cache values. The arrays contain one integer for each of the 9 channels supported by the YM3812. This also means that in our register writing functions, we have to choose the correct register cache value based on the channel we want to update. Here is an example:

void regChFeedback( uint8_t ch, uint8_t val ){ 
  sendData(0xC0+ch, SET_BITS( reg_C0[ch], 0b00000111, 1, val ) ); 
}

This function modifies the feedback property of a specific channel. It takes two parameters: the channel to update and the value to set the feedback property to. Looking at our call to sendData, we see two important changes. First, we have to compute the address of the register we want to update by adding the channel number (ch) to the base address (0xC0). Second, we need to pull the correct register value from our cache by using ch as the array index.

Operator Register Fns

Updating operator registers works the same way as channels, but with yet another twist. The channel registers are all in sequence, so computing the register address is super simple (just add the channel number to the base address). We aren’t so lucky with the operators.

Operators 1, 2, 3, 4, 5, and 6 all pair with register offsets 0, 1, 2, 3, 4, and 5… so far so good. But then… Operator 7 pairs with register offset 8! what happened to 6 and 7? Then, later, we skip offset locations 0xE and 0xF. Woof.

To get around this, we use an array that maps the operator number to the memory offset:

uint8_t op_map[YM3812_NUM_OPERATORS] = { 0,1,2,3,4,5,8,9,10,11,12,13,16,17,18,19,20,21 };

Let’s use the attack function as an example:

void regOpAttack( uint8_t op, uint8_t val ){ 
  sendData(0x60+op_map[op], SET_BITS( reg_60[op], 0b00001111, 4, val ) );
}

Now, instead of adding the operator number to the base address (like we did with channels), we add the mapped offset from our array.

All of the register functions follow these patterns, and when you put them together, they create a lovely and readable, almost table-like pattern:

Really, the only things that change are the function name, the base address, the register cache, the bitMask and the offset. And, of course, all of those values come from the Register Map.

For the full implementation of all of these functions, check out the GitHub repot. This version has been heavily simplified to match this article and will serve as a foundation for all of the other functionality we’ll be adding.

Making Music

The time has finally come… Let’s go back to our YM3812_Breadboard.ino file and put our library to good use. Again, we are going to keep this as simple as possible. There are two parts: setting things up in a setup() function, and then playing a sequence of notes in a loop() function.

setup()

The first thing we need to do is initialize the YM3812 library. I’ve defined a global instance of the library with the line:

YM3812  PROC_YM3812

Then, inside of the setup function, we initialize the library with the reset function:

PROC_YM3812.reset();

At this point, we get to set up the properties of the sound that we want to create. To keep this simple, let’s just tell every channel to have the same sound properties:

//Set up a patch
for( uint8_t ch=0; ch<YM3812_NUM_CHANNELS; ch++){   // Use the same patch for all channels
  op1_index = PROC_YM3812.channel_map[ch];
  op2_index = op1_index + 3;                        // Always 3 higher

  //Channel settings
  PROC_YM3812.regChAlgorithm(  ch, 0x1 ); // Algorithm (Addative synthesis)
  PROC_YM3812.regChFeedback(   ch, 0x0 ); // Feedback

  //Operator 1's settings
  PROC_YM3812.regOpAttack(   op1_index, 0xB );
  PROC_YM3812.regOpDecay(    op1_index, 0x6 );
  PROC_YM3812.regOpSustain(  op1_index, 0xA );
  PROC_YM3812.regOpRelease(  op1_index, 0x2 );
  PROC_YM3812.regOpLevel(    op1_index, 0x0 );      // 0 - loudest, 64 (0x40) is softest
  PROC_YM3812.regOpWaveForm( op1_index, 0x1 );

  //Operator 2's settings
  PROC_YM3812.regOpAttack(   op2_index, 0xB );
  PROC_YM3812.regOpDecay(    op2_index, 0x6 );
  PROC_YM3812.regOpSustain(  op2_index, 0xA );
  PROC_YM3812.regOpRelease(  op2_index, 0x2 );
  PROC_YM3812.regOpLevel(    op2_index, 0x0 );      // 0 - loudest, 64 (0x40) is softest
  PROC_YM3812.regOpWaveForm( op2_index, 0x1 );
    
}

As we loop through the channels, we have to first compute the index of the operators we want to modify. And of course, it’s quirky. Operator 2‘s index will always be 3 higher than Operator 1‘s. The pattern for Operator 1‘s index however, is less straightforward. To get around this, we are going to add another array to our YM3812 class that maps from channel number to its associated Operator 1 index:

uint8_t channel_map[YM3812_NUM_CHANNELS] = { 0,1,2,6,7,8,12,13,14 };

Now that we know which channel to modify as well as the associated operator indexes, the rest of the function configures each of the sound parameters using the register functions.

Loop()

Now finally, we get to play the four notes in our chord. And there are just a few steps to do it:

First, we turn off any notes that might happen to be on:

  PROC_YM3812.regKeyOn(  0, false ); //Turn Channel 0 off
  PROC_YM3812.regKeyOn(  1, false ); //Turn Channel 1 off
  PROC_YM3812.regKeyOn(  2, false ); //Turn Channel 2 off
  PROC_YM3812.regKeyOn(  3, false ); //Turn Channel 3 off

Then we set the octave we want the notes to be in:

  PROC_YM3812.regFrqBlock( 0, 4); //Fourth Octave
  PROC_YM3812.regFrqBlock( 1, 4); //Fourth Octave
  PROC_YM3812.regFrqBlock( 2, 4); //Fourth Octave
  PROC_YM3812.regFrqBlock( 3, 4); //Fourth Octave

Then we set the frequency for each of the notes:

  PROC_YM3812.regFrqFnum( 0, 0x1C9 ); // F
  PROC_YM3812.regFrqFnum( 1, 0x240 ); // A
  PROC_YM3812.regFrqFnum( 2, 0x2AD ); // C
  PROC_YM3812.regFrqFnum( 3, 0x360 ); // E

Wait… 0x1C9, 0x240, 0x2AD and 0x360 look nothing like F A C E… Nothing to see here… we will talk about that in the next article. Anyway… Finally, we turn the notes on:

  //Turn on all of the notes one at a time
  PROC_YM3812.regKeyOn(  0, true );
  delay(100);
  PROC_YM3812.regKeyOn(  1, true );
  delay(100);
  PROC_YM3812.regKeyOn(  2, true );
  delay(100);
  PROC_YM3812.regKeyOn(  3, true );
  delay(1000);

Now, I turned all of the notes on one at a time here by adding delays, but if you remove those, they would turn on all at once.

Final Thoughts

My goodness that was a long article. Apparently “FACE reveal” is a bit more involved than “hello world.” If you made it all of the way through, I hope that a lovely F Major 7th chord is echoing through your speakers at this very moment. If you ran into any trouble along the way, feel free to post questions in the comments. All of the working code is posted on gitHub, so hopefully that will help you in the troubleshooting process as well.

While the journey so far may have been arduous, it’s just getting started. Remember how I glossed over the frequencies for F A C E? Well, if we want to add midi control we are going to need a way to translate midi notes into those values. You know all of those register control functions we made? Eventually we are going to get rid of most of those—there’s a better way. But for now, don’t worry about all of that. Enjoy the fruits of your labor. See if you can create more interesting instruments than the one I used. Maybe program in a nice little jig! You got this.

In the next article, we’ll add midi control.

FACE Reveal

In the last article we dug into the YM3812 registers and how to manipulate them an electrical level. Today we are going to build up the first part of the schematic—just enough to get sound working through a microcontroller.

Whenever building on a new platform, What’s the first thing you implement? Hello World. It’s a great starting point that ensures everything works—the hardware, the development toolchain, etc. We need an equivalent project for our YM3812 that uses sound instead of text on the screen. We need… a FACE reveal! (you know… play an F major 7th chord… F A C E… yeah… woof… #DadJokes 🙄). OK but seriously… to play a note on this chip, we need working hardware, a library that interfaces with the chip, a properly configured voice, and the ability to turn on/off a note at the right frequency. This is going to be an epic journey… and it’s going to take two articles to complete. In this article, we will start with the hardware and schematic, and then upload the code from the GitHub repo using the Arduino IDE. Then in the next article, we will look into the code in a bit more detail to see exactly how it’s working.

The Components

In the spirit of starting small, I’ve pulled together a simple implementation of the YM3812 hardware. Technically, you could simplify this further—interfacing the full 8-bit data bus directly with the microcontroller, or having the microcontroller produce the 3.58 MHz clock. But we are going to need some of those pins down the line and this all fits on a single breadboard. Let’s take a look at our cast of silicon characters.

AVR128DA28 Microcontroller

I like to think of the AVR128DA28 as an Arduino Nano, but in chip form—and far more capable. This chip sports:

• 128kb of program memory and16kb of ram
• 10 AD converters, and a DA converter
• I2C, SPI, UART, and even 4 hardware serial ports
• Operating voltage of 1.8v to 5.5v
• Internal auto-tuned 24 MHz oscillator
• UPDI programing & Arduino IDE Support
• And sooooo much more…

All in an itty bitty 28pin DIP package. There are even more powerful surface mount versions of the chip as well, but this will give us plenty of oomph in our project. I have to give a shout out here to Robbie Langmore from Tangible Waves for introducing me to these microcontrollers. In a world of chip shortages, there are still ~300 in stock at mouser—as of writing this.

74HC595 Shift Register

The 74HC595 shift register is next in our lineup. This chip converts the serial output from the AVR’s SPI bus and converts it into the 8-bit parallel bus that bus required by the YM3812.

YM3812 OPL2 Sound Processor

If you are reading this article and wondering what this chip does, then I highly recommend reading part one of this series. Other than some decoupling capacitors, the YM3812 requires a a 3.58Mhz crystal oscillator.

Y3014B DAC

Unlike some of the other YM sound processors, the YM3812 does not have an analog output. Instead, it needs to be paired with the Y3014B 10-bit Digital to Analog Converter. This chip takes a serial data stream coming from the YM3812 and converts it into an analog output. The Y3014B requires a voltage of 1/2 VCC on pin 8 (MP) to bias the output signal (pin 2) around. Fear not though, it produces its own reference voltage on pin 8 (RB), but you still need to buffer that voltage using an operational amplifier. Also, buffering the output signal (pin 2) with an operational amplifier is another solid plan.

TL072 / LM358 OpAmp

Did somebody say operational amplifier? OpAmps are the workhorses of Eurorack Modules and Analog Circuitry in general. Unless it’s a passive attenuator, odds are, there’s going to be 1 or maybe 10 of these versatile building blocks. In our case, will use these to buffer the reference voltage and output signal generated by the Y3014B.

Other Parts

After the ICs, there’s only a handful of other parts.

• The six .1uF capacitors provide decoupling for the ICs
• The two 10 uF capacitors stabilize the reference voltage on the Y3014b
• And the 4.7 uF capacitor provides capacitive coupling on the audio output
• The 100k resistor ties the output capacitor to ground and the 1k resistor ensures appropriate output impedance
• The 1N4148 signal diode converts the single-wire UDPI pin into separate Tx/Rx pins that attach to an FTDI cable
• Lastly, a micro-switch provides a reset button for the AVR microcontroller.

Schematic Time!

Microcontroller Connections

Now that we’ve talked through how the pieces work, the schematic should seem pretty straightforward. The Clock (pin 26) and Data (pin 28) of the SPI bus of the AVR128DA28 connects to the Serial Data (pin 14) and Shift Clock (pin 11) inputs on the 74HC595 shift register. PortD-3 (Pin 9) on the microcontroller connects to the Latch Clock (pin 12) on th 74HC595 and latches the output of the register. This sends the 8 Data Bits (pins 15, 1-7) to the YM3812 Data Inputs (pins 10-11, 13-18).

PortD 0, 1, 2 and 4 (pins 6, 7, 8, 10) on the microcontroller connect to the four control lines of the YM3812—Write (pin5), A0 (pin 4), Initialize/Clear (pin 3), and Chip Select (pin 7) respectively. On the YM3812, tie Read (pin 6) high to prevent rogue reads. IRQ (pin 2) can be left floating in the breeze.

Sound Processor & DAC Connections

The Output of the 4.58 MHz Crystal Oscillator flows in to the Master Clock Input (pin 24) on the YM3812. Enable (pin 1) on the oscillator should float. Tying it to ground disables the clock output.

The Serial Data and Clock output pins on the YM3812 connect to the Serial Data and Clock input pins on the Y3014B and transfers the raw sound data to the DAC. Sample & Hold (pin 20) on the YM3812 connects to the Latch (pin 3) on the Y3014B, and updates the analog value of the output.

The Y3014B produces a reference voltage of 1/2 VCC on RB (pin 7) which the TL072 then buffers and sends back to the output bias control pin MP (pin 8) on the Y3014B. C7 and C8 stabilize the reference voltage.

The Analog Output signal of the Y3014B (pin 2) get buffered through another operational amplifier on the TL072 before passing through a coupling capacitor (C8) to remove the DC bias. A high value resistor (R1) ensures our output stays centered at ground, and R2 ensures our output remains at a 1k impedance.

The Other Stuff

Of course all of the ICs require decoupling capacitors on their power pins (C1 – C6). And a reset button connects the Reset Line (pin 18) of the AVR128DA28 to ground. As far as I can tell, the reset button doesn’t require a debouncing filter, you can just directly connect it.

Lastly, the AVR128DA28 can be programmed through a one-wire Universal Programming & Debugging Interface. If you don’t have one of those programmers, you can use an FTDI to USB connector. There are many variations of this connector, some include the RTS/CTS lines (which we don’t use) and some don’t. Also, there are a couple of color variations of the wires on the connector. Here is an alternate color scheme that I have seen:

Starter Code

Our circuit isn’t going to do much without a bit of code. We need to program the microcontroller to see if everything works. As it happens that I created a simple library on my GitHub for just that purpose. I’ve trimmed it down to its basic elements and added loads of comments to make things as readable as possible. Feel free to download and play around with it, and in the next video we’ll dive into exactly how the code works.

Note, to get the YM3812_Breadboard.ino file to work, you will need to create a “YM3812_Breadboard” folder in your Arduino folder and then copy YM3812_Breadboard.ino, YM3812.h, and YM3812.cpp into it.

Programming the Micro

Assuming that you chose to use an AVR128DA28 as your microcontroller, you’ll need to install the DxCore in your Boards Manager. DxCore is an open sourced library written by Spence Konde that allows you to use the AVR128 line of microcontrollers in the Arduino IDE. There are detailed installation instructions on the GitHub, but this should at least get you started.

First we need to add a URL to the Additional Boards Manager URLs. To do that, open the menu: Arduino > Preferences:

Enter the url, http://drazzy.com/package_drazzy.com_index.json in the Additional Boards Manager URLs text box as shown above.

Then, locate the boards manager in Tools > Boards:… > Boards Manager

Search for DxCore and locate a package that looks similar to the one below:

After installing the DxCore boards library, you should be able to select the AVR DA-series (no bootloader) from the board menu. Also, select AVR128DA28 as the chip, and 24 MHz Internal as the Clock Speed.

The programmer that worked best for me was SerialUPDI – 230400 baud. It’s quite fast.

Now, just connect your FTDI cable as described in the schematic section of this article. And fingers crossed your program should upload directly into the micro. If it doesn’t… check that the Tx/Rx pins aren’t swapped—I’ve done that a few times.

Final Thoughts

With any luck, you have now experienced the total exhilaration of getting the YM3812 to generate that F Major 7 chord! Realistically, ANY sound at this point is great, because it shows that the hardware is working. If you got everything working, feel free to leave a comment. Similarly, if you see any issues in the schematic, let me know. After all, I’m still learning too!

In the next article, we will look through the code in detail.

Errata

• In the schematic, the labels on the SPI Clock and MOSI lines were swapped. Thank you to Peter Hesterman for catching this one!

Introduction

In conducting a pretty extensive deep dive into Yamaha’s FM synthesis chips, I’ve come to realize that while these chips produce very unique sounds, they are also largely very similar. In fact, if you compare their register settings (and ignore the level of granular control that you get), you can see just how many of the settings are the same:

With all of these similarities in mind, I originally planned to build a single module with a variety of sound processor types all controlled by a single microcontroller. After breadboarding this idea out with a YM3812, YM2151 and even a non-Yamaha SN76494, it worked! And I was even able to translate chip settings from one chip to another seamlessly. But when I started to document how it worked, I realized from a complexity standpoint, I needed to back waaaay up and start from the beginning. To get into the advanced stuff, we need to start with a smaller project that lays a strong foundation. And what better foundation than a Eurorack module powered by Yamaha’s YM3812 OPL2 sound chip. A chip that revolutionized computer audio for the video games of my childhood.

This article is only the first in a series. Together, we will tour the properties of the YM3812, design the hardware for a module and write the supporting microcontroller code. Hopefully, each article will pair with a YouTube video on the subject as well.

Why the YM3812?

If you grew up in the 80’s and 90’s and played video games on a PC, then it is highly likely that you have listened to the glorious 8-bit audio output of a YM3812 sound processor. To me, this sound is synonymous with Sierra and Lucas Arts adventure games. I can still remember reading advertisements for the sound card in Sierra’s interAction magazine. The idea of getting music and sound effects other than square waves from a computer was like magic. So after saving up my dog-sitting money I bough a SoundBlaster Pro from Fry’s electronics. The first time using this thing was symphonic—it took adventure gaming to a whole new level. Now, 30-ish years later, I want to recapture that magic.

From a more practical standpoint, the YM3812 supports only two operators per voice making it significantly simpler to understand than other 4-operator or even 6-operator FM synthesizers. But don’t be fooled, this is still a powerful chip, capable of creating a vast variety of nostalgia-generating instrumental and percussion sounds—and that’s what makes this chip such a great starting point.

How does FM synthesis work on the YM3812?

Let’s start with a quick review of FM Synthesis and how sound processors use it to produce sound. The YM3812 is an FM Synthesis sound processor. It plays up to 9 different sounds (voices) simultaneously, with each sound composed of two different operators.

An operator is the basic building block of FM synthesis. It contains an oscillator that generates a sound wave, and an envelope that adjusts the sound’s level over time. Each voice of the YM3812 includes two of these operators, and they combine together using two possible algorithms:

Mixing is the simplest form of “synthesis.” It adds the output of the two oscillators together like a mixer. In the output, both oscillators’ sounds are audible and distinct.

Frequency Modulation uses the first operator (called the modulator) to modulate the second operator (called the carrier). In this style, only the level of the carrier operator affects the level (volume) of the output signal. The level of the modulator operator affects the brightness of the timbre of the output. The higher the modulator level, the brighter the sound will be.

Frequency Modulation Demo

Words simply can’t do this justice, so let’s try a demonstration. I’ve connected an oscilloscope to the output of the final module (spoiler alert… the module eventually does work and this story will have a happy ending). I configured the module into Frequency Modulation mode and set the modulator operator to have a slowly decaying envelope. This way, you can hear how the amount of modulation changes the timbre of the sound as it slowly decreases. After playing a few notes, I also show how using different waveforms for the modulator and carrier signal also change the overall output.

Notice how the brightness quickly drops as the level of the modulating operator decays. In the Oscilloscope, it looks like the waveform collapses back into itself. Pretty cool right? Let’s try something even more mind bending…

Feedback

In the YM3812, the modulator operator (operator 1) also has the ability to modulate itself. What does that mean? This was incredibly difficult to wrap my head around, so I made an animation that starts with a sine wave and slowly increases the amount of feedback. As the amount of feedback increases, the waveform shifts from a sine wave into something more like a sawtooth wave. Then, after adding too much feedback, the wave deteriorates into inharmonic white noise. While less than musical, this white noise is a critical component of making percussive sounds on the YM3812, so it’s actually a good thing!

As an experiment to see if my animation aligns with reality, I plugged the final module into an oscilloscope. Now, we only want operator #1 because that is the operator that has the option for feedback. So, I set the module in mixing mode and turned the second operator’s signal all of the way down. This ensures that only the first operator’s signal appears in the output. I then set the first operator’s waveform to be a sine wave and then slowly increased the amount of feedback. You can see it shift from sine to saw… to crazy…

Types of Settings in the YM3812

The register settings that control sound production on the YM3812 fall into three different categories.

• Operator Level settings control how the oscillator and envelope functions. Oscillator settings include things like the waveform, detuning, and vibrato, while the envelope settings include things like attack, decay, sustain, and release. Operator settings have to be defined for every operator on the chip, so there are 18 sets of these settings on the YM3812.
  
• Channel level settings determine how the operators will work together to form a sound, as well as the things that affect that sound overall. Channel settings include the pitch of the note to play, whether the sound is turned on or off, and adding effects like tremolo and vibrato.
  
• Global level settings control the general properties of the chip like turning on “drum mode” or affecting internal chip timers. The “Deep Tremolo” and “Deep Vibrato” settings change the amount of vibrato / tremolo applied to the channels that have vibrato / tremolo enabled. Because these two settings are global, they affect all channels at once. As for the drum mode, you get 6 drum sounds for the cost of 3 channels. It seems like a good thing, but realistically you can achieve far superior drum sounds using normal instrument settings.

What are Registers?

In order to produce sound, the YM3812 uses a set of special-purpose memory locations to store the sound settings called registers. Because space comes at a premium, and there are so many different settings to store, the YM3812 compresses multiple settings into each register byte. So, for example, let’s say we found the value stored at register 0x41 to be 0x4C.

This value represents two different settings—Level Scaling and Total Level for Operator 1 of Channel 2. To understand how these values were combined, you have to look at the value of 0x4C in a binary representation. As shown above, this translates to a binary value of 01001100. The top bits on the left (the two “highest” bits) store the value “01” or in decimal, 1 and the next 6 bits store the value 001100 or in decimal, 12. The first number maps to the Level Scaling setting and the second to Total Level. Combining variables in this way saves memory because not every setting requires 8 bits to represent its value. Conversely, this also means that the maximum integer value a variable represents depends on the number of bits used.

For example, a 1-bit number, can only be on or off, where as a 2-bit number can have 4 states (0-3). The number of allowable states doubles with each successive bit, until you get to a maximum of 256 (0 – 255) for an 8-bit number.

Note, the Frequency Number setting is the only one that uses MORE than 8 bits. This value is broken up across two register settings: an 8-bit Frequency Number LOW setting and a 2-bit Frequency Number HIGH setting. To combine these into a single 10-bit value, you shift the 2 high bits over to the left 8 times and then logically OR it with the low setting.

Finding Register Locations

Earlier, I pulled a random location 0x41 and somehow said, “oh that’s these two settings.” How the heck did I know that? Well, the answer is that I looked it up in the data sheet. But I think with a spreadsheet and a little information design, we can build a simple map to use going forward.

Global Registers

The chart above shows how settings map to the memory locations shown on the right. These 6 global registers scrunch together 18 different settings. The left side of the chart shows how the settings map to each bit of those 6 bytes. The D0 column represents the lowest bit in the byte and D7 represents the highest bit. So for example, if you wanted to set the Deep Vibrato flag’s setting, you take the current value of BD and do a logical OR with 0b01000000 to set the correct bit, and then write the result into the BD register.

Channel Registers

The channel-level registers follow a similar pattern, but with one added twist. Instead of each register type having one location in memory, they have 9—one for each channel. The columns on the left still indicate how bits map to settings, but now the columns on the right show the memory location of the register that corresponds to each channel. So, for example, if I wanted to turn sound generation on for Channel 5, I would have to set bit 5 of memory location 0xB4 to a 1, and that would play the note.

One more note, the base address column in the center provides the memory location of the first channel, and we can use it as an offset to calculate the other memory locations. So if we wanted the memory location of the “B0” setting of channel 5, we could find it with the formula, “0xB0 + 5 – 1”. The minus 1 is in there because the channel names are “1 indexed” instead of “0 indexed” If you labeled them channel 0 – 8, then “channel 5” would become “channel 4” and the formula would just be “0xB0 + 4”

Operator Registers

The operator-level register add a bit more complexity to the mix. I’ve laid them out in a similar fashion with the mapping of bits to setting types on the left and memory locations on the right, but now we have 18 different locations to contend with—one for each operator—instead of 9. For every channel, there are two operators—a Modulator and a Carrier. We can also abstract these into “Slot 1” and “Slot 2” because in other Yamaha chips, there are up to 4 operators per channel and numbers add clarity.

I’ve arranged the memory location columns in the table above to keep each operator visually connected with its associated channel. If you look closely, a curious pattern emerges. Channel 1 associates with operators 1 and 4, Channel 2 associates with operators 2 and 5, and so-on. The carrier operator number is always three higher than the modulator’s operator number.

In the chart above, the row below the operator numbers (that starts, “+0, +3, +1,…”) represents the memory offsets for each operator from the base address. So to find a memory location for a specific operator, you could add this value to the base address associated with the setting you want to change. Here again, there is another “gotcha.” The memory locations JUMP between channels 3 and 4, and skip offsets 0x6 and 0x7. A similar jump occurs between channels 6 and 7, where we skip offsets 0xE and 0xF as well. As far as I can tell, the easiest way to manage this is to put the offsets into an array that maps operator to memory location.

Full Register Map

If we put all of these pieces together, the full register map emerges:

If you want to develop code that controls a YM3812, I highly recommend printing this chart, laminating it and pinning it to you wall. You are going to need it!

Oh, one other thing, if you turn on drum mode then channels 7, 8, 9 become dedicated to drum sound production. I’ve indicated this with orange asterisks in the chart above. Again, I’d recommend against using the default percussion sounds, but hey, it’s there if you need it!

Setting Registers on the YM3812

Now that we know the mapping of settings to register locations, let’s talk about how to set those registers… electrically.

YM3812 Pins

The pins of the YM3812 fit into three different types. The power pins connect to 5v and ground. The three pins in yellow provide a serial connection to the Y3014b digital to analog converter chip. The 8 pins in blue connect to the data bus, and the 6 green pins work as control lines. There are also a few unused pins in grey that we can ignore.

For this exercise, our interest lies in the 8 data lines and the A0, Write, and Chip Select control lines. The Init-Clear pin will clear the contents of the chips registers, and the IRQ and read pins are used to read status information from the chip. Unfortunately, you can’t read the contents of a register, so honestly reading information from the chip just isn’t that useful.

Selecting Registers & Sending Data

Setting the register requires two main steps: selecting the register, and setting its data. To select a register, we:

• Begin with the Chip Select and Write control lines high (disabled). The A0 line could be either high or low.
• Set the Chip Select line low to enable the chip
• Set A0 low to tell the YM3812 that we are selecting a register
• Put the address of the register we want to write onto the Data Bus
• Set Write to low to tell the YM3812 to use the data on the Data Bus to select the register
• Wait 10 microseconds
• Set Write to high to complete the write cycle
• Wait 10 microseconds. At this point the register is selected
• Flip the A0 control line high to indicate that we are now writing data into the register
• Put the value onto the Data Bus to write into the selected register
• Set Write to low to tell the YM3812 to write the data into the selected register
• Wait 10 microseconds
• Set Write to high to complete the write cycle.
• Wait 10 microseconds. At this point, the data has been written into the YM3812
• Set Chip Select back to high to disable the YM3812 again

And that’s it! If you followed the steps above, then you have written data into a register!

Wrap Up

Now that you know where all of the registers are on the chip, and how to manipulate them, you have the fundamental building blocks to control the YM3812. Of course getting from register setting to a working MIDI controlled module will require a bit more discussion. My hope is to take these topics one at a time in future articles. In the next article, let’s go through the module schematic, and after that we will get into some more software algorithms.