Battery voltage monitors (#416)

* battery voltage monitor example on different shields

* different voltage dividers on different expansionboard versions

The newer exp3.1 expansionboards have a different voltage divider than what is depicted in the pinout image

* add battery voltage example in menu tree

* separated exp 2 & 3, added mV

* correction

correction

config.toml

@@ -482,11 +482,11 @@ theme = "doc-theme"
     parent = "tutorials@expansionboards"
     weight = 40
 [[menu.main]]
-    name = "Sleep"
-    url = "/tutorials/expansionboards/sleep/"
-    identifier = "tutorials@expansionboards@sleep"
+    name = "Battery Voltage"
+    url = "/tutorials/expansionboards/vbat/"
+    identifier = "tutorials@expansionboards@vbat"
     parent = "tutorials@expansionboards"
-    weight = 20
+    weight = 50
 [[menu.main]]
     name = "Advanced"
     url = "/tutorials/advanced/"

content/datasheets/expansionboards/expansion3.md

@@ -25,12 +25,14 @@ The pinout of the Expansion Board is available as a [PDF File](/gitbook/assets/e
 The expansion board contains 7 jumpers labeled:
 - TX: TX UART (GPIO1) communication of the development board to the Expansionboard
 - RTS: Can be used for UART flow control. Connected to GPIO7. 
-- RX: RX UART (GPIO2() communication of the development board to the Expansionboard
+- RX: RX UART (GPIO2) communication of the development board to the Expansionboard
 - CTS: Can be used for UART flow control. Connected to GPIO6.
 - BAT: Connect the resistor divider on the Expansionboard to the Voltage monitoring ADC Pin (GPIO3)
 - LED: Connect the LED on the Expansionboard to GPIO16
 - CHG: Removing the jumper will decrease battery charging current from 450mA to 100mA
 
+> Note: The internal voltage divider is 1M / 1M, instead of the mentioned values in the pinout. Take care of this when reading the battery voltage.
+
 ![](/gitbook/assets/expansion3-pinout-1.png)
 
 > Be gentle when plugging and unplugging from the USB connector. Whilst the USB connector is soldered and is relatively strong, if it breaks off it can be very difficult to fix.

content/tutorials/expansionboards/vbat.md

@@ -0,0 +1,60 @@
+---
+title: "Reading Battery Voltage"
+---
+
+Each shield allows you to read the battery voltage, though in a slightly different way. Below we explain how to measure the battery voltage for each shield.
+## Expansionboard 2
+```python
+from machine import ADC
+adc = ADC()
+bat_voltage = adc.channel(attn=ADC.ATTN_11DB, pin='P16')
+vbat = bat_voltage.voltage()
+# note that the expansionboard 2.0 has a voltage divider of 115K / 56K to account for
+
+# 115K / 56K, ratio =~ 1:3
+print('battery voltage:', vbat*3, 'mV')
+```
+
+## Expansionboard 3.0 / 3.1
+
+The Expansionboard has an on-board voltage monitor connected through a voltage divider to an ADC pin, allowing you to read the voltage. You can use the example below. Note that, depending on the revision of expansionboard you own, the dividing ratio of the voltag divider varies. Note that the battery voltage will be close to 5V when you ahve a USB cable connected.
+
+```python
+from machine import ADC
+adc = ADC()
+bat_voltage = adc.channel(attn=ADC.ATTN_11DB, pin='P16')
+vbat = bat_voltage.voltage()
+# note that the expansionboard 3 has a voltage divider of 1M / 1M to account for
+# 1M / 1M, ratio = 1:2
+print('battery voltage:', vbat*2, 'mV')
+```
+
+## Pysense / Pytrack / Pyscan
+
+The first and second generation of Pysense, Pytrack and Pyscan shields do not directly connect the battery voltage to the module. Instead, they use the ADC of the coprocessor to read the battery voltage, saving an additional IO pin. You can use the following example. Note that the battery voltage will be close to 5V when you have a USB cable connected.
+```python
+
+# first generation
+# from pycoproc_1 import Pycoproc
+# py = Pycoproc(Pycoproc.PYSENSE)
+
+# second generation
+from pycoproc_2 import Pycoproc
+py = Pycoproc()
+
+print(py.read_battery_voltage())
+```
+
+## Pygate
+
+The Pygate has a voltage divider of 100K / 100K on board, with the battery connected to P13. Note that the battery voltage will be close to 5V when you have a USB cable connected.
+
+```python
+from machine import ADC
+adc = ADC()
+bat_voltage = adc.channel(attn=ADC.ATTN_11DB, pin='P13')
+vbat = bat_voltage.voltage()
+# note that the Pygate has a voltage divider of 100K / 100K to account for
+# 100K / 100K ratio = 1:2
+print('battery voltage:', vbat*2, 'mV')
+```