DOCSEARCHbyAlgolia
Submit Docs

Arduino OPL2 Library

repository·master·Indexed 42 days ago

https://github.com/dhrbaksteen/arduinoopl2

An audio library for Arduino-compatible hardware, Teensy, and Raspberry Pi to interface with OPL2 (YM3812) and OPL3 (YMF262) synthesis chips. It enables music playback of DRO, IMF, and VGM files, MIDI synthesis, and custom synthesizer building with support for Adlib and 'The Fat Man' instrument definitions.

Tokens
7.9K
Snippets
23
Records
41
Agent score
53%

What's inside Arduino OPL2

  1. Overview of the Arduino OPL2 Library

    master

    The Arduino OPL2 Library provides support for OPL2 and OPL3 audio chips, specifically designed for the OPL2 Audio Board (YM3812) and the OPL3 Duo! board (dual YMF262). It is compatible with Arduino, Teensy, Raspberry Pi, and other Arduino-like boards.

    Key Capabilities:

    • Chip Support: Experiment with YM3812 (OPL2) or YMF262 (OPL3) chips.
    • Synthesizer Building: Build custom synthesizers or play OPL2 tunes.
    • Instrument Definitions: Includes Adlib and 'The Fat Man' instrument definitions for both 2-op and 4-op OPL3.
    • File Playback: Play exported OPL2 music files (DRO, IMF, VGM) or Reality Adlib Tracker music files.
    • MIDI Support: Use the board as a MIDI synthesizer (examples provided for Teensy++ 2.0 and later).
    • DosBox Emulation: Output MIDI music from DosBox using the board (Teensy++ 2.0 and later).
    • Direct Use: The board can be used directly as a synthesizer via the OPL3BankEditor software.

  2. Set Oscillator Frequencies using Blocks and F-numbers

    master

    Oscillator frequency is determined by a combination of a Block Number (defining the frequency range) and an F-number (the fine-tuning value within that range).

    • Block Number: A value from 0 to 7. Higher blocks correspond to higher frequency ranges (effectively acting as octaves).
    • F-number: A value from 0 to 1023.

    Register Mapping:

    • Block Number: Bits 2, 3, and 4 of base register 0xB0.
    • F-number (Lower 8 bits): Stored in base register 0xA0.
    • F-number (Upper 2 bits): Bits 0 and 1 of base register 0xB0.

    Setting the F-number to 0 always results in 0 Hz regardless of the block.

  3. Hardware Support: OPL2 Audio Board vs OPL3 Duo! Board

    master

    The library supports two specific hardware configurations:

    OPL2 Audio Board

    • Chip: YM3812 (OPL2).
    • Capabilities: 9 channels with 2-operators each, producing classic early 90s computer game sounds.

    OPL3 Duo! Board

    • Chip: Dual YMF262 (OPL3).
    • Capabilities: Supports up to 36 channels of 2-operator sounds, or a mix of up to 12 4-operator + 12 2-operator sounds.
    • Audio: Features stereo sound and is fully OPL2 compatible.
    • Control Modes: Each OPL3 chip can be controlled individually, or the library can treat the entire board as a single large OPL3 chip with 36 channels.

  4. Understand OPL3 special features

    master

    The OPL3 (YMF262) chip is backward compatible with OPL2 but offers significantly more capabilities. To access these, you must first enable OPL3 mode.

    Key Differences & Features:

    • Channels: 18 channels total (vs 9 on OPL2).
    • Operator Configuration: Supports 18 2-operator channels, 6 of which can be configured as 4-operator channels.
    • Waveforms: 4 additional waveforms (8 total).
    • Digital Output: 4 digital output channels (allowing for advanced stereo/multichannel setups).

    Note: When reset, the OPL3 starts in OPL2 compatible mode. You must explicitly enable OPL3 mode to use the advanced features.

  5. Configure Synthesizer Mode (AM vs FM)

    master

    The YM3812 (OPL2) and YMF262 (OPL3) chips allow channels to operate in either Additive Synthesis (AM) mode or Frequency Modulation (FM) mode.

    • AM Mode: The outputs of the two operators are added together.
    • FM Mode: The output of Operator 1 (the modulator) influences the frequency of Operator 2 (the carrier).

    This mode is controlled via bit 0 of base register 0xC0. Setting this bit to 0 enables FM mode, while setting it to 1 enables AM mode.

  6. Adjust Operator Frequency Multipliers

    master

    Each operator has a frequency multiplication factor that scales the channel's base frequency. This allows for complex harmonic structures.

    • Multiplier Range: 0 to 15.
    • Special Case: Setting the multiplier to 0 results in a multiplication factor of 0.5.
    • Register: The multiplier is set in the lower 4 bits of base register 0x20.

  7. Connect the OPL2 Audio Board to Raspberry Pi / Orange Pi

    master

    Use the following GPIO mapping for Raspberry Pi or Orange Pi boards.

    | OPL2 Board | GPIO Pin |
|------------|----------|
| +5v        | 2        |
| GND        | 6        |
| A0         | 16       |
| Data       | 19       |
| Latch      | 12       |
| Shift      | 23       |
| Reset      | 18       |

  8. Install the Arduino OPL2 Library on Raspberry Pi or Orange Pi

    master

    To install the library on a Raspberry Pi or compatible board:

    1. Clone this repository to your device.
    2. Run the build script:
      ./build

    Requirement: The library requires WiringPi to be installed. The ./build script can automatically install WiringPi if it is not already present on your system.

    ./build

  9. Assemble the OPL2 Audio Board

    master

    Follow these steps to manually assemble the OPL2 Audio Board from a kit. The assembly order follows component height from smallest to tallest.

    1. Resistors (R1-R4): Bend legs 90 degrees, insert through PCB, solder, and clip excess leads. Polarity does not matter.
    2. Pin Header (J1): Solder one pin first to align the header flush to the board, then solder the remaining pins.
    3. Crystal (XTAL1): Insert the 3.579 MHz crystal (orientation doesn't matter), solder, and clip leads.
    4. Capacitors (C1-C8): Insert and solder. Orientation does not matter.
    5. Sockets or ICs (IC1-IC6): It is recommended to use sockets. Align the notches/cutouts correctly. Solder one pin first to ensure the component sits flat, then solder the rest.
    6. Audio Output (J2): Choose either a 3.5mm jack plug socket or a 3-pin terminal block for speakers. Solder the center pin first to ensure it sits flat before soldering the rest.
    7. Volume Potentiometer (R5): Insert and solder the 10kΩ trimmer potentiometer.
    8. Electrolytic Capacitors (C9-C10): Note polarity. The negative band must face the hole with the minus symbol or the square pads.
    9. ICs: If using sockets, insert the ICs last. Align the notches on the ICs with the notches on the board. Ensure the round cut-out on the IC faces the notch.

  11. Install the Arduino OPL2 Library

    master

    You can install the library using one of three methods:

    1. Arduino Library Manager: Open the Library Manager in the Arduino IDE (Sketch > Include Library > Library Manager), search for Arduino OPL2, and click Install.
    2. Git Clone: Clone this repository directly into your Arduino libraries folder.
    3. ZIP File: Download the ZIP file and extract it into your Arduino libraries folder.

  12. Connect the OPL2 Audio Board to Arduino

    master

    Use the following pin mapping to connect the OPL2 Audio Board to an Arduino.

    Note for Arduino Mega users: Use pins 51 and 52 for the Data and Shift connections respectively (standard SPI pins).

    | OPL2 Board | Arduino Pin |
|------------|-------------|
| A0         | 9           |
| Data       | 11*         |
| Latch      | 10          |
| Shift      | 13*         |
| Reset      | 8           |

*Use pins 51 and 52 respectively on Arduino Mega.