Wiki

Below is the source of this page. To edit this source as well as other pages on the wiki, you must login.
===== Power System Management on Linux Tutorial =====

==== Introduction ====
The goal of this tutorial is to equip the reader with a collection of hardware and software tools for working with Power System Management devices, and more generally, devices that fall under the Linux hardware monitoring kernel API (HWMON) framework.
\\
The tutorial will focus on using standard tools and simple examples that can be used for debug and development.
\\
Also note that the tutorial is geared toward Linux-based systems, in contrast to bare-metal, no-OS applications. A great resource for learning about this use case is the [[ad>https://www.analog.com/dc2294a|Linduino to PSM adapter shield]]. The instructions for this board go over how to run several examples on the Linduino (A clone of the Arduino UNO).

==== Videos ====
<WRAP todo>
This video includes installation and configuration of Kuiper Linux, as well as building and installing the development branch of the libiio with HWMON support. The video will be re-done (and re-hosted on the CftL YouTube channel) once these features are merged to master and included in a Kuiper release.\\
{{youtube>mR9V8uN390M?large}}
</WRAP>
\\
==== Materials ====
  * Raspberry Pi 4; 2G, 4G, or 8G version. (3B, 3B Plus will work, but you will want the 4 :-) )
  * 5V USB-C wall adapter for Raspberry Pi (micro USB for model 3)
  * [[adi>https://www.analog.com/dc1962c|DC1962C "PowerStick" PSM Demo Board]]
  * Electrical connection hardware (choose one):
    * 12x 15cm socket-to-socket jumpers such as [[https://schmartboard.com/wire-jumpers/female-jumpers/5-inch/|these from Schmartboard]]
    * <<Future RPi to Pmod, QuikEval, PSM adapter>>
  * 16GB (or larger) Class 10 (or faster) micro-SD card
  * User interface setup (choose one):
    * HDMI monitor, keyboard, mouse plugged directly into Raspberry Pi
    * Host Windows/Linux/Mac computer on same network as Raspberry Pi
  * Multimeters [[https://www.harborfreight.com/7-function-digital-multimeter-63759.html|7-Function Cen Tech]] or equivalent
\\

==== Hardware Setup: Linux / Raspberry Pi ====
Follow the directions for downloading and burning the ADI Kuiper Linux image to the SD card:\\
[[:resources:tools-software:linux-software:kuiper-linux|Kuiper Linux]]\\

<WRAP todo>
Remove this when overlay is merged to RPi branch and shows up in Kuiper. For the time being you will need to copy this file:\\
[[https://github.com/mthoren-adi/devicetree_overlays/raw/main/rpi-dc1962c.dtbo| Compiled DC1962C Device Tree Overlay]]
to the boot/overlays directory on the SD card. This can be done from Windows, Linux, Mac.\\
For reference, here is the source:\\
[[https://github.com/mthoren-adi/devicetree_overlays/raw/main/rpi-dc1962c.dts| DC1962C Device Tree Overlay Source]]
</WRAP>

Add the following line to config.txt:

<code>
dtoverlay=rpi-dc1962c
</code>
\\
Make the fllowing connections between the DC1962C and the Raspberry Pi, following the pin mapping in Figure 1 and corresponding photo in Figure 2.
\\
<WRAP todo>
Pin mapping diagram
</WRAP>
<WRAP centeralign> Figure 1. Pin Mapping Diagram </WRAP>
\\
{{ :university:labs:software:psm_hwmon_linux_tutorial:rpi_power_stick_jumpers.jpg?600 |}}
<WRAP centeralign> Figure 2. Connections with Discrete Wires </WRAP>
\\
<WRAP todo>
Update photo when production boards arrive
\\
{{ :university:labs:software:psm_hwmon_linux_tutorial:rpi_adapter_power_stick.jpg?600 |}}
<WRAP centeralign> Figure 3. Connections with DesignSpark adapter </WRAP>
\\
</WRAP>



==== Toolbox Item: i2cdetect ====
When bringing up I2C devices on the Raspberry Pi (or any other processor / operating system, for that matter), it's helpful to know if devices are connected properly. The i2c-detect utility will scan all addresses on a partc
I2c-detect is part of the I2C-tools package, which is pre-installed in Kuiper Linux. (It can be installed with apt-get install i2c-tools on Debian systems). The [[https://manpages.debian.org/unstable/i2c-tools/i2cdetect.8.en.html|i2c-detect man page]] describes all options. Run:
<code>
i2cdetect -y 1
</code>
And observe the output as shown in Figure X.
<WRAP todo>
Re-take screenshot with other EEPROMs on experimenter setup disabled (0x50-0x53)
{{ :university:labs:software:psm_hwmon_linux_tutorial:i2c-detect_drivers_enabled.png?400 |}}
<WRAP centeralign> Figure 4. Scanning I2C Bus 1 with i2c-detect </WRAP>
</WRAP>
The LTC2974, LTC2977, and LTC3880 are at I2C addresses 0x32, 0x33, and 0x30, respectively. i2c-detect reports "UU" for these addresses because these devices are controlled from kernelspace, and users cannot access them directly. The onboard 24AA02 EEPROM is not associated with a driver. The upper nibble of the i2c address is 0x5, and the lower 3 bits select banks within the device. Externally, addresses 0x50 to 0x57 are acknowledged.\\
Note that no data transfer actually occurs, the i2c-detect command is simply testing which devices acknowledge, then a stop condition is issued.
\\
==== Toolbox Item: LM Sensors utilities ====
<WRAP todo>
ToDo: add issue to Kuiper repo - add lm-sensors
<code>
sudo apt-get install lm-sensors
</code>
</WRAP>

<code>
sensors
</code>


==== Toolbox Item: HWMON Python library ====
<code>
sudo pip3 install hwmon
</code>
(run through some of the examples)
<code>
from hwmon import Hwmon
sensors = Hwmon.HW()
sensors.print_data()
</code>


==== Toolbox Item: IIO Utilities ====
Yup, this really works!

<WRAP todo>
ToDo: Remove when merged to master and included in Kuiper release
The libiio master branch now includes HWMON support, but is not included in the latest Kuiper release. It needs to be installed manually - but fear not, It's easy:
<code>
git clone https://github.com/analogdevicesinc/libiio.git
cd libiio
git checkout master
mkdir build && cd build && cmake -DWITH_SYSTEMD=ON -DWITH_HWMON=ON -DWITH_EXAMPLES=ON ../ && make && sudo make install
sudo reboot
</code>
</WRAP>
\\
iio_info
\\
IIO Oscilloscope
\\
Hopefully PyADI-IIO in the not too distant future
\\


==== Toolbox Item: pmbus_dpsm utilities ====

When you need to dig in deeper, use cases, noting that you have to remove the device tree overlay in order to use userspace functions.

==== Putting it all together: A Run-time Logging Application ====

Put together a simple python script to periodically log data from the power stick over time, and save to a local file. Show how this can be used to detect anomalies, trends toward higher operating temperatures, and other diagnostic stuff.

Show both a python HWMON example running locally, and a libiio based example that can run either locally or remotely.


==== Conclusion ====
\\
Existing PSM tools are the workhorse of system design and bringup. The Linux HWMON drivers and utilities are additional tools available for run-time debug and monitoring. (obviously this conclusion needs work...)
\\
Analog Devices Wiki

Page Tools
