Software

This section of the documentation explains how to install and configure the Mini-Monitor software on a Raspberry Pi computer. There are three steps to install and configure the software.

1. Download, unzip, and write the Image file containing the Mini-Monitor software onto an SD card.
2. Insert the SD card into a PC and edit the Settings file to configure the Mini-Monitor for your application.
3. Boot the Raspberry Pi with the SD card, log on, and upgrade the Mini-Monitor software to the newest release. Reboot to begin using the newest software.

Each of these three steps is described in more detail in the following sections.

Download and Install Mini-Monitor SD Card Image

The Raspberry Pi uses an SD card as a solid-state drive for the storage of the operating system, programs, and user data. We have made a complete image of the SD card containing the Raspbian Linux Operating System and the entire Mini-Monitor software application. This image is based on the Raspberry Pi OS Lite image. You can download a zipped version of this image from the link below. The file is about 1.8 GB in size so will take some time to download.

Mini-Monitor SD Card Image (1.5 GB), version 3.9

Use the Raspberry Pi Imager software to write the image to an 8 GB or greater micro-SD card.

GUI Configuration Program

The SD card has a partition that is readable on a Windows PC, Mac, or Linux computer. On a Windows PC it will show up as a drive labeled boot. On this partition is a GUI-based setup utility available that can easily configure Internet access and a few other key settings. The utility can be run from the Windows PC or the Mac PC that created the card. The file name of the utility is settings_editor_win.exe for use on a Windows PC, and settings_editor_mac for use on a Mac PC. This utility allows for setting up an ID for the logger, configuration Internet access, and configuring the Utility meter reader software.

Manually Set up Internet Access

Configuration can also be performed manually by editing files on the boot partition of the SD card. Although these files are usable on a Windows PC, they are text files that use the line-ending format (“n”) used on Linux computers. It is important to preserve that type of line-ending when editing the files. The standard Notepad program that comes with the Windows Operating System does not preserve Linux line endings. Most text editors used for programming do preserve line endings, such as EditPlus or Notepad++. You need to use one of these editors when editing the files described in this section and the next.

The first issue to address is setting up Internet Access. Here are three possibilities:

• Wired Ethernet Internet access through the RJ-45 port on the Raspberry Pi. No special software configuration is needed for this option.
• Wireless Internet access either through the built-in WiFi adapter present on the Raspberry 3, or through a USB WiFi adapter plugged into a USB port. For more details on setting up a WiFi connection for the Raspberry Pi, click here.
• Internet access through a Cellular Modem connecting to a mobile data network. For certain Huawei cellular modems (models E173u-6, E173s-65, E3276s-500, E3276s-505, and E1756C) connecting to the GCI (Alaska) mobile data network, configuration just involves setting the USE_CELL_MODEM parameter to True in the Settings file, and setting the CELL_MODEM_MODEL parameter to the correct model type, as described below. For other modems and other carriers, appropriate modification of the pi_logger/wvdial.conf file on the SD card will be required. See documentation of the WvDial program for further information.

If you need to set up a static IP address for the Raspberry Pi, the pi_logger/dhcpcd.conf is available for that purpose. See this article . The appropriate settings lines are at the bottom of the dhcpcd.conf file, but are commented out by default.

Configure Settings File for your Application

The next step is to edit the special Mini-Monitor Settings file on the SD card to configure the software for your application. The settings file is found at pi_logger/settings.py when accessed through the SD card, and

/boot/pi_logger/settings.py when actually running on the Pi.

Open this file in a text editor; see the discussion in the prior section regarding the use of a Text Editor that preserves Linux line endings. This file is essentially a Python code file, but the only types of statements in the file are comments (any text appearing after the “#” symbol at the beginning of a line) and variable assignment statements, like:

LOGGER_ID = 'test'

The rest of this section will explain the key variables that can be altered in this file. Excerpts from the file will be shown followed by an explanation of setting. After modifying values in the file, simply save it back to the SD card.

# The unique ID of this particular logger, which will be prepended to
# sensor IDs.
LOGGER_ID = 'test'

Each Mini-Monitor needs to be assigned an ID that is unique across all of the Mini-Monitors posting data to a particular BMON web site. The ID should be kept to 13 characters or less, using only letters and numbers (no spaces). An example is ‘Okla511’, which was used for a building at 511 Oklahoma Street. As shown in the example above, the ID string must be enclosed in single or double quotes.

# The intervals for reading sensors and for logging readings
READ_INTERVAL = 5     # seconds between readings
LOG_INTERVAL = 10*60  # seconds between logging data

The READ_INTERVAL setting controls how often the Mini-Monitor reads the sensors attached to it. The value is expressed in seconds, and in general it should be a value of 5 seconds or longer. The LOG_INTERVAL expressed in seconds determines how often the sensor readings are summarized and posted to the BMON server. As you can see in the example above, a math expression can be used, such as 10 * 60. If READ_INTERVAL is set to 5 seconds and the LOG_INTERVAL is set to 10*60 or 10 minutes, sensors will be read 120 times before their data is posted to the BMON server. For analog sensors or readings (ex. temperature) the 120 readings are averaged together before being posted to the BMON server. A post is timestamped in middle of the 10 minute interval, since the posted value represents conditions occurring throughout the interval.

For sensors or readings that are state values, such as On/Off readings or perhaps a Fault Code, every change of state that occurs in the 10 minute interval is posted as a separate reading value, appropriately timestamped. The last state recorded in the interval is also posted, even if no change occurred in the interval.

Note that these settings do not apply to separate processes that post sensor data directly to the Mini-Monitor MQTT broker; the settings apply only to the Sensor Reader Classes described in a following section. As an example, the Utility Meter Reader script is a separate process that posts directly to the MQTT broker; it has a separate interval setting found near the bottom of the Settings file and described later in this document.

Settings related to Using a Cellular Modem for Internet Access

# Set following to True if you are using a USB Cellular modem
# to connect to the Internet.
USE_CELL_MODEM = False

USE_CELL_MODEM should be set to True if a USB Cellular Modem is being used to provide Internet Access.

# If you are using a cell modem, set the following to a string indicating
# the type of cell modem you are using.  This string must be one of the
# "Dialer" sections in the wvdial.conf file found in the /boot/pi_logger
# folder (the folder also containing the Mini-Monitor settings file.)
# Currently, the following value are supported:
#
#     E173: Works with the Huawei E173 mdoem
#     E3276: Works with the Huawei E3276 modem
#     E1756C: Works with the Huawei E1756C modem
#
# Mini-Monitor uses the WvDial Linux utility to connect the cell modem
# to the Internet.  The /boot/pi_logger/wvdial.conf is the configuration
# file for WvDial and can be edited to modify configuration settings and/or
# enter new Dialer sections to support different models of modems.  Also,
# The wvdial.conf file is set up with the APN of the GCI carrier in Alaska.
# (see the Init3 configuration settings). This can be modified for other carriers.
# See documentation of the Linux WvDial program for further information on
# the configuration file.
# NOTE: some versions of the E1756C modem did not reliably connect using
# the current wvdial.conf settings.  Use the E173 or E3276 modems if possible.
CELL_MODEM_MODEL = 'E173'

The CELL_MODEM_MODEL parameter must be set to one of the allowed string values to selet the type of cellular modem being used. As described in the comments above for this parameter, adjustments can be made to the wvdial.conf file to use other types of cellular modems or use carriers other than GCI (Alaska). See documentation of the WvDial program and the wvdialconf program for information on making those adjustments.

Settings related to Posting to a BMON Server

# Set following to True to enable posting to a BMON server
ENABLE_BMON_POST = True

# URL to post readings to, and required storage key
# An example BMON URL is "https://bms.ahfc.us"
# The Store Key can be any string with no spaces
POST_URL = '[BMON URL goes here]/readingdb/reading/store/'
POST_STORE_KEY = 'Store Key Goes Here'

ENABLE_BMON_POST should be set to True to have the Mini-Monitor post data to a BMON server. The POST_URL is the Internet URL where the Mini-Monitor will post its data. For a BMON web-based sensor system, a sample URL is https://bms.ahfc.us/readingdb/reading/store/. The particular BMON system you are posting to has a secret storage key, which should be entered as the POST_STORE_KEY setting.

Sensor Reader Classes

# A list of sensor reader classes goes here
READERS = [
'ha7s.HA7Sreader',             # 1-Wire Sensors
'sage_boiler.Sage21Reader',    # Burnham Alpine Boilers w/ Sage 2.1 controller
#'aerco_boiler.BMS2reader',    # AERCO BMS II Boiler Manager
#'dg700.DG700reader',          # Energy Conservatory DG-700 Pressure Gauge
#'labjack.LabjackTempReader',  # Thermistors connected to Labjack U3
#'sensaphone.SensaphoneReader',   # Reads Node sensors from Sensaphone IMS 4000
'sys_info.SysInfo',            # System uptime, CPU temperature, software version
]

The READERS setting holds a list of sensor reading code segments that are needed for your application. If you want to use a particular sensor reader, remove the ‘#’ symbol from the beginning of the line. To disable a particular sensor reader type, enter a ‘#’ at the beginning of the line. In the example above, three sensor readers are enabled:

• The reader for 1-Wire sensors connected to the Mini-Monitor.
• The reader that will collect data from a Burnham Alpine Boiler using the Sage 2.1 controller.
• A reader that will report general system information including the amount of time the system has operated since the last reboot, the temperature of the CPU, and the Mini-Monitor software version.

Do not change anything else in this section other than adding or removing ‘#’ symbols from the beginning of reader lines.

More detail is provided on each reader type in the Available Sensor Readers document. That document explains what values are read and reported by the various readers.

Settings related to Mini-Monitor Health

# Number of days of uptime between forced reboots.  Set to 0 to never reboot.
REBOOT_DAYS = 2

# Reboots if Error Count is too high
CHECK_ERROR_CT = False

# Reboots if Last Post was too long ago
CHECK_LAST_POST = False

The Mini-Monitor can be configured to automatically reboot itself on a schedule, which can add to the stability of the system when unforeseen problems are occurring. The value of REBOOT_DAYS is expressed in days, and we have typically chosen to reboot every two days. If the setting is set to 0, the Mini-Monitor will never intentionally reboot.

If CHECK_ERROR_CT is set to True, the Mini-Monitor will reboot if the number of errors occurring in the application are too high. If CHECK_LAST_POST is set to True, a reboot will occur if the Mini-Monitor is not successfully posting readings to the BMON server.

Settings related to Logging Errors, Warnings, and Operational Information

# This controls what messages will actually get logged in the system log
# 'Logging' here does *not* refer to sensor logging; this is error and debug
# logging.
# Levels in order from least to greatest severity are:  DEBUG, INFO, WARNING,
# ERROR, CRITICAL
LOG_LEVEL = logging.INFO

This setting controls how Error and Debug logging operates in the Mini-Monitor. The setting is not related to sensor logging, instead, it relates to logging how the program code is operating. The LOG_LEVEL setting determines how many events are recorded into the log file. We normally run this at the logging.INFO level, but when debugging a problem, more information will be logged with the logging.DEBUG value. The main log file is located on the Raspberry Pi at /var/log/pi_log.log. Other log files associated with the Mini-Monitor are: /var/log/pi_cron.log, /var/log/mqtt_to_bmon.log, /var/log/meter_reader.log, and /var/log/mosquitto.log. All of these files, except mosquitto.log are affected by the LOG_LEVEL setting.

Settings related to Recording Data from a Sensaphone

# If you are using the sensaphone.SensaphoneReader reader, then you need
# to set the IP address of the Host Sensaphone unit below
SENSAPHONE_HOST_IP = '10.30.5.77'

This final setting is only necessary if you are using the SensaphoneReader class. The IMS-4000 host IP address should be entered in this section, using single quotes. Ensure that the device has access to the network where the IP address is located.

Settings related to Recording Transmissions from Utility Meters

# Set to True to enable the meter reader
ENABLE_METER_READER = False

# A Python list of the Meter IDs you wish to capture and post.
# Use empty brackets to read all meters, i.e.:  []
METER_IDS = [1234, 6523, 1894]

# The minimum number of minutes between postings. If you set
# this too low, the resolution of the posted meter reading delta
# will be low.
METER_POST_INTERVAL = 30  # minutes

# The multipliers below are applied to the rate of change calculated from
# sequential meter readings.  They can be used to convert that
# rate of change into engineering units, such as BTU/hour.
# There is a separate multiplier for Gas Meters, Electric Meters and Water Meters.
# *** NOTE: If you set a multiplier to 0, that type of Meter (gas, electric, water)
# will not be recorded by the Mini Monitor.
METER_MULT_GAS = 1000.0       # Converts Cubic Feet/hour to Btu/hour
METER_MULT_ELEC = 1.0         # Electric Meter Multiplier
METER_MULT_WATER = 1.0        # Water Meter Multiplier

These settings are for the script that can receive meter reading transmissions from certain Utility meters. See the Hardware document for the necessary Mini-Monitor hardware. Further discussion of the values posted by this script is available in the Available Sensor Readers document.

The ENABLE_METER_READER setting must be set to True to enable reading of utility meter transmissions. METER_IDS is a Python list containing the Meter IDs of the meters you wish to record. You can generally find the Meter ID number on the meter nameplate, as shown in this picture:

You can also use a METER_IDS setting of empty brackets, [] to record all meters received by the Mini Monitor.

METER_POST_INTERVAL is the minimum number of minutes between meter readings that are used to create a recorded/posted value. As explained in the Available Sensor Readers document, the script posts the amount the utility meter value has changed, so if this METER_POST_INTERVAL is too short, a low resolution change value will be reported.

Finally the various METER_MULT_ settings give multipliers that are applied to the rate of change value determined by the meter reader before it is sent to be stored or posted. The meter reader normally calculates a rate of change per hour; for a natural gas meter that value usually has the units of cubic feet per hour. Setting METER_MULT_GAS to 1000.0 then converts the value to BTU/hour, since there are approximately 1,000 BTUs per cubic foot of natural gas.

If any of the METER_MULT_ settings are set to 0, that type of meter will be ignored and not recorded.

Upgrade Mini-Monitor Software to Newest Release

Once you have updated the Settings file on the SD card, the next step is to start the Raspberry Pi and upgrade the Mini-Monitor software to the newest version. Insert the SD card into the Raspberry Pi, connect an Ethernet cable with Internet access, and apply power. Then, log onto the Pi either through use of a console cable or an SSH connection. The log on credentials are:

mini-monitor login:  pi
Password:  minimonitor

Change into the main software directory and update the software using a Git source control pull command by using these commands:

cd pi_logger
git pull

If you would like to change the log-in password, use the passwd command. Reboot the logger to utilize the new software:

sudo reboot

In the future if you need to update the Mini-Monitor software, this same process should be repeated. Also, for a new update, you should inspect the /home/pi/pi_logger/system_files/settings_template.py sample Settings file to see if any new setting variables have been added, which could require an update of your actual Settings file, as discussed in the prior section.