Merge branch 'raw-adc' (bringing in ADC and flash access)

6 files changed, 179 insertions, 76 deletions

diff --git a/README.md b/README.md
index cb9d039..b1c6b60 100644
--- a/README.md
+++ b/README.md
@@ -9,8 +9,6 @@ Open source firmware for the Novation Launchpad Pro grid controller!  By customi
 
 You'll definitely 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 Pro, which comprises a build environment, application entry points / API, and a library of low level source code.  Our reasoning is as follows:
 
@@ -71,9 +69,9 @@ Once your new "box" is up and running, you can build the app in one of two ways.
 
 Either of the above methods will generate the firmware image, `launchpad_pro.syx`, in the project `build` directory.  You can then upload this to your Launchpad Pro from the host!
 
-## Using OS X
+## Using macOS
 
-On OS X you can easily install the GCC ARM toolchain using the [homebrew package manager](http://brew.sh). The EABI tools are maintained in an external repository which you need to put on tap first. You can then run ```make``` to directly compile the code:
+On macOS you can easily install the GCC ARM toolchain using the [homebrew package manager](http://brew.sh). The EABI tools are maintained in an external repository which you need to put on tap first. You can then run ```make``` to directly compile the code:
 
 ```
 brew tap PX4/homebrew-px4
@@ -82,7 +80,7 @@ make
 ```
 
 # Uploading to a Launchpad Pro
-Now you've got some nice new code to run! To upload it to your Launchpad Pro, you'll need a sysex tool for your host platform (I'd love to get it working from the virtual machine, but that's for later).  I recommend [Sysex Librarian](http://www.snoize.com/SysExLibrarian/) on OS X, and [MIDI OX](http://www.midiox.com/) on Windows.  On Linux, I'll bet you already have a tool in mind.
+Now you've got some nice new code to run! To upload it to your Launchpad Pro, you'll need a sysex tool for your host platform (I'd love to get it working from the virtual machine, but that's for later).  I recommend [Sysex Librarian](http://www.snoize.com/SysExLibrarian/) on macOS, and [MIDI OX](http://www.midiox.com/) on Windows.  On Linux, I'll bet you already have a tool in mind.
 
 I won't describe how to use these tools, I'm sure you already know - and if you don't, their documentation is superior to mine!  Here's what you need to do:
 
@@ -109,17 +107,16 @@ By calling into the HAL, your app can:
 
 - Write colours to the LEDs
 - Send messages to the MIDI/USB ports
+- Store and recall a little bit of data on the Launchpad Pro's flash memory
 
 The best way to learn about these is to read the documentation in `app.h`, and to study the (very basic) example code!
 
-Currently the HAL/app interface does not support reading or writing the flash memory.
-
 # Debugging
 We decided not to support or encourage using a hardware debugger, as opening a Launchpad Pro to fit a debugging header can easily damage the FSR (force sensitive resistor) sheet.
 
 Instead, you're going to have to do things the old fashioned way - by blinking LEDs or sending MIDI messages (though hopefully no need for a 'scope!).  For what it's worth, that's the way I've developed this version of the firmware - dogfooding all the way ;)
 
-If do you want to debug interactively (and of course you do), you can use the interactive desktop simulator on OS X.  
+If do you want to debug interactively (and of course you do), you can use the interactive desktop simulator on macOS:
 
 1. Build the Xcode project located in `/tools/osx`
 2. Connect your Launchpad Pro
@@ -127,7 +124,7 @@ If do you want to debug interactively (and of course you do), you can use the in
 4. Put the Launchpad Pro into "Programmer" mode using the Setup button (you'll get odd behaviour otherwise)
 5. Start debugging in Xcode!
 
-Currently it only supports button presses and LED messages - there's no virtual MIDI IO, setup button or aftertouch (yet).  It has a really awful busywaiting timer for the 1kHz tick.  However, it does allow you to debug your application logic using Xcode!
+Currently it only supports button presses and LED messages - there's no setup button, flash storage or aftertouch (yet).  It has a really awful busywaiting timer for the 1kHz tick.  However, it does allow you to debug your application logic using Xcode!
 
 You can also use the simple command-line simulator located in the `/tools` directory.  It is compiled and ran as part of the build process, so it serves as a very basic test of your app before it is baked into a sysex dump - more of a test harness.
 
@@ -142,7 +139,7 @@ To debug the simulator interactively in Eclipse:
 # The Hardware
 The Launchpad Pro is based around an ARM Cortex M3 from STMicroelectronics.  Specifically, an [STM32F103RBT6](http://www.st.com/web/catalog/mmc/FM141/SC1169/SS1031/LN1565/PF164487).  It's clocked at 72MHz, and has 20k RAM (I'm not sure how much of this we're using in the open build yet - should be a fair amount left but I haven't measured it).  The low level LED multiplexing and pad/switch scanning consume a fair bit of CPU time in interrupt mode, but have changed a little in the open firmware library (so again, I don't have measurements for how many cycles they're using).
 
-It has 128k of flash memory, but I'm pretty sure we won't be exposing all of it as part of this API (dangerously easy to corrupt things!).  Current thinking is to expose a few pages for use by apps, though this would still introduce risks (accidentally wearing out sectors, for example).  To be continued...
+It has 128k of flash memory, but we won't be exposing all of it as part of this API (dangerously easy to corrupt things!).
 
 # Vagrant tips
 When you're done developing, simply type `vagrant suspend` to halt your VM without destroying it - this will make `vagrant up` a lot quicker next time.  If you're really finished, `vagrant destroy` will completely remove the VM from your system (but not any of your code).
diff --git a/include/app.h b/include/app.h
index ed946d5..96801eb 100644
--- a/include/app.h
+++ b/include/app.h
@@ -43,7 +43,7 @@
 
 /******************************************************************************
  Button indexing is as follows - numbers in brackets do not correspond to real
-buttons, but can be harmessly sent in hal_set_led.
+ buttons, but can be harmessly sent in hal_set_led.
  
  (90)91 92 93 94 95 96 97 98 (99)
  .......
@@ -92,6 +92,40 @@ void hal_send_midi(u8 port, u8 status, u8 data1, u8 data2);
  */
 void hal_send_sysex(u8 port, const u8* data, u16 length);
 
+/**
+ * Read some data from flash.
+ *
+ * Flash storage is in a single block, currently corresponding to one page.
+ * The block is always USER_AREA_SIZE bytes long. You can read/write any bytes
+ * within it - you do not need to worry about paging, that's handled by the HAL.
+ *
+ * The block size may increase to span multiple pages in future :)
+ *
+ * @param offset - how far into the USER_AREA_SIZE byte block to start reading
+ * @param data - buffer to receive data (must be at least length bytes long)
+ * @param length - bytes to read
+ *
+ * Attempts to read beyond the end of the block will fail silently.
+ *
+ * Note that your first ever read from a new device will contain 0xFF's until
+ * you overwrite them.
+ */
+void hal_read_flash(u32 offset, u8 *data, u32 length);
+
+/**
+ * Write data to flash
+ *
+ * Do take care to avoid thrashing it, as you can wear it out with excessive
+ * writes. The HAL does not currently do anything clever to mitigate this.
+ *
+ * @param offset - how far into the USER_AREA_SIZE byte block to start writing
+ * @param data - buffer to write (must be at least length bytes long)
+ * @param length - bytes to write
+ *
+ * Attempts to write beyond the end of the block will fail silently
+ */
+void hal_write_flash(u32 offset,const u8 *data, u32 length);
+
 // ____________________________________________________________________________
 //
 // Callbacks from the hardware (implemented in your app.c)
@@ -99,8 +133,13 @@ void hal_send_sysex(u8 port, const u8* data, u16 length);
 
 /**
  * Called on startup, this is a good place to do any initialisation.
+ *
+ * @param adc_buffer -  this is a pointer to the raw ADC frame buffer. The
+ *                                              data is 12 bit unsigned. Note the indexing is strange - 
+ *                                              translate ADC indices to LED/button indices using the
+ *                                              ADC_MAP table declared in app_defs.h.
  */
-void app_init();
+void app_init(const u16 *adc_buffer);
 
 /**
  *  1kHz (1ms) timer.  You can set LEDs and send MIDI out from this function,
diff --git a/include/app_defs.h b/include/app_defs.h
index 829f8a6..d9b4311 100644
--- a/include/app_defs.h
+++ b/include/app_defs.h
@@ -100,5 +100,33 @@ typedef unsigned char  u8;
 #define MIDI_OUT_CABLE          1
 
 // ____________________________________________________________________________
+//
+// Flash storage
+// ____________________________________________________________________________
+
+#define USER_AREA_SIZE 1024
+
+// ____________________________________________________________________________
+//
+// Raw ADC reads. For technical reasons, the ADC layout is not the same as the
+// LED layout. Be sure to translate ADC values using the table below as you
+// need them!
+// ____________________________________________________________________________
+
+#define PAD_COUNT 64
+
+static const u8 ADC_MAP[PAD_COUNT] =
+{
+        11, 51, 12, 52, 13, 53, 14, 54,
+        15, 55, 16, 56, 17 ,57, 18, 58,
+        21, 61, 22, 62, 23, 63, 24, 64,
+        25, 65, 26, 66, 27, 67, 28, 68,
+        31, 71, 32, 72, 33, 73, 34, 74,
+        35, 75, 36, 76, 37, 77, 38, 78,
+        41, 81, 42, 82, 43, 83, 44, 84,
+        45, 85, 46, 86, 47, 87, 48, 88,
+};
+
+// ____________________________________________________________________________
 
 #endif
diff --git a/lib/launchpad_pro.a b/lib/launchpad_pro.a
index 712626d..c2c9af2 100644
--- a/lib/launchpad_pro.a
+++ b/lib/launchpad_pro.a
diff --git a/src/app.c b/src/app.c
index f0edec8..5b83182 100644
--- a/src/app.c
+++ b/src/app.c
@@ -41,51 +41,57 @@
 //
 // This is where the fun is!  Add your code to the callbacks below to define how
 // your app behaves.
+//
+// In this example, we render the raw ADC data as LED rainbows.
+//______________________________________________________________________________
+
+static const u16 *g_ADC = 0;
+
 //______________________________________________________________________________
 
 void app_surface_event(u8 type, u8 index, u8 value)
 {
-        switch (type)
-        {
-                case  TYPEPAD:
-                {
-                        // example - light / extinguish pad LEDs, send MIDI
-                        hal_plot_led(TYPEPAD, index, value, value, value);
-                        hal_send_midi(DINMIDI, NOTEON | 0, index, value);
-                }
-                break;
-
-                case TYPESETUP:
-                {
-                        // example - light the setup LED
-                        hal_plot_led(TYPESETUP, 0, value, value, value);
-                }
-                break;
-        }
+    switch (type)
+    {
+        case  TYPEPAD:
+        {
+            // example - light / extinguish pad LEDs, send MIDI
+            hal_plot_led(TYPEPAD, index, value, value, value);
+            hal_send_midi(DINMIDI, NOTEON | 0, index, value);
+        }
+            break;
+            
+        case TYPESETUP:
+        {
+            // example - light the setup LED
+            hal_plot_led(TYPESETUP, 0, value, value, value);
+        }
+            break;
+    }
 }
 
 //______________________________________________________________________________
 
 void app_midi_event(u8 port, u8 status, u8 d1, u8 d2)
 {
-        // example - MIDI interface functionality for USB "MIDI" port -> DIN port
-        if (port == USBMIDI)
-        {
-                hal_send_midi(DINMIDI, status, d1, d2);
-        }
-
-        // // example -MIDI interface functionality for DIN -> USB "MIDI" port port
-        if (port == DINMIDI)
-        {
-                hal_send_midi(USBMIDI, status, d1, d2);
-        }
+    // example - MIDI interface functionality for USB "MIDI" port -> DIN port
+    if (port == USBMIDI)
+    {
+        hal_send_midi(DINMIDI, status, d1, d2);
+    }
+    
+    // // example -MIDI interface functionality for DIN -> USB "MIDI" port port
+    if (port == DINMIDI)
+    {
+        hal_send_midi(USBMIDI, status, d1, d2);
+    }
 }
 
 //______________________________________________________________________________
 
 void app_sysex_event(u8 port, u8 * data, u16 count)
 {
-        // example - respond to UDI messages?
+    // example - respond to UDI messages?
 }
 
 //______________________________________________________________________________
@@ -93,60 +99,81 @@ void app_sysex_event(u8 port, u8 * data, u16 count)
 void app_aftertouch_event(u8 index, u8 value)
 {
     // example - send poly aftertouch to MIDI ports
-        hal_send_midi(USBMIDI, POLYAFTERTOUCH | 0, index, value);
-
+    hal_send_midi(USBMIDI, POLYAFTERTOUCH | 0, index, value);
+    
     // example - set LED to white, brightness in proportion to pressure
-        hal_plot_led(TYPEPAD, index, value/2, value/2, value/2);
+    hal_plot_led(TYPEPAD, index, value/2, value/2, value/2);
 }
-        
+
 //______________________________________________________________________________
 
 void app_cable_event(u8 type, u8 value)
 {
     // example - light the Setup LED to indicate cable connections
-        if (type == MIDI_IN_CABLE)
-        {
-                hal_plot_led(TYPESETUP, 0, 0, value, 0); // green
-        }
-        else if (type == MIDI_OUT_CABLE)
-        {
-                hal_plot_led(TYPESETUP, 0, value, 0, 0); // red
-        }
+    if (type == MIDI_IN_CABLE)
+    {
+        hal_plot_led(TYPESETUP, 0, 0, value, 0); // green
+    }
+    else if (type == MIDI_OUT_CABLE)
+    {
+        hal_plot_led(TYPESETUP, 0, value, 0, 0); // red
+    }
 }
 
 //______________________________________________________________________________
 
-
 void app_timer_event()
 {
-        // example - send MIDI clock at 125bpm
+    // example - send MIDI clock at 125bpm
 #define TICK_MS 20
-        
-        static u8 ms = TICK_MS;
-        
-        if (++ms >= TICK_MS)
+    
+    static u8 ms = TICK_MS;
+    
+    if (++ms >= TICK_MS)
+    {
+        ms = 0;
+        
+        // send a clock pulse up the USB
+        hal_send_midi(USBSTANDALONE, MIDITIMINGCLOCK, 0, 0);
+    }
+    
+/*
+        // alternative example - show raw ADC data as LEDs
+        for (int i=0; i < PAD_COUNT; ++i)
         {
-                ms = 0;
+                // raw adc values are 12 bit, but LEDs are 6 bit.
+                // Let's saturate into r;g;b for a rainbow effect to show pressure
+                u16 r = 0;
+                u16 g = 0;
+                u16 b = 0;
+                
+                u16 x = (3 * MAXLED * g_ADC[i]) >> 12;
+                
+                if (x < MAXLED)
+                {
+                        r = x;
+                }
+                else if (x >= MAXLED && x < (2*MAXLED))
+                {
+                        r = MAXLED - x;
+                        g = x - MAXLED;
+                }
+                else
+                {
+                        g = MAXLED - x;
+                        b = x - MAXLED;
+                }
                 
-                // send a clock pulse up the USB
-                hal_send_midi(USBSTANDALONE, MIDITIMINGCLOCK, 0, 0);
+                hal_plot_led(TYPEPAD, ADC_MAP[i], r, g, b);
         }
+ */
 }
 
 //______________________________________________________________________________
 
-void app_init()
+void app_init(const u16 *adc_raw)
 {
-    // example - light the LEDs to say hello!
-        for (int i=0; i < 10; ++i)
-        {
-                for (int j=0; j < 10; ++j)
-                {
-                        u8 r = i < 5 ? (MAXLED * (5-i))/5 : 0;
-                        u8 g = i < 5 ? (MAXLED * i)/5 : (MAXLED * (10-i))/5;
-                        u8 b = i < 5 ? 0 : (MAXLED * (i-5))/5;
-
-                        hal_plot_led(TYPEPAD, j*10 + i, r, b, g);
-                }
-        }
+        
+        // store off the raw ADC frame pointer for later use
+        g_ADC = adc_raw;
 }
diff --git a/tools/simulator.c b/tools/simulator.c
index 56298d7..138277e 100644
--- a/tools/simulator.c
+++ b/tools/simulator.c
@@ -57,16 +57,28 @@ void hal_send_sysex(u8 port, const u8* data, u16 length)
         printf("...hal_send_midi(%d, (data), %d);\n", port, length);
 }
 
+void hal_read_flash(u32 offset, u8 *data, u32 length)
+{
+        printf("...hal_read_flash(%d, (data), %d);\n", offset, length);
+}
+
+void hal_write_flash(u32 offset,const u8 *data, u32 length)
+{
+        printf("...hal_write_flash(%d, (data), %d);\n", offset, length);
+}
+
 // ____________________________________________________________________________
 //
 // App event wrappers - these just log to the console.  Would be nice to wire
 // these up to a MIDI input from the real Launchpad Pro!
 // ____________________________________________________________________________
 
+static u16 raw_ADC[64];
+
 static void sim_app_init()
 {
         printf("calling app_init()...\n");
-        app_init();
+        app_init(raw_ADC);
 }
 
 static void sim_app_surface_event(u8 type, u8 index, u8 value)