===== SID Library =====
The library provides the setup and communications functions to interface an Arduino board with a [[MOS6581]] Sound Interface Device (SID).
Connecting the Arduino board to the SID is made through the Arduino hadware SPI interface, using 74hc595 deserializers.
Schematic, Layout and Source Code of the associated Midi Synth project SIDaster can be found here : http://bit.ly/SIDaster

==== Download ====

Download Link : {{:sid_lib_v4.zip|}}


==== Installation ====

As simple as an Arduino library installation:

  * Go to your ''Arduino\Library'' subfolder.
  * delete any previous installation of the SID library by removing the ''SID'' folder
  * Extract files from the library archive to your ''Arduino\Library'' subfolder.

==== Usage ====

You shall first include the library inside its Arduino design by addin a call to the library:

''#include « SID.h »''

Then you need to create an instance of the SID type, and initilalise it:

  * Create a SID synth by declaring it : ''SID mysid;''
  * In the Arduino ''setup()'' function, shall setup successively the clock and the SPI interface by calling in this order
    * ''mysid.clk_setup();''
    * ''mysid.SPI_setup();''
  * Send bytes to the SID by using ''sid.send(Address, Data);'' 

Address is the SID address ranging 0-24 as mentionned in the SID datasheet, and the Data is the byte you want to write. See the [[mos6581]] datasheet for more details on how to program the Chip.

==== Code example ====

Here is an example of how to use the library, showing how to combine the ''Midi'' library and the ''SID' library.

<sub>note: it's a reduced version of a engineering version of the SIDaster, lots of things have been deleted to ease comprehension, however brute force copy paste of this code shall not compile properly under Arduino IDE.</sub>

<code C>
#include <SID.h>
#include <MIDI.h>

// Pulse width must be less than 0x0FFF (4095)
// note - must also be higher than nothing if using a square wave
//
#define PULSE_WIDTH 0x0

// These all must be below 0x0F (15) 

//==============================
// GLOBAL SYNTH VARIABLES INIT
//==============================

SID sid;

// Play sound at frequency specified on voice specified
//
void synth_on(int note) 
{
  freq1=NOTES[note];
  sid.send(SID_FREQ1LO,char(freq1));
  sid.send(SID_FREQ1HI,char(freq1>>8));
  freq2=NOTES[note+3];
  sid.send(SID_FREQ2LO,char(freq2));
  sid.send(SID_FREQ2HI,char(freq2>>8));
  freq3=NOTES[note+7];
  sid.send(SID_FREQ3LO,char(freq3));
  sid.send(SID_FREQ3HI,char(freq3>>8));
  ctrl1|=1;
  sid.send(SID_CTRL1,ctrl1);
  ctrl2|=1;
  sid.send(SID_CTRL2,ctrl2);
  ctrl3|=1;
  sid.send(SID_CTRL3,ctrl3);
}

void synth_off(int note) 
{
  ctrl1&=~1;
  sid.send(SID_CTRL1,ctrl1);
  ctrl2&=~1;
  sid.send(SID_CTRL2,ctrl2);
  ctrl3&=~1;
  sid.send(SID_CTRL3,ctrl3);
}

// Debug 2 bytes of data via the address + data shifters
//

// Initially executed code
//
void setup() 
{
  // Set up the SID chip
  sid.clk_setup();
  sid.SPI_setup();

  // Give the voices some initial values
  // Set up the MIDI input
  MIDI.begin();
  MIDI.setHandleNoteOn(DoHandleNoteOn);
  MIDI.setHandleNoteOff(DoHandleNoteOff);

  synth_init();

}

// Main program loop
//
void loop() {
  MIDI.read();
}

// Note On Handler
// PS : The if / else is implemented because some Midi equipements do not use Note Off, but use instead note On with velocity = 0 
void DoHandleNoteOn (byte channel, byte note, byte velocity) {
   synth_on(note);
}


void DoHandleNoteOff (byte channel, byte note, byte velocity) {
  synth_off(note);
}
</code>

==== Changelog ====
See the SID.h file comments for library changelog.