improved documentation (slightly!)

5 files changed, 152 insertions, 10 deletions

diff --git a/LICENSE b/LICENSE
index 8e2e528..03c2fcb 100644
--- a/LICENSE
+++ b/LICENSE
@@ -11,7 +11,7 @@ modification, are permitted provided that the following conditions are met:
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.
 
-* Neither the name of launchpad-pro nor the names of its
+* 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.
 
diff --git a/README.md b/README.md
index f5f0968..fec8668 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,8 @@ Open source firmware for the Novation Launchpad Pro grid controller!  By customi
 
 You'll definiteley need *some* C programming experience, but we've deliberately kept much of the firmwarey nastiness tucked away, to make the process a little friendlier.
 
+This project is still at an early stage, and no "interesting" example apps have yet been developed.  You might want to hang on until there's something more detailed before you get stuck in.  Or not!
+
 # Philosophy
 We could have released the full source for the factory shipping firmware, but we decided not to for a variety of reasons.  Instead, we created a simplified framework for developing "apps" on Launchpad, which comprises a build environment, application entry points / API, and a library of low level source code.  Our reasoning is as follows:
 
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
diff --git a/src/app.c b/src/app.c
index 662007e..a5fb790 100644
--- a/src/app.c
+++ b/src/app.c
@@ -1,3 +1,35 @@
+/******************************************************************************
+ 
+ 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.
+ 
+ *****************************************************************************/
+
 //______________________________________________________________________________
 //
 // Headers