mhia pi
Overview
mhia pi is a 8-channel analog-digital-converter designed for use with Raspberry Pi computers or compatible. Raspberry Pi is a trademark of Raspberry Pi Ltd. The developers of mhia pi hardware and software are not associated with Raspberry Pi Ltd.
mhia pi is designed as a HAT (Hardware attached on top). Alternatively, you can use jumper cables to connect mhia with your single board computer, especially if you need to use alternative assignments of the GPIO pins. It is also possible to connect mhia pi to microcontrollers with SPI (for the display) and I²C (for the AD-Chips), but beware that the AD-Chips are driven with 5 V and the display is driven with 3.3 V. This wiki describes only the use case of attaching mhia pi as a HAT on a Raspberry Pi. mhia pi is already tested for use with Raspberry Pi 3, 4, Zero W and Zero 2W.
The mhia pi PCB consist of 4 copper layers, resulting in better signal integrity than similar products and enabling SPI, I2C and analog signals to traverse on the small PCB without significantly affecting each other.
Specifications
- 4 layer PCB design
- 2x MCP3424 AD-Converters from Microchip Technology Inc.:
- Interface: I²C (channels 0x68 and 0x6d on the mhia pi v1.0)
- each ADC-chip has 4 analog input channels, on this PCB analog input signals can range between 0V and +5V max, and are single ended!
- Resolution: 12, 14, 16 or 18 bit. On this PCB reduced by one bit (no negative values)
- Sample rates: approx 240, 60, 15, 3.75 samples per second
- PGA: 1x, 2x, 4x, 8x
- datasheet
- IPS display:
- Interface: SPI
- ST7789V3 controller
- 172x320 px
- 262K RGB
- size: 17 x 32 mm
- rounded corners (few corner pixels are not visible)
- datasheet
- five-way tactile navigation button using GPIOs 12, 16, 20, 21 and 26
- single extra button using GPIO 4
- if your SBC has tall GPIO header pins, you can accessed free GPIOs on top
- 16 pin 2.54mm (0,1") pitch screw terminal (CH1, GND, CH2, GND, ..., CH8, GND)
- 5 V sensor supply voltage (+5 V, GND) screw terminal
HW Installation (as HAT of a Raspberry Pi)
mhia pi can be attached as a HAT to these models:
- Raspberry Pi 2
- Raspberry Pi 3 (Model A and B)
- Raspberry Pi 4
- Raspberry Pi Zero W
- Raspberry Pi Zero 2 W
On the Raspberry Pi 4, you might need to trim the J14 pins (PoE). If your Raspberry Pi has a heat sink on its SoC please check that there is no contact between the mhia pi and the heat sink. Alternatively you can also use a socket riser.
SW Installation (on a Raspberry Pi)
There are various sources online explaining installation of an operating system on a Raspberry Pi, setting it up and running python scripts on it. We assume you already know how to, or know how to find out yourself. The next subsection describes briefly a practical way to install the Raspberry Pi OS.
Install the Operating System
We suggest to install the Raspberry Pi OS Lite (32bit or 64bit, appropriate to your model) using the Raspberry Pi Imager. This free tool can be downloaded from the official website of Raspberry Pi. Raspberry Pi is a trademark of Raspberry Pi Ltd.
We also strongly recommend to set and configure these options in the advanced options menu (cogwheel button) of the the Raspberry Pi Imager:
- hostname
- SSH
- username and password
- wireless LAN
- wireless LAN country
Please choose the hostname wisely. Especially when you intend to connect more than one Raspberry Pi in the network. Also consider that with these options set, the Raspberry Pi will attempt to connect over WiFi to your network and obtain an IP address from the DHCP server. In any case, you should follow the policies set by the administrator of the network you want to connect to.
After the Image and the configuration are written, slide the card into the Raspberry Pi and power it up. The first boot will take a few minutes. If the options were set correctly using the Imager, your Raspberry Pi should be connected to the LAN. Try to ping it by its hostname from within the same network. You might need to check the DHCP client list to find the ipv4 address. You should be able to start a shell session over SSH now. Consider to set up key authentication instead of username/password authentication.
At this point you are encouraged to start an SSH-session and do:
sudo apt update
sudo apt upgradeActivate SPI and I²C
After you SSH to the Raspberry Pi you can run the interactive raspi-config tool to activate SPI and I²C. Alternatively you can also activate both non-interactively by executing these two command lines:
sudo raspi-config nonint do_i2c 0
sudo raspi-config nonint do_spi 0Indeed do_i2c 0 means here turn on I²C and do_i2c 1 means turn it off!
(If you want to know more about raspi-config visit this website)
You can check whether I²C and SPI are activated by verifying that the /dev folder contains the device files i2c-1, spidev0.0 and spidev0.1.
Install pip
The Raspberry Pi OS Lite comes already with python3 included (version 3.9.2 as this wiki was written), but apparently without the Python Package Manager ''pip''. Ensure that you get pip on your device by using this command:
sudo apt install python3-pipInstall the suggested application
We suggest that you use the open source mhia pi software available at https://github.com/Talwiese/mhiapi
Feel free to clone the repository, if you want to use git on the Raspberry Pi.
If you don't know how to or don't want to use git, you can also download the source code as a ZIP-archive. On the main page of the repository hit the green Code button and then click on Download ZIP as seen in the screenshot here to the right.
You then have to unzip the zip and transfer the files from your PC on which you downloaded the repository to your Raspberry Pi. On a Microsoft Windows system with PowerShell the command looks like this:
scp -r .\mhiapi userx@hosty:~/mhiapiAssuming you are running the command in the path you just unzipped the repo in, and want to have the main application folder in the userx's home directory on the Raspberry Pi with hostname hosty.
If you unzipped the downloaded zip on a Microsoft Windows system you might need to reset some file attributes after copying the files. The scripts should be executable since mhia.py triggers execution of the other scripts:
chmod +x mhia.py sampler.py displayer.py publisher.pyYou also need to install the requirements by running:
pip install -r requirements.txt
After this step you can start the mhia application with default settings with:
python mhia.pyor just:
./mhia.py
Description of suggested software
We suggest that you use the open source mhia software available at https://github.com/Talwiese/mhiapi
mhia software is a set of python3 scripts and modules initially developed by Talwiese IoT Solutions e.U. using some third party modules including the ADCPi module from ABelectronics and the lcdconfig module from Waveshare Electronics.
The mhia software has a GNU GPLv3 license! Please copy, modify and distribute this software commercially as much as you want to, but only in compliance with GPLv3. Just a reminder: there is no warranty that the software works at all, and the developers cannot be held liable.
The mhia application consists of these main python scripts, (.py at end of script name is omitted here):
- mhia
- sampler
- displayer
- publisher
All these scripts access the single configuration file config.yaml or config_default.yaml if config.yaml doesn't exist in the main folder. The scripts mhia, sampler and displayer should work with the the default configuration file config_default.yaml that is part of the repository. Please have a look this file, it is commented thoroughly.
mhia
When mhia is started it starts the sampler in any case and then the displayer and/or publisher if they were enabled in the configuration file. After displayer and/or publisher are started each is connected to the sampler over a Unix Domain Socket (UDS) that was initially opened by the sampler. After the needed sub-processes started successfully, each of them (and mhia itself) run their main loops, until an interrupt is detected (TERM or KILL signal, or the reset button on mhia pi pushed).
Sampler
In its main loop the sampler uses the ADCPi module to capture samples continuously according to the configuration and sends each sample to displayer and/or publisher. The sampler will try to sample at almost constant intervals ("time-equidistant"). For each possible adc_resolutionthe interval is set in the requested_sampling_interval object in the configuration file. As you can see in the default configuration the intervals should be larger at higher resolution. They depend mainly on the time the MCP3424 chips take for the AD-conversion. The following table shows the samples per second values (SPS) and corresponding intervals in milliseconds, next to the default values set in the configuration file. If you want to change these values, make sure your values are higher than the maximum milliseconds according to the chip's datasheet. The faster (lower milliseconds) you set the sampler, the more processing time will also the other scripts (displayer or publisher) need. For example on a Raspberry Pi Zero W, 20 milliseconds is too small for 12 bit resolution if the displayer script is also enabled. The values in config_default.yaml are suggestions for the Raspberry Pi 4 or Raspberry Pi Zero2.
Be aware the ADC-chips can do one conversion at a time. So if you have more than one channel activated, the intervals between neighboring samples on each channel are multiples of this value. E.g. if channels 1, 4 and 7 are activated, the samples of channel 4 will be 3x 20ms = 60ms apart.
| resolution
in bits |
Samples per seconds, according
to MCP3424 datasheet |
Duration of a conversion in ms
according to MCP3424 datasheet |
value in config_default.yaml | |||||
|---|---|---|---|---|---|---|---|---|
| min | typ | max | max | typ | min | in milliseconds | corresponding SPS | |
| 12 | 176 | 240 | 328 | 5.68 | 4.17 | 3.05 | 20 | 50 |
| 14 | 44 | 60 | 82 | 22.73 | 16.67 | 12.20 | 50 | 20 |
| 16 | 11 | 15 | 20.5 | 90.91 | 66.67 | 48.78 | 100 | 10 |
| 18 | 2.75 | 3.75 | 5.1 | 363.64 | 266.67 | 196.08 | 400 | 2.5 |
Displayer
The displayer controls the display of mhia pi. It includes the behavior of the application when buttons are pushed on the device. Enabling the displayer is optional. In most cases after installation, mhia pi will acquire sensor data and securely publish them over trusted infrastructure, with no need for direct monitoring or any user interaction with the device. But a display and a few tactile buttons on the device itself not only can help setting up on site, but also will attract more views during hardware demonstrations. Be aware that the displayer script consumes the most resources of the Raspberry Pi, so disable it when not needed.
In the current version, there are 5 main display modes available:
- Single Channel (
display_mode11 to 18) - Multi Channel (
display_mode9) - Line Chart (
display_mode21 to 29) - QR screen (
display_mode40) - Info screen (
display_mode51 to 53)
You can switch between the main modes using the up and down buttons of the tactile navigation switch on the mhia pi board. In single-channel or line chart mode you can use the left and right buttons to switch between channels in the same display mode.
Single-channel mode
In addition to displaying the current voltage captured on a sensor input channel, in single-channel mode some information about the sensor itself is displayed. You should supply these sensor information in the config file under the appropriate channel number in the channels_config item. In the next image the fields on the LCD in single-channel mode are explained. A screenshot of the corresponding configuration file opened is also uploaded here for comparison.
The two first lines on the display show the values of description and label of the corresponding channel in the configuration. These two values are just read and displayed for each channel.
The channel number is self-explanatory.
The shown value can be the latest quantized raw voltage signal with a 'V' for volt, or a calculated value according to /channels_config/<<ch#>>/calc/coefficients set in the config.yaml (or config-default.yaml) file together with a user set unit string. By pushing the center button on the navigation switch you can switch the value and unit field between the raw sensor value and the calculated value and unit. This is also indicated by 'SENS' or 'CALC' on the left.
The bottom line shows some information about the current voltage range of the ADCs input. The first item in that line is the the sensor output range in volts. This is read again directly from the configuration file for the corresponding channel, min_voltage, max_voltage. As you can see in the configuration example, each channel has also the item wanted_pga. This sets the gain of the input channel before quantization of the signal. Setting wanted_pga to 2, means the signal (voltage) is multiplied with 2. This reduces the allowable maximum value the ADCs can quantize. As you can see in this example the maximum volt that the ADC can handle on that channel is divided by the the same wanted_pga value. So in the last line the user can double check if the sensors maximum possible output voltage is lower than ADCs allowable input voltage for that channel.
You can switch between the channels using the left and right buttons.
Here are some screenshots of the displayer's output in 'CALC' view:
Multi-channel mode
The multi-channel mode is intended to display the latest quantized values of each activated channels on one screen. Switching between sensor output and calculated value ('SENS' and 'CALC') is not implemented in this mode yet!
Line chart mode
In this mode a live moving line chart of one channels sensor values are displayed. The vertical axis is scaled according to the set PGA of the channel. As you can see in the screenshot below, the top horizontal line is at 1.25V, that is at a PGA of 4 the highest value the ADC can quantize.
The horizontal (time) axis is scaled in the way that each pixel on the display (in width) represents the duration between two consecutive samples, that is the currently set sampling interval. As a result, at lower sampling rates the chart will move slower and at higher rates faster.
You can switch between the channels using the left and right buttons. Whenever you switch between the channels the chart is cleared and a new moving chart will be drawn.
QR code screen mode
For now this screen shows a static QR code that is generated during startup from the value of /display/qr-text from the configuration file. The QR code is intended to represent a link to an online dashboard showing the live captured values of each channel.
(For debugging and documentation we implemented an experimental "take screenshots" feature in this mode. When the user hits the center button once, a screenshot is taken from the last screens of the other modes (single-channel, multi-channel and line chart) and saved in the screenshots directory. Be aware that the colors will look differently (mainly darker but also a bit distorted color tones) on a computer screen. Read also the comments in the /display section of the configuration file.)
Info screen mode
Currently this mode shows just some information of the running application and device (for now just static information), currently in three pages. You can switch between the pages using left and right buttons. One page shows the current hostname and IP address of the device. Another one shows some set ADC parameters (from configuration). The third page shows for now if publisher is enabled and its parameters (from configuration, experimental).
Publisher
When the publisher is enabled, it will try to establish a connection to the MQTT broker (server) specified in the configuration file. The publisher only supports connections using Transport Layer Security (TLS). It connects only to MQTT broker, that deliver a trusted server certificate at beginning of the handshake. The publisher will also send a client certificate to the broker to authenticate itself. Therefore you need to set up the paths to these files in the configuration:
cafile: full chain certificate for validating whether the server certificate is signed by a trusted certificate authoritycertfile: client certificate signed by the authority which the server trustskeyfile: the clients key, that was used to requestcertfilefrom the certificate authority
You can use the ./certs folder to put these files inside (or symbolic links to them). Everything inside the ./certs folder except README.md will be ignored by git.
The publisher relies on the Eclipse Paho MQTT client library. If you want to set another kind of security mechanism or for some reason none at all, you can change the publisher script. You can also find some example scripts for the Eclipse Paho library here: https://pypi.org/project/paho-mqtt/
Configuration (config_default.yaml)
The config includes all settings for the python scripts, which are grouped in the categories mentioned below. Be aware that the content of the file is a dictionary in YAML-format. The content is not validated, before the processes start, so wrong structure or data types will probably crash execution of one or more scripts or result in undefined behavior. Please read the comments in the config_default.yaml carefully. The detailed description is written as comments in the file.
If you want to change the configuration we suggest that you copy config_default.yaml as config.yaml, to keep the default configuration. The processes will ignore if there is a config.yaml in the main folder of the application. (For contributors: config.yaml is included in .gitignore)