Differences

This shows you the differences between two versions of the page.

--- sid_library [2011/09/27 10:06] – created wadmin
+++ sid_library [2018/08/26 09:36] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
-This library allows the operation of the SIDaster Shield (V2.3+) by specifying setup / communication functions. See the comments inside the library file files for in depth description.
+===== 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.
@@ Line 7: / Line 17: @@
   * 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();
- One shall first include the library inside its design: #include « SID.h »
+}
-Then create a SID synth by declaring it : SID sid;
+// Main program loop
+//
+void loop() {
+  MIDI.read();
+}
-In the Arduino setup() function, one shall setup successively the clock and the SPI to operate the SID:
+// Note On Handler
-sid.clk_setup();
+// PS : The if / else is implemented because some Midi equipements do not use Note Off, but use instead note On with velocity = 0
-sid.SPI_setup();
+void DoHandleNoteOn (byte channel, byte note, byte velocity) {
+   synth_on(note);
+}
-You eventually can 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.
+void DoHandleNoteOff (byte channel, byte note, byte velocity) {
+  synth_off(note);
+}
+</code>
+==== Changelog ====
+See the SID.h file comments for library changelog.