Developers¶
This section of the documentation is aimed at developers who wish to better understand and perhaps modify the Mini-Monitor software. The code is thoroughly commented, but the documents described below are meant to provide higher level documentation for the application. It is recommended that the <software> document be read as a prerequisite to this document.
Mini-Monitor is a Python 3 application and is currently running with
Python 3.7.3 on the Raspberry Pi running a Raspbian Buster Lite Linux
distribution, July 2019 version. On the Raspberry Pi, the Python code
for the application is found in the pi
user’s directory space in the
folder /home/pi/pi_logger
. References to file paths in the following
text will all be relative to that directory.
Overall Structure of the Application¶
Starting with version 1.7, the Mini-Monitor software is designed to use
an MQTT Broker to manage the transport of sensor
readings from software that acquires the readings to software that
consumes the readings, for example, software that posts the readings to
a BMON server. The specific MQTT broker that is used and hosted on the
Mini-Monitor is Mosquitto. The broker runs
as a daemon on the Raspberry Pi and is started via the systemd script
/etc/systemd/system/mosquitto.service
.
As of version 1.7, there are a few different processes that acquire sensor readings and publish them to the MQTT broker:
pi_logger.py
: This script instantiates “Readers” that are enabled in the settings file, these readers periodically read their associated sensors. After passage of a logging time interval (as specified in the Settings file),pi_logger.py
publishes reading summaries to the MQTT broker (average values for analog sensors, or state changes for sensors that determine the state of a device).meter_reader.py
: The Mini-Monitor has the ability to listen to meter reading radio broadcasts from utility meters. The utility meter is not “polled” by the Mini-Monitor but instead waits for readings to arrive. So, thepi_logger.py
style of sensor reading did not apply. Instead, a separate script is available that listens for these readings and publishes rates of change of the cumulative meter value to the MQTT broker.rtl433_reader.py
: The Mini-Monitor has the ability to read Acurite 592TXR Temperature/Humidity Wireless sensors by using a RTL2832U USB-connected software defined radio (the same device used by the meter reader script described above.)power_monitor.py
: The Mini-Monitor can read a Peacefair PZEM-016 Electric Power sensor through use of this script.
These sensor reading scripts are started by the standard
rc.local
script that the Raspberry Pi runs at the end of its boot up
process. In order to include the rc.local
script in the Mini-Monitor
source code, a symlink is created from the standard /etc/rc.local
file to an rc.local
file located in the Mini-Monitor software folder
at system_files/rc.local
. It is valuable to look at this file for
other details on the Mini-Monitor start-up process.
pi_logger.py
is only started if at least one Reader file is enabled
in the Settings file. The other scripts described above are started
depending on flags found in the /boot/pi_logger/settings.py
file.
As of Version 1.7, there is only one possible consumer of sensor
readings published to the MQTT broker: the mqtt_to_bmon.py
script,
which receives sensor readings and posts them to a BMON server on the
Internet. Enabling and configuring that script occurs in the Settings
file. If enabled, it runs in a separate process from pi_logger.py
and meter_reader.py
. In the future, a basic log-to-disk sensor
reading consumer is envisioned.
mqtt_to_bmon.py
subscribes to the readings/final/#
topic on the
MQTT broker. All sensor readings published to that topic set will be
received by mqtt_to_bmon.py
and posted to the BMON server.
pi_logger.py
publishes to the topic readings/final/pi_logger
and
meter_reader.py
publishes to the topic
readings/final/meter_reader
.
Reader Files¶
The Mini-Monitor is designed so it is easy to mix different sensor
types and data sources in the data acquisition process. As mentioned in
the prior section, pi_logger.py
utilizes Reader classes to read
different types of sensors. Each Reader class knows how to gather data
from a particular data source, e.g. a 1-Wire sensor network or a
particular boiler type. The READERS
setting in the settings file holds that
list of classes. The list items for the READERS
setting are in the
format of <file>.<class name>
. All of these files are located in the
readers
directory of the application.
Each specific Reader class inherits from readers/base_reader.Reader
.
The specific Reader class only needs to implement a read()
method.
The requirements for that read()
method are described in the
base_reader.Reader
base class. Basically, the read()
method
returns a list of sensor readings.
A number of equipment manuals are available that relate to the existing Reader classes. These are listed and are accessible from the Relevant Manuals page.
To add a new data source to the Mini-Monitor software, you
only need to write a new Reader class and put that class in the
readers
directory. Then, add the class to the READERS
variable
found in the Settings file, described in the next section.
Alternatively, a separate script can be written, similar to
meter_reader.py
, that can acquire sensor readings and
publish them directly to the MQTT broker.
Settings File¶
In the Software document, the Settings file was described in detail.
This file controls the types of data sources the deployed Mini-Monitor
will collect data from and controls a number of other data collection
parameters. The Settings file that is used by the deployed Mini-Monitor
is found at /boot/pi_logger/settings.py
. This file is not in source
control because it contains a secret Store Key for the BMON system
receiving the data, and it as setting specific to the particular
application being deployed. There is a sample Settings file that is kept
in source control and is present at
system_files/settings_template.py
.
If you add a new Reader class to the Mini-Monitor software, you should
add the <file>.<class>
name to the READERS
variable in both the
sample Settings file (system_files/settings_template.py
) and the
operational Settings file for the Mini-Monitors you have deployed that
need to use the new Reader.
Cron Tasks¶
The Mini-Monitor system has a Cron job that runs every 15 minutes and
executes the scripts/cron_15m.py
script. This script performs a
number of health checks on the Mini-Monitor, records some some summary
information in the application log file, and performs a few other tasks
that should run in a process independent of the main Mini-Monitor
software.
Raspbian OS Configuration¶
Some configuration was done to the Raspbian operating system for use in the Mini-Monitor. As a user of the Mini-Monitor, if you download the SD card image according to instructions on the Software page, you do not need to perform any of the following configuration changes. The SD card image already includes all of these configuration changes. The information in this section is meant for developers attempting to understand or modify the Mini-Monitor system.
The modifications to the base Raspbian Buster Lite image are described in this document