HomeLab-pH software for Raspberry Pi

HomeLab-pH back view with smartphone displaying user interface.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, as well as presents to the user an interface to log the pH 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 console or get it remotely via an http request.

Visual interface

HomeLab-pH user interface - main screenThere is a button bar and three areas where digital values are displayed. Just below the button bar the pH value is displayed. The other two displays show the voltage and the temperature values. 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.

button calibrationThe 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.


button infoLog 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.


button unassistedDuring the software installation a cron job for periodic unassisted measurements (PUM) has been registered at the OS crontab. Here PUMs 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.

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.


button infoRead 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.


button infoThere 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.


button messagesOccasionally 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.


button HL linkA 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:


For json-formated output use "-json" or "-j" option:

/var/www/homelab/cgi-bin/get_pH.sh -json

Shell access

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


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:


replacing accordingly the <rpi-ip-address>.

Shell access

Of course, to see the http response you may also simply invoke cURL at the console.

curl http://<rpi-ip-address>:7223/command/getPH

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. 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.

Now - time for a test. Check the Pi has internet access. Load/reload the program in your browser to read the newly configured channel. Just for the testing - set a PUM-task with the shortest sampling time interval of 5 min and wait till some data is communicated. Try to plot it. See the user interface section for guidance.

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", ver.16.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.


An active internet connection has to be available during the installation.

  1. Go to the Downloads and get the HomeLab-pH installation file.
  2. Create a new installation directory and copy the file there.
  3. Move to this directory and unpack the file:
    tar -xvf hl_install_xxxxxxx.tar.gz --overwrite
    ("xxxxxxx" to correspond to the version number)
  4. Run the package installation like this:
    sudo bash homelab_install.sh
  5. Wait for the script to finish.
    If successful:
  6. 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.?
  7. Restart the system if asked to do so.


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.

Found a bug?

If you have found a bug or have a proposal for improving the user experience, please share it with us at the contact form.


There are currently two versions available to download. The newer one, 181126B BETA, has the feature of unassisted measurements. Namely - the meter takes measurement at a user selectable time interval ranging from 5 min to 24 hours. When required the data can be viewed through the user interface. The software may also optionally plot the data using a connection to a thingspeak.com user account. The connection attributes has to be entered by the user in a configuration file.

Version with unassisted measurements

The version is in its testing phase, so any feedback will be highly appreciated.

Version 181126B BETA Download

SHA256 checksum:

The changes to the previuos 180730B_BETA version include the
mounting of a small 1MB RAM disk on boot to store temporary data,
dropped support for versions of Raspbian OS earlier than Dec 31st, 2014 and
fix for a bug that prevented storing of data to send later to reconnected Thingspeak account.

No unassisted measurements

Version 180121B Download

SHA256 checksum:

Log of the versions' changes.