Touchups for documentation & comments for adc* scripts from romfs.

doc/luadoc/refman_gen_adc.lua

@@ -7,7 +7,7 @@ data_en =
   title = "eLua reference manual - ADC",
 
   -- Menu name
-  menu_name = "ADC",
+  menu_name = "adc",
 
   -- Overview
   overview = [[This module contains functions that access analog to digital converter (ADC) peripherals. ]],
@@ -38,7 +38,7 @@ data_en =
         "$id$ - ADC channel ID.",
         "$count$ - optional parameter to indicate number of samples to return. If not included, all available samples are returned."
       },
-      ret = "$samples$ - table containing integer conversion values"
+      ret = "$samples$ - table containing integer conversion values. If not enough samples are available, remaining indices will be nil."
     },
     { sig = "#adc.insertsamples#( id, table, idx, count )",
       desc = "Write multiple samples to a table.",
@@ -47,7 +47,7 @@ data_en =
         "$id$ - ADC channel ID.",
         "$table$ - table to write samples to. Values at $table$[$idx$] to $table$[$idx$ + $count$ -1] will be overwritten with samples.",
         "$idx$ - first index to use for writing samples",
-        "$count$ - number of samples to return. If not enough samples are available (after blocking, if enabled) nil is written to indexes that would have received samples."
+        "$count$ - number of samples to return. If not enough samples are available (after blocking, if enabled) remaining values will be nil."
       }
     },
     { sig = "maxval = #adc.maxval#( id )",

romfs/adcpoll.lua

@@ -1,3 +1,4 @@
+-- Acquire ADC samples using a timer with polling for available samples
 
 if pd.board() == "ET-STM32" then
   timer = 2
@@ -9,16 +10,17 @@ else
   adcsmoothing = {4, 64, 32, 16}
 end
 
+-- Setup ADC and start sampling
 for i, v in ipairs(adcchannels) do
-  adc.setblocking(v,0)
-  adc.setsmoothing(v,adcsmoothing[i])
-  adc.setclock(v, 4 ,timer)
+  adc.setblocking(v,0) -- no blocking on any channels
+  adc.setsmoothing(v,adcsmoothing[i]) -- set smoothing from adcsmoothing table
+  adc.setclock(v, 4 ,timer) -- get 4 samples per second, per channel
 end
 
-adc.sample(adcchannels,128)
+adc.sample(adcchannels,128) -- start sampling on all channels
 
+-- Draw static text on terminal
 term.clrscr()
-
 term.gotoxy(1,1)
 term.putstr("ADC Status:")
 term.gotoxy(1,3)
@@ -26,23 +28,23 @@ term.putstr(" CH   SLEN   RES")
 term.gotoxy(1,#adcchannels+5)
 term.putstr("Press ESC to exit.")
 
+-- use some locals for speed
 local sample = adc.sample
 local getsample = adc.getsample
 local samplesready = adc.samplesready
-local i, v
-local tsample
+local i, v, tsample
 
 while true do
   for i, v in ipairs(adcchannels) do
-    tsample = getsample(v)
-    if not (tsample == nil) then
+    tsample = getsample(v) -- try to get a sample
+    if not (tsample == nil) then -- if we have a new sample, then update display
     	term.gotoxy(1,i+3)
     	term.putstr(string.format("ADC%02d (%03d): %04d\n", v, adcsmoothing[i], tsample))
     end
-    if adc.isdone(v) == 1 then adc.sample(v,128) end
+    if adc.isdone(v) == 1 then adc.sample(v,128) end -- if samples have run out, start collection again
   end
   key = term.getch( term.NOWAIT )
-  if key == term.KC_ESC then break end
+  if key == term.KC_ESC then break end -- exit if user hits Escape
 end
 
 term.clrscr()

romfs/adcscope.lua

@@ -1,3 +1,6 @@
+-- Acquire ADC samples as quickly as possible, without the use of a timer
+--  provides statistics on time and memory usage while running
+
 if pd.board() == "ET-STM32" then
   adcchannels = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}
   adcsmoothing = {4, 4, 4, 4, 16, 16, 16, 16, 32, 32, 32, 32, 64, 128, 64, 128}
@@ -8,14 +11,15 @@ else
   numiter = 200
 end
 
+-- Setup ADC
 for i, v in ipairs(adcchannels) do
-  adc.setblocking(v,1)
-  adc.setclock(v,0)
-  adc.setsmoothing(v,adcsmoothing[i])
+  adc.setblocking(v,1) -- block, waiting for samples when an adc.get* function is used
+  adc.setclock(v,0) -- set clock to zero: no timer, acquire samples as fast as possible
+  adc.setsmoothing(v,adcsmoothing[i]) -- apply moving average filter using lengths from adcsmoothing
 end
 
+-- Draw static text on terminal
 term.clrscr()
-
 term.gotoxy(1,1)
 term.putstr("ADC Status:")
 term.gotoxy(1,3)
@@ -23,36 +27,39 @@ term.putstr(" CH   SLEN   RES")
 term.gotoxy(1,#adcchannels+7)
 term.putstr("Press ESC to exit.")
 
+-- use some locals for speed
 local adcvals = {}
-local key, stime, etime, dtime
+local key, stime, etime, dtime, i, v
 local sample = adc.sample
 local insertsamples = adc.insertsamples
 local tread = tmr.read
 local tstart = tmr.start
-local i, v
 
 while true do
-  stime = tstart(0)
-  for j=1,numiter do 
+  stime = tstart(0) -- start timer
+  for j=1,numiter do -- acuire numiter samples
     sample(adcchannels, 1)
     for i, v in ipairs(adcchannels) do
-      insertsamples(v,adcvals,i,1)
+      insertsamples(v,adcvals,i,1) -- for each iteration j, get samples and put them in adcvals
     end
   end
-  etime = tread(0)
-  dtime = tmr.diff(0,etime,stime)/numiter
+  etime = tread(0) -- get cycle end time
+  dtime = tmr.diff(0,etime,stime)/numiter -- compute average acquisition time per cycle
   
+  -- draw last acquired samples on the console
   term.gotoxy(1,4)
   for i, v in ipairs(adcchannels) do
     term.putstr(string.format("ADC%02d (%03d): %04d\n", v, adcsmoothing[i],adcvals[i]))
     term.gotoxy(1,i+4)
   end
+  
+  -- draw acquisition statistics
   term.putstr(string.format("Tcyc: %06d (us)\n",dtime))
 	term.gotoxy(1,#adcchannels+5)
 	term.putstr(string.format("Mem:  %03.2f (kB)\n",collectgarbage("count")))
 
   key = term.getch( term.NOWAIT )
-  if key == term.KC_ESC then break end
+  if key == term.KC_ESC then break end -- exit if user hits Escape
 end
 
 term.clrscr()