NRF52LL ADC and documentation improvements

Author: gfwilliams

devices/NRF52LL.js

@@ -206,7 +206,9 @@ exports.lpcomp = function(opts) {
     eEnd     // event when ADC has filled DMA buffer
     setDMA : function({ptr,cnt}) // set new DMA buffer
                // double-buffered so can be set again right after tStart
+    start : function() // configure ADC (called automatically when 'saadc' created)
     sample : function(cnt) // Make `cnt*channels.length` readings and return the result. resets DMA
+    stop : function() // uninitialise so that normal analogRead works
   }
 */
 exports.saadc = function(opts) {
@@ -227,6 +229,7 @@ exports.saadc = function(opts) {
       poke32(addr+0x630, 0|o.cnt);
     },
     sample : function(cnt) {
+      poke32(o.enable, 1);
       cnt = cnt||1;
       if (cnt>1 && !opts.samplerate)
         throw "Can't do >1 sample with no samplerate specified";
@@ -241,7 +244,37 @@ exports.saadc = function(opts) {
       while (!peek32(o.eEnd));
       poke32(o.tStop,1);
       o.setDMA(); // don't try and write to this buffer now we're not using it any more
+      poke32(addr+0x104, 0); // clear end flag
+      poke32(o.enable, 0);
       return buf.slice(0,cnt*opts.channels.length);
+    },
+    start : function() {
+      this.stop();
+      // config channels
+      opts.channels.forEach(function(ch, idx) {
+        var a = addr+0x510 + idx*16;
+        var v = (pulls.indexOf(ch.pinpull)) |
+          (pulls.indexOf(ch.npinpull)<<4) |
+          (gains.indexOf(ch.gain)<<8) |
+          ((!!ch.refvdd)<<12) |
+          (tacqs.indexOf(ch.tacq)<<16) |
+          ((ch.npin!==undefined)<<20) | // differential if npin is supplied
+          ((!!opts.oversample)<<24);
+        poke32(a+8, v); // options
+        poke32(a, 0|(new Pin(ch.pin).getInfo().channel+1)); // pin pos -  undefined -> 0
+        poke32(a+4, 0|((ch.npin&&new Pin(ch.npin).getInfo().channel)+1)); // pin neg - undefined -> 0
+      });
+      poke32(addr+0x5F0, (opts.resolution-8)>>1);
+      poke32(addr+0x5F4, 0|opts.oversample);
+      poke32(addr+0x5F8, opts.samplerate | ((!!opts.samplerate)<<12));
+      o.setDMA(opts.dma);
+    },
+    stop : function() {
+      poke32(o.enable, 0);
+      poke32(addr+0x5F4, 0); // disable oversample
+      // disable all ADC channels
+      for (var i=0;i<8;i++)
+        poke32(addr+0x510 + i*16, 0);
     }
   };
   var pulls = [undefined, "down","up","vcc/2"];
@@ -251,38 +284,21 @@ exports.saadc = function(opts) {
   if (!opts.channels || opts.channels.length>8) throw "Invalid channels";
   if (opts.oversample && opts.channels.length>1)throw "Can't oversample with >1 channel";
   if (opts.samplerate && opts.channels.length>1)throw "Can't use samplerate with >1 channel";
-  poke32(o.enable, 0);
-  // disable all ADC channels
-  for (var i=0;i<8;i++)
-    poke32(addr+0x510 + i*16, 0);
-  // config those specified
+  // check channel info
   opts.channels.forEach(function(ch, idx) {
-    var a = addr+0x510 + idx*16;
     if (!ch.gain) ch.gain=1;
     if (!ch.tacq) ch.tacq=3;
     if (pulls.indexOf(ch.pinpull)<0) throw "Invalid pinpull";
     if (pulls.indexOf(ch.npinpull)<0) throw "Invalid npinpull";
     if (gains.indexOf(ch.gain)<0) throw "Invalid gain";
     if (tacqs.indexOf(ch.tacq)<0) throw "Invalid tacq";
-    var v = (pulls.indexOf(ch.pinpull)) |
-      (pulls.indexOf(ch.npinpull)<<4) |
-      (gains.indexOf(ch.gain)<<8) |
-      ((!!ch.refvdd)<<12) |
-      (tacqs.indexOf(ch.tacq)<<16) |
-      ((ch.npin!==undefined)<<20) | // differential if npin is supplied
-      ((!!opts.oversample)<<24);
-    poke32(a+8, v); // options
-    poke32(a, 0|(new Pin(ch.pin).getInfo().channel+1)); // pin pos -  undefined -> 0
-    poke32(a+4, 0|((ch.npin&&new Pin(ch.npin).getInfo().channel)+1)); // pin neg - undefined -> 0
   });
-  poke32(addr+0x5F0, (opts.resolution-8)>>1);
-  poke32(addr+0x5F4, 0|opts.oversample);
-  poke32(addr+0x5F8, opts.samplerate | ((!!opts.samplerate)<<12));
-  o.setDMA(opts.dma);
-  poke32(o.enable, 1);
+  // setup 
+  o.start();
   return o;
 };
 
+
 /** Real time counter
   You should only set on ch2 as 0 and 1 are used by Espruino/Bluetooth
   This function intentionally doesn't set state itself to allow you

devices/NRF52LL.md

@@ -4,8 +4,8 @@ nRF52 Low Level Interface Library
 
 <span style="color:red">:warning: **Please view the correctly rendered version of this page at https://www.espruino.com/NRF52LL. Links, lists, videos, search, and other features will not work correctly when viewed on GitHub** :warning:</span>
 
-* KEYWORDS: Module,nRF52,nRF5x,nRF52832,Puck.js
-* USES: Puck.js,Pixl.js,MDBT42Q,nRF52832,nRF52
+* KEYWORDS: Module,nRF52,nRF5x,nRF52832,Low Level,Hardware,Differential,SAADC,GPIOTE,LPCOMP,PPI,TIMER
+* USES: Puck.js,Pixl.js,Jolt.js,MDBT42Q,nRF52832,nRF52
 
 The nRF52 microcontroller used in [Puck.js](/Puck.js), [Pixl.js](/Pixl.js) and [MDBT42Q](/MDBT42Q) has a load of really interesting peripherals built-in, not all of which are exposed by Espruino. The microcontroller also contains something called PPI - the "Programmable Peripheral Interconnect". This allows you to 'wire' peripherals together internally.
 
@@ -140,7 +140,7 @@ setWatch(function() {
 
 ### Make one reading from the ADC:
 
-Uses ADC.
+Uses the ADC (much line `analogRead` but with more options)
 
 ```JS
 var ll = require("NRF52LL");
@@ -153,6 +153,27 @@ var saadc = ll.saadc({
   } ]
 });
 print(saadc.sample()[0]);
+saadc.stop(); // deconfigure so analogRead works again (use saadc.start() to redo)
+```
+
+### Make a differential from the ADC:
+
+Use the ADC to measure the voltage difference between D30 and D31,
+with the maximum gain and oversampling provided by the hardware.
+
+```JS
+var ll = require("NRF52LL");
+var saadc = ll.saadc({
+  channels : [ { // channel 0
+    pin:D30, npin:D31,
+    gain:4,
+    tacq:40,
+    refvdd:true,
+  } ],
+  oversample : 8
+});
+print(saadc.sample()[0]);
+saadc.stop(); // deconfigure so analogRead works again (use saadc.start() to redo)
 ```
 
 ### Read a buffer of data from the ADC
@@ -186,6 +207,7 @@ poke32(saadc.tSample,1); // start!
 while (!peek32(saadc.eEnd)); // wait until it ends
 poke32(saadc.tStop,1);
 print("Done!", buf);
+saadc.stop(); // deconfigure so analogRead works again (use saadc.start() to redo)
 ```
 
 ### Read a buffer of data from the ADC, alternating between 2 pins
@@ -203,7 +225,7 @@ var buf = new Int16Array(128);
 // ADC
 var saadc = ll.saadc({
   channels : [ {
-    pin:D31, // channel 0    
+    pin:D31, // channel 0
     gain:1/4,
     refvdd:true
   }, {
@@ -226,6 +248,7 @@ while (!peek32(saadc.eEnd)); // wait until sampling ends
 poke32(tmr.tStop,1);
 poke32(saadc.tStop,1);
 print("Done!", buf);
+saadc.stop(); // deconfigure so analogRead works again (use saadc.start() to redo)
 ```
 
 ### Use the RTC to toggle the state of a LED