STM32: Ensure proper distribution of analogRead values (now 0<=analogRead()<1 as on other boards) and add docs (fix #2612)

Author: gfwilliams

ChangeLog

@@ -16,6 +16,7 @@
             STM32: Revert hasSystemSlept=true before _WFI that caused jsTimer to get corrupted
             Pipboy: allow audio files to be played at the same time as (silent) video. add audioStopped/videoStopped events and audioStop method
             Pipboy: Pip.audioStartVar(wav,{overlap:true}) can now play sounds over the top of other sounds. audioRead now doesn't stop audio playback
+            STM32: Ensure proper distribution of analogRead values (now `0<=analogRead()<1` as on other boards) and add docs (fix #2612)
 
      2v25 : ESP32C3: Get analogRead working correctly
             Graphics: Adjust image alignment when rotating images to avoid cropping (fix #2535)

src/jswrap_io.c

@@ -172,10 +172,14 @@ void jswrap_io_poke(JsVarInt addr, JsVar *data, int wordSize) {
   "params" : [
     ["pin","pin",["The pin to use","You can find out which pins to use by looking at [your board's reference page](#boards) and searching for pins with the `ADC` markers."]]
   ],
-  "return" : ["float","The Analog Value of the Pin between 0(GND) and 1(VCC). See below."]
+  "return" : ["float","The analog value of the `Pin` between 0(GND) and 1(VCC). See below."]
 }
 Get the analogue value of the given pin.
 
+* The value is normally greater than or equal to 0, however in some cases nRF52-based boards can produce values
+less than 0 when the ADC voltage is slightly less than the chip's internal GND.
+* The value returned will always be *less* than 1, even when the ADC reads full range. For example a 12 bit ADC may return 4095 as a full-range value, but this is divided by 4096 to produce `analogRead`'s output value.
+
 This is different to Arduino which only returns an integer between 0 and 1023
 
 However only pins connected to an ADC will work (see the datasheet)

src/jswrap_pin.c

@@ -233,7 +233,7 @@ void jswrap_pin_pulse(JsVar *parent, bool value, JsVar *times) {
   "class"    : "Pin",
   "name" : "analog",
   "generate" : "jswrap_pin_analog",
-  "return" : ["float","The analog Value of the Pin between 0 and 1"]
+  "return" : ["float","The analog value of the `Pin` between 0(GND) and 1(VCC)"]
 }
 (Added in 2v20) Get the analogue value of the given pin. See `analogRead` for more information.
  */

targets/stm32/jshardware.c

@@ -1900,7 +1900,7 @@ JsVarFloat jshPinAnalog(Pin pin) {
   if (!jshGetPinStateIsManual(pin))
     jshPinSetState(pin, JSHPINSTATE_ADC_IN);
 
-  return jshAnalogRead(pinInfo[pin].analog, false) / (JsVarFloat)65535;
+  return jshAnalogRead(pinInfo[pin].analog, false) / (JsVarFloat)65536;
 }
 
 /// Returns a quickly-read analog value in the range 0-65535