improved documentation (slightly!)

2 files changed, 117 insertions, 9 deletions

diff --git a/include/app.h b/include/app.h
index 51eef58..8f33e48 100644
--- a/include/app.h
+++ b/include/app.h
@@ -1,14 +1,54 @@
-//
-//  app.h
-//
-
 #ifndef LAUNCHPAD_APP_H
-#define LAUNCHPAD_APP_H

-

-// ____________________________________________________________________________

+#define LAUNCHPAD_APP_H
+
+/******************************************************************************
+ 
+ Copyright (c) 2015, Focusrite Audio Engineering Ltd.
+ All rights reserved.
+ 
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are met:
+ 
+ * Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+ 
+ * Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+ 
+ * Neither the name of Focusrite Audio Engineering Ltd., nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+ 
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ 
+ *****************************************************************************/
+
+// ____________________________________________________________________________
 //
 #include "app_defs.h"
 
+/******************************************************************************
+ Button indexing is as follows - numbers in brackets do not correspond to real
+buttons, but can be harmessly sent in hal_set_led.
+ 
+ (90)91 92 93 94 95 96 97 98 (99)
+ .......
+ 20  21 22 23 24 25 26 27 28  29
+ 10  11 12 13 14 15 16 17 18  19
+ (0)  1  2  3  4  5  6  7  8  (9)
+ 
+ *****************************************************************************/
+
 // ____________________________________________________________________________
 //
 // Interface to the hardware (implemented in launchpad_pro.a library)
@@ -17,17 +57,34 @@
 /**
  * Set an LED's RGB value.  This function is safe to call from any
  * of the app functions below, at any time.
+ *
+ * @param type - TYPEPAD to address any pad or button, TYPESETUP to address the Setup button
+ * @param index - The index of the button.  The buttons are indexed from the bottom left as detailed above.
+ * @param red - red colour value, in [0, MAXLED]
+ * @param green - green colour value, in [0, MAXLED]
+ * @param blue - blue colour value, in [0, MAXLED]
  */
 void hal_plot_led(u8 type, u8 index, u8 red, u8 green, u8 blue);
 
 /**
  * Send a MIDI message to either USB port or to the DIN output.
+ * 
+ * @param port - which port to send the message to - can be USBSTANDALONE, USBMIDI or DINMIDI.
+ * @param status - MIDI status byte
+ * @param data1 - first MIDI data byte
+ * @param data2 - second MIDI data byte
+ *
+ * There is little error checking in this code - if you send invalid MIDI, the results are undefined!
  */
-void hal_send_midi(u8 port, u8 status, u8 d1, u8 d2);
+void hal_send_midi(u8 port, u8 status, u8 data1, u8 data2);
 
 /**
  * Send system exclusive to USB or DIN.  Messages must be correctly formatted
  * (F0 ... F7) and must not exceed 320 bytes.
+ *
+ * @param port - which port to send the message to - can be USBSTANDALONE, USBMIDI or DINMIDI.
+ * @param data - pointer to array containing sysex data.
+ * @param length - must not exceed 320 bytes.
  */
 void hal_send_sysex(u8 port, const u8* data, u16 length);
 
@@ -45,29 +102,45 @@ void app_init();
  *  1kHz (1ms) timer.  You can set LEDs and send MIDI out from this function,
  *  but you will get LED tearing as there is (currently) no double buffering.
  *
- *  You will get jitter.
+ *  You will get some jitter.
  */
 void app_timer_event();
 
 /**
  * Called when a MIDI message is received from USB or DIN.
+ *
+ * @param port - the port the message was received from - USBSTANDALONE, USBMIDI or DINMIDI.
+ * @param status - MIDI status byte
+ * @param data1 - first MIDI data byte
+ * @param data2 - second MIDI data byte
  */
 void app_midi_event(u8 port, u8 status, u8 d1, u8 d2);
 
 /**
  * As above, but for system exclusive messages.  Low level hardware buffering sets
  * a maximum message size of 320 bytes, messages larger than this will not work.
+ *
+ * @param port - the port the message was received from - USBSTANDALONE, USBMIDI or DINMIDI.
+ * @param data - pointer to array containing sysex data.
+ * @param length - the amount of data received.
  */
 void app_sysex_event(u8 port, u8 * data, u16 count);
 
 /**
  * Called when a MIDI DIN breakout cable is connected or disconnected.  Note that
  * you can still write MIDI events to the DIN ports even if no cable is connected.
+ *
+ * @param type - which cable was connected/disconnected - MIDI_IN_CABLE or MIDI_OUT_CABLE.
+ * @param value - 0 = disconnected, nonzero = connected.
  */
 void app_cable_event(u8 type, u8 value);
 
 /**
  * Called when the user presses or releases any button or pad on the control surface.
+ *
+ * @param type - TYPEPAD for normal pads or buttons, TYPESETUP for the Setup button
+ * @param index - The index of the button, as detailed at the start of this file.
+ * @param value - 0 for release, nonzero for press.
  */
 void app_surface_event(u8 type, u8 index, u8 value);
 
@@ -77,6 +150,9 @@ void app_surface_event(u8 type, u8 index, u8 value);
  * threshold to prevent excessive aftertouch after the initial hit, at the expense of
  * dynamic range.  This firmware does not - the full range of the pad is transmitted,
  * with the side effect that aftertouch onset is more rapid.
+ *
+ * @param index - The index of the pad, as detailed at the start of this file.
+ * @param value - the aftertouch value in [0, 127]
  */
 void app_aftertouch_event(u8 index, u8 value);
 
diff --git a/include/app_defs.h b/include/app_defs.h
index b339ed1..cc7493b 100644
--- a/include/app_defs.h
+++ b/include/app_defs.h
@@ -2,6 +2,38 @@
 #ifndef APP_TYPES_H
 #define APP_TYPES_H
 
+/******************************************************************************
+ 
+ Copyright (c) 2015, Focusrite Audio Engineering Ltd.
+ All rights reserved.
+ 
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are met:
+ 
+ * Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+ 
+ * Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+ 
+ * Neither the name of Focusrite Audio Engineering Ltd., nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+ 
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ 
+ *****************************************************************************/
+
 // ____________________________________________________________________________
 //
 // Types