Merge branch 'maint'

3 files changed, 107 insertions, 3 deletions

diff --git a/host/docs/res/e3xx_conn_photo.png b/host/docs/res/e3xx_conn_photo.png
new file mode 100644
index 000000000..dd12f5ac2
--- /dev/null
+++ b/host/docs/res/e3xx_conn_photo.png
diff --git a/host/docs/res/e3xx_conn_render.png b/host/docs/res/e3xx_conn_render.png
new file mode 100644
index 000000000..52e6ce5d9
--- /dev/null
+++ b/host/docs/res/e3xx_conn_render.png
diff --git a/host/docs/usrp_e3x0.dox b/host/docs/usrp_e3x0.dox
index ff03dedcd..70432d05f 100644
--- a/host/docs/usrp_e3x0.dox
+++ b/host/docs/usrp_e3x0.dox
@@ -264,7 +264,7 @@ You may need to change the USRP's IP address for several reasons:
 - **RF B Group**
   + **TX/RX LED**: Indicates that data is streaming on the TX/RX channel on frontend B
   + **RX2 LED**: Indicates that data is streaming on the RX2 channel on frontend B
-- **PWR**: Power switch
+- **PWR**: Power switch with integrated status LED, for status description see below.
 
 - **SYNC**: Input port for external PPS signal
 
@@ -272,6 +272,43 @@ You may need to change the USRP's IP address for several reasons:
 
 - **AUDIO**: Audio input / output
 
+The status LED in the power switch indicates the power and charge status.
+It's behavior is firmware version dependent.
+
+- **Version 1** (original E310)
+  + **Off**: Indicates device is off and not charging
+  + **Solid Red**: Indicates device is charging
+  + **Solid Green**: Indicates device is on
+  + **Fast Blinking Red**: Indicates an error code
+    + 1 - Low voltage error
+    + 2 - Regulator low voltage error
+    + 3 - FPGA power error
+    + 5 - 1.8V rail power error
+    + 6 - 3.3V rail power error
+    + 7 - Daughterboard / TX power error
+    + 9 - Temperature error
+
+- **Version 2** (E312 and upgraded E310)
+  + **Off**: Indicates device is off and not charging
+  + **Slow Blinking Green**: Indicates device is off and charging
+  + **Fast Blinking Green**: Indicates device is on and charging
+  + **Solid Green**: Indicates device is on (and not charging, if E312)
+  + **Solid Orange**: Indicates device is on and discharging
+  + **Fast Blinking Orange**: Indicates device is on, discharging, and charge is below 10% charge
+  + **Fast Blinking Red**: Indicates an error code
+    + 1 - Low voltage error
+    + 2 - Regulator low voltage error
+    + 3 - FPGA power error
+    + 4 - DRAM power error
+    + 5 - 1.8V rail power error
+    + 6 - 3.3V rail power error
+    + 7 - Daughterboard / TX power error
+    + 8 - Charger error
+    + 9 - Charger temperature error
+    + 10 - Battery low error
+    + 11 - Fuel Gauge temperature error
+    + 12 - Global (case) temperature error
+
 \subsection e3x0_hw_rear_panel Rear Panel
 
 \image html e3x0_rp_overlay.png "USRP E310 Rear Panel"
@@ -351,7 +388,7 @@ For more advanced IMU based applications please refer to the <a href="https://gi
 
 ### Connector
 
-\image html e3x0_gpio_conn.png "E3x0 GPIO Connector"
+\image html e3x0_gpio_conn.png "E3xx GPIO Connector"
 
 ### Pin Mapping
 
@@ -379,7 +416,7 @@ The Left/Right audio outputs are compatible with typical low-impedance headphone
 
 ### Connector
 
-\image html e3x0_jtag_conn.png "E3x0 JTAG Connector"
+\image html e3x0_jtag_conn.png "E3xx JTAG Connector"
 
 ### Pin Mapping
 
@@ -396,6 +433,73 @@ USRP-E series devices can be used with Xilinx chipscope using the internal JTAG
 
 Further information on how to use Chipscope can be found in the *Xilinx Chipscope Pro Software and Cores User Guide (UG029)*.
 
+\section e3xx_battery Battery notes
+
+The USRP E312 (and with upgraded firmware E310) supports LiIon Battery packs (e.g. AA Portable Power Corp, 749801-01).
+
+\subsection e3xx_battery_connector Connector
+
+The connector J1 on E312's motherboard is a Molex 53014-6310. The corresponding mating connector is a Molex 51004-0300.
+
+\image html e3xx_conn_photo.png "Battery pack connector"
+
+The pins are as follows:
+- Pin 1 (Red): VBat
+- Pin 2 (Black): GND
+- Pin 3 (White): Battery Thermistor
+
+\subsection e3xx_battery_information Driver
+
+The battery information is exposed on the device via the sysfs directory under:
+
+    /sys/class/power_supply/BAT/
+
+and for the charger:
+
+    /sys/class/power_supply/AC/
+
+The values can be accessed via libudev or manually e.g.:
+
+    root@ettus-e3xx: cat /sys/class/power_supply/BAT/status
+
+The driver emits uevents on changes, that can be used to write custom UDev rules.
+Using UDev rules one can configure the USRP E3xx to shut down on certain events,
+such as low battery charge, high temperatures or AC power plug in.
+
+The following example will cause the system to shut down at a reported temperature
+of 73C:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+SUBSYSTEM=="power_supply", ATTR{online}=="1", ATTR{temp}=="730", RUN+="/sbin/shutdown -h now"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Another example will cause a safe shutdown once the battery level reaches 5 percent
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+SUBSYSTEM=="power_supply", ATTR{online}=="1", ATTR{status}=="Discharging", ATTR{capacity}=="5", RUN+="/sbin/shutdown -h now"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For more information, please see the udev manual pages and <a href ="https://www.kernel.org/doc/Documentation/power/power_supply_class.txt"> Kernel Power Supply Docs </a>.
+
+\subsection e3xx_battery_calibration Calibration Procedure
+
+In order for the fuel gauge to give a usable indication of remaining charge it needs to be calibrated.
+The procedure for calibration is as follows:
+
+1. Completely discharge battery (e.g. by booting up without SD card, so OS doesn't autoshutdown)
+2. Unplug the battery pack and external power
+3. Reconnect the battery pack
+4. Reconnect AC power and charge until charge completed.
+
+A faster (less accurate) calibration procedure is as follows:
+
+1. Completly charge battery
+2. Type:
+
+    $ echo 3200000 > /sys/class/power_supply/BAT/charge_now
+
+3. Unplug AC power
+4. Replug AC power and wait until charge completes
+
 \section e3x0_dboards Daughterboard notes
 
 \subsection e3x0_dboard_e310 E310 MIMO XCVR board