HomeLab Software for Raspberry Pi
The HomeLab-pH board is just a measuring block. It has to be assisted by an external CPU-board and corresponding software to perform the calculations. The software package, which can be downloaded here, is intended to work with Raspberry Pi or compatible computer as server. (For Arduino boards read this page.) It visualizes the measured data and presents to the user an interface to log the pH, set timing for periodic unassisted measurements and calibrate the device. Visualization is done by a browser residing on a smartphone, laptop, tablet, etc. that connects to a LAN-address where the server is installed.
Additionally, interested users can access the measured data at the Raspbian/Ubuntu Mate console or get it remotely via an http request.
Visual interface
Access the visual interface by pointing a web browser to
http://<rpi-ip-address>:7223
The visual interface consists of a button bar and three areas where digital values are displayed. Just below the button bar is the pH value. The other two areas show the voltage generated by the pH-sensor and the sample temperature measured by the temperature sensor.
A tiny display bottom right shows the difference between the current temperature and the one measured during the calibration.
Using the button bar the user can do some useful things, the main being the calibration of the board.
The meter has to be calibrated in short time periods as pH-electrodes are not quite famous for their stability. There are a few types of calibration procedures accessible via this button. The user interface in calibration mode is mostly self-explanatory. see how
To start the calibration procedure the system waits for the user to confirm by pressing the board button. A count-down clock is started.
When the button is pressed, the user is given three choices of calibration type to select from.
Two points calibration
"Two points" is the most widely used calibration.
First step is to calibrate at pH 7.
Second and final step is to calibrate either at pH 4 or pH 10.
Custom calibration
"Custom" calibration gives the user maximum flexibility to calibrate with buffers of different pH.
As many buffer points can be measured as needed.
In each step the user can select among 13 pH buffers in the range from 1 pH to 13 pH.
Calibration with user set iso-potential data.
"Manual iso-point" calibration is especially useful when pH measurements at different temperatures are made and the electrode iso-potential point is known or measured in advance.
First the iso-potential point data has to be entered by the user.
Then one point calibration is made.
Successful calibration.
At the end of the calibration procedure an informative message is shown.
close
Log the current pH, temperature and other data by this button. see how
The pH and temperature values are updated constantly. Pressing the "hold" button "freezes" last measured values (only at the white area) and shows the next screen.
Either log the data to the server or return to the previuos action.
Data is logged and tracking the measured values resumed.
close
The meter may take continuous unassisted measurements (PUM) with user selectable time interval. Here PUM are managed, listed and plotted. see how
Setting a PUM-task
If no task is running the user is presented a button to set one.
Enter a short description and select a sampling time interval for the periodic measurements (from 1 min up to 24 hours).
If a sampling time interval longer than 1 hour is selected, set also the time of the first measurement. Click/tap 'SET' while pressing the on-board button.
There are four button to manage a running PUM-task. Use the 'Settings' button to change task parameters.
Cancelling a PUM-task
Cancel a running task with the 'End' button.
Confirm the cancellation. To succeed hold the on-board button pressed while clicking/tapping 'Confirm'.
View the data
To see the data click/tap the 'list' button.
The task attributes are presented along with the measurement data sets. Each measurement set is on a separate line, the most recent being on top.
The same PUM-task data may also be accessed through the data log button. All tasks are listed. The currently running one is missing the delete option on its line.
Plot the data
To plot the data click/tap the 'plot' button. A plotter has to be configured and active.
Plotting pH. Hovering a mouse pointer over a point shows the corresponding data.
To plot the temperature click/tap the 'temperature' button. (Respectively for the voltage.)
Here something went wrong with the connection. Check the connection attributes in the configuration file.
close
Read the logged data, PUM data as well. see how
A list of logged measurement files is shown. User can either delete a file or list its content.
A measurement file content is listed.
File deletion has to be confirmed.
close
There is some information available concerning the board, temperature sensor, calibration data, etc. View it by clicking this button. Temperature scale can be selected as well. see how
System data is shown. Temperature scale may be selected - Fahrenheit or Celsius.
close
Occasionally the software sends some useful messages and warnings to the user. This button will conveniently show or hide them. see how
A message of detached temperature sensor is shown.
close
A button to access this site if your browser is connected to the internet.
Shell access
Measured data can also be accessed at the shell by:
/var/www/homelab/cgi-bin/get_pH.sh
For json-formated output use "-json" or "-j" option:
/var/www/homelab/cgi-bin/get_pH.sh -json
- The parameter names and values are as follows:
- "taskStatus" is either "ok" (normally) or 'bad'.
- "time" value is Unix Epoch Time in seconds.
- "v" is the generated voltage in mV.
- "t" is the sample temperature in degrees Celsius.
- "pH" is, obviously, the pH of the sample.
- "calibID" is, well - the last calibration procedure id.
- "calibDate" is the date the calibration was performed.
If error or warning messages are present they are shown as "errorStrings" - a comma-separated list of strings. This case is illustrated at the lower part of the picture above, where a missing temperature sensor is reported. Some members may get the value of "skipped" (or boolean "false" in json-formated response).
Reading the module from Python
It is possible to read HomeLab-pH data also using Python. The script has to execute the above shell command.see how
#!/usr/bin/python
import os, json
# execute the shell command and assign the result
data = os.popen('/var/www/homelab/cgi-bin/get_pH.sh -json').read()
# just to see the result
print (data)
# convert the json string
d = json.loads(data)
# see the pH value
print (d['pH'])
# see the temperature
print (d['t'])
Remote http access
To see the json-formated output above, type at the browser address field the following address:
<rpi-ip-address>:7223/command/getPH
replacing accordingly the <rpi-ip-address>.
Of course, to see the http response you may also simply invoke cURL at the console.
curl http://<rpi-ip-address>:7223/command/getPH
Installing the Software
The package installation is performed under Raspbian or Ubuntu Mate operating systems. They should be downloaded at the Raspberry Pi web site. Raspbian is in fact a Debian GNU-Linux. Supported are 7.8, 8.0 and all later Debian versions. Ubuntu supported version is "Ubuntu Mate for the RPi 2 & RPi 3", versions 16.04 and 18.04.
The operating system should have Apache web-server installed to send the module readings to the browser. If it is not found the installation script will try to install the Apache package. Other modules and packages to be installed if not present are: i2c_bcm2708, i2c_dev, i2c-tools, w1-gpio, w1-therm and bc.
Installation
An active internet connection has to be available during the installation.
- Go to the Downloads and get the HomeLab-pH installation file.
- Create a new installation directory and copy the file there.
- Move to this directory and unpack the file:
tar -xvf hl_install_xxxxxxx.tar.gz --overwrite
("xxxxxxx" to correspond to the version number) - Run the package installation like this:
sudo bash homelab_install.sh
or to enable PUM:
sudo bash homelab_install.sh --enable-pum
or to disable PUM:
sudo bash homelab_install.sh --disable-pum - Wait for the script to finish.
If successful: - Take a note of the printed IP-address at the end of the installation. This is where the HomeLab-pH meter may be accessed in your LAN.
- Restart the system if asked to do so.
Usage
Be sure the RPi, which the HomeLab-pH board is mounted on, is connected to the LAN and powered. Plug in the temperature sensor and a pH-electrode in their sockets on the board. Start a web-browser on a whatever device (laptop, tablet, smartphone) connected to the same LAN and point it to the device's IP-address. You will see the HomeLab-pH page main screen with the meter readings.
What if you do not know the local IP-address of the RPi? Well, you may try the address printed at the end of the installation procedure. If you have just installed the software there is a good chance for the IP-address to not being changed by the router. Otherwise you have to use a LAN-scanner to find the address.
If the RPi is configured to use a dynamic IP-address, when restarted it may be assigned a different one by the router. So, if you are forced to do address searching frequently when measuring pH, it is better to assign a static (not changing) IP-address to the RPi computer.
A bug found?
If you have found a bug or have a proposal for improving the user experience, please share it with us at the contact form.
Periodic Unassisted Measurements
This software may take continuous unassisted measurements - PUM. The time interval between measurements is user-selectable ranging from 1 min to 24 hours. For intervals greater then 1 hour the user additionally may set the full hour at which the measurement is to be taken.
Enable and disable a PUM cron job
The PUM rely on a cron job which fires every five minutes starting at full hour. The job is not registered to crontab by default. Its availability is managed in two ways: by the installation script or by shell commands.
To make the cron job running the software installation script should be started with an argument:
sudo bash homelab_install.sh --enable-pum
Alternatively if present the job is removed during installation with:
sudo bash homelab_install.sh --disable-pum
If neither option is set the user would be asked to decide intaractivelly.
The cron job is also managed by shell console commands. May be started by:
/var/www/homelab/cron/set.sh
and removed by:
/var/www/homelab/cron/unset.sh
PUM-task configuration data
Only one PUM-task can be active at a time. A prerequisite to start a task is to have a running PUM cron job. The cron job reads the task's configuration file to determine if it's time to take a measurement. This file location is:
/var/www/homelab/cgi-bin/data/cron.cfg
The file content is governed by the visual interface ( click [see how] button here ). So it's not good practice to change the contents manually.
Below is an example of a PUM-task configuration data. The data is in JSON format.
{"id":"1576375200","interval":300,"aPointAt":0,"newLog24":true,"description":"test 35"}
The "id" of each task is unique and reflects the time the task has been set at.
PUM-task data log
Each task has its own log file. Below is a short excerpt from a common PUM log. This is what is logged when calibration is available and both sensors are in place.
{"id":"1575684000","interval":300,"aPointAt":0,"newLog24":true,"description":"TEST","data":[
{"taskStatus":"ok","time":1575597601.260,"v":1.3,"t":23.9,"pH":7.00}
,{"taskStatus":"ok","time":1575600002.018,"v":1.3,"t":24.0,"pH":7.00}
,{"taskStatus":"ok","time":1575600301.739,"v":1.3,"t":24.0,"pH":7.00}
,{"taskStatus":"ok","time":1575600601.500,"v":1.3,"t":24.0,"pH":7.00}
,{"taskStatus":"ok","time":1575600902.099,"v":1.3,"t":23.9,"pH":7.00}
,{"taskStatus":"ok","time":1575601801.178,"v":1.3,"t":23.8,"pH":7.00}
,{"taskStatus":"ok","time":1575602101.939,"v":1.3,"t":23.6,"pH":7.00}
,{"taskStatus":"ok","time":1575602401.785,"v":1.3,"t":23.6,"pH":7.00}
,{"taskStatus":"ok","time":1575602701.338,"v":1.3,"t":23.5,"pH":7.00}
]}
The data log is JSON-formated, the first line being a copy of the PUM-task's configuration data. Each time a new measurement is taken for the task, a new line with data is appended, where:
- "time" is the time of measurement in seconds since the start of the UNIX Epoch,
- "v" is the voltage measured in millivolts,
- "t" is the temperature measured in decrees Celsius,
- "pH" is the pH.
The directory where the PUM log files are placed is:
/var/www/homelab/cgi-bin/data/cron/log/
Log files rotation
The file rotation feature allows data logging to be done in a special way. If file rotation is active a new log file is started every 24 hours. Unlike the usual PUM task's the file rotation task has multiple files and an "id" in such a file reflects the time (future) when the file will be rotated at.
To use or not 24 hour file rotation is controlled by the visual interface (default is NO). The time when the rotation is to be done is set in a configuration file. To change the time edit this file:
/var/www/homelab/cgi-bin/cron_config.sh
Plotting Data
Data accumulated from periodic unassisted measurements (PUM) is periodically send to the cloud and at user demand its plot is retrieved from there. Currently the ThingSpeak cloud service is used for the purpose.
The usage of the feature is controlled by shell commands. To start/stop sending data to the Thingspeak cloud use:
/var/www/homelab/cron/thingspeak/start.sh
/var/www/homelab/cron/thingspeak/stop.sh
There are two prerequisites before seeing your data plotted: register a data channel at thingspeak.com (they offer a free account, which is suitable for this usage) and enter the channel's connection attributes in a configuration file.
So, the first step is to register an account at ThingSpeak. It would not take more than a couple of minutes. Go to thingspeak.com and do it. An email box has to be available for the account verification.
Second - create a data channel. In the freshly created account go to Channels > My Channels and click the New Channel button. Give a name to the channel and activate the first 3 fields of the channel. These will be accessed by our software to write the pH, temperature and voltage values respectively, in this order. See the picture.
Save the channel.
In the new screen go to API keys and look for 3 items: the Channel ID, the Write API Key and the Read API Key. See the picture.
Write down or copy their values for later use. Click around the channel menu to see you can do other useful things here like clearing your data or making the channel private.
The third step is to edit a configuration file of the installed HomeLab software. The simplest way is to start the nano editor at the shell:
nano /var/www/homelab/site/cron/thingspeak/channel_config.sh
and replace there the values of the channel_id, the write_api_key and the read_api_key with the ones from the ThingSpeak channel. See the picture.
Save the changes.
Now - time for a test.
- Check the Pi has internet access.
- To start sending data to the Thinkspeak account execute at the shell console: /var/www/homelab/cron/thingspeak/start.sh
- Load/reload the program in your browser to read the newly configured channel data.
- Just for the testing - set a PUM-task with the shortest sampling time interval of 5 min.
- Wait until some data is communicated. Try to plot it (see the user interface section for guidance).
Downloads
SHA256 checksum:
eac397720eeddd37ceb4de1f77bb62d86c23176f75df954ada617cb43849aec3
Changes to the previuos 240102B version:
At Periodic Unassisted Measurement (PUM) the least time interval available to the user for selection is set from 5 minutes down to 1 minute.
Log of the versions' changes.