HomeLab-pH software for Arduino

For Arduino controllers there are three pieces of HomeLab software to select from: A‑Lib , A‑Vis  and A‑Server . Each one is intended for a different use case. The software should be compiled and loaded to the controller memory using the Arduino IDE. A‑Vis  and A‑Server  need A‑Lib  preinstalled.

A-Lib

The A‑Lib  is a library for the Arduino IDE. The library exposes functions to the user's code for reading the sensors signals and calculating the sample pH. No means to perform a calibration are present though. To calibrate the module use one of the other available software (easier with A‑Vis ).

A-Vis

The A‑Vis  is an Arduino IDE sketch which relies on the A‑Lib  code to give the user a visual interface for reading data and calibrating the module. It is intended for direct interaction at the console interface.

A-Server

The A‑Server  is another Arduino sketch that uses the A‑Lib  code. It allows a remote machine to read and calibrate the module over a special protocol. To the remote machine the Arduino controller has the role of a HomeLab‑pH data server. No visual interface.

The sketches and the library are packed in a separate .zip files to download. Get instructions here about how to install the sketches.

Measured parameters

Four parameters and their values are shown (or sent) in a line:

V= 112.1 [mV]   T= 23.4 [C]   pH= 5.01   BTN=0

The measured voltage and temperature are used to calculate the pH. Additionally the status of the on-board button is checked.

Calibration procedure

The software allows calibration to be only performed with the most commonly used buffers, namely: pH 4.00 - phthalate, 7.00 - phosphate, 10.01 carbonate (contact us for ways of changing to another set). A standard two points calibration is performed where for each point any of the three buffers may be used as long as they are different. Note that both the pH-electrode and the temperature sensor should be put in the vessel with the fresh buffer and also they have to be rinsed with clear water between the measurements.

System information

A-Vis calibration info

Useful information about the system is presented by selecting "1" within the A‑Vis Main menu or received by sending #GI request to the A‑Server. The top 4 lines in A‑Vis (see the screenshot) show test results concerning HomeLab-pH health. They need always to show "passed" for the system to function properly. Next there is a block of information to identify the software, the board and the temperature sensor. Last is the current calibration data.

Speed of response and resolution of the temperature sensor

The resolution of the temperature sensor can be set by selecting "2" within the A‑Vis Main menu or by sending #Stn request to the A‑Server. This parameter is the primary factor for the system speed of response. The bigger the value of the temperature resolution the faster is the overall response. It is recommended, though, to not set the resolution greater than 0.12°C (default) when measuring pH values lower than 2 or greater than 11 at low temperature and especially during calibration. Doing otherwise may lead to measuring the pH with greater inaccuracy.

Transmission rate

The transmission rate to correctly communicate with the software is 9600 bauds.

Arduino IDE Library

While the library does offer extensive functionality to read sensors data, it currently does not support calibration of the module. In case you develop your own code based on A‑Lib  and it does not implement calibration you may consider calibrating the module in advance using the A‑Vis  sketch.

Usage instruction are to be found in the README.md file. A helpful Arduino example is included as well.

Loading API of A‑Lib ...

Visual Interface

PUTTY terminal emulator is used to illustrate the functionality of the A‑Vis software. Click on the images for larger view.

A-Vis software start This is the starting screen showing some hardware data and the Main menu. Here the calibration data is replaced by a "No valid calibration data" message. It shows when either the data is damaged or the board is brand new with no single calibration performed.
The choices within the Main and all other menus are made by entering the number matching the desired functionality.

Measurement - single shot or cyclic

A-Vis measurement data A choice of "5" within the Main menu starts cyclic measurement (no gap between the measurements) till whatever keyboard key is pressed to cancel. Here the on-board button is detected to have been pressed and later released.

A-Vis measurement data A choice of "4 - single shot" within the main menu shows the same data as "5" but returns to the Main menu after a single line is printed.

Calibration

A-Vis calibration 1-st point A choice of "3" within the Main menu starts a standard two-point calibration procedure. Enter the number matching the selected buffer to start cyclic measurement of the buffer.

A-Vis calibration 2-nd point Here a buffer of 7.00 pH has been selected to be measured as a first calibration point. The readings were stable before accepted. The recorded data is valid (no any error is shown) and now a buffer for the second calibration point is to be selected.

A-Vis successful calibration The second calibration point was chosen to be pH 4.00. A successful calibration has been completed and the calculated electrode asymmetry and slope are shown.

A-Vis calibration info A choice of "1" within the Main menu now shows also the calibration data.

Temperature resolution

A-Vis setting temperature resolution A choice of "2" within the Main menu presents a submenu where the temperature sensor resolution can be selected. Here the resolution has been reset from 0.50°C to 0.12°C.

Missing temperature sensor

When the temperature sensor is detached from the module, the real automatic temperature compensation (ATC) of the pH value is not possible. Nevertheless the system will still show the measured pH "assuming" the temperature is 25°C.

A-Vis no temperature sensor No temperature sensor is found, so the T-sensor test has failed. The temperature and the pH values are prepended with asterics (*) to hint that the temperature value is assumed while the pH was compensated for an assumed temperature.

A-Vis setting temperature resolution Callibration will not be allowed with missing temperature sensor.

A-Vis setting temperature resolution Resetting temperature resolution is obviously not possible.

Remote Access

Remotely the communication with the A‑Server is accomplished by the client sending a request and receiving a response. Each request begins with the # (sharp) letter. The response can be either a primary response or an error. The error response syntax is ERRn, where 'n' is a number corresponding to an error code (i.e. ERR14). See a list of all errors and their descriptions.

To ease the user entry in the client-server communication we prepared a quick-start list of requests.

Requests and responses

You may get a list of all available requests by sending  ?  (question mark) to the server.
#GA
meaning: get asymmetry
primary response: float, to the tenths
description: pH-electrode asymmetry in millivolts
example: 2.4
response error codes: 1,4-23
#GB
meaning: get button state
primary response: 0 or 1
description: 1 indicates the board button is currently pressed
response error codes: 1
#GC
meaning: get calibration status
description: calibration data validity check; errors are returned on one-fixed-then-next basis
primary response: the string "OK"
response error codes: 1,4-23
#GI
meaning: get system information
primary response a list of parameter:value
example:
ADC test : passed
T-sensor test : passed
EEPROM test : passed
Callibration test : passed
 
Software version : 180303AS
Board revision : 3.0
Board ID : 2130360003
T-sensor ID : 28 FF 9C 57 47 16 03 6F
T-sensor resolution : 0.12 [C]
 
pH-buffer 1 : pH = 4.00 Phthalate
T-calibration 1 : 27.2 [C]
pH-buffer 2 : pH = 7.00 Phosphate
T-calibration 2 : 27.3 [C]
slope : 97.8 [%]
asymmetry : -5.1 [mV]
response error codes: 1
#GL
meaning: get a line of data
primary response:
description: a single line of measured parameters and their values
example: V: 112.1 [mV]   T: 23.4 [C]   BTN: 0   pH: 5.01
response error codes: 1,4,5
#GP
meaning: get pH
primary response float, to the hundredths
description: current pH value
example: 10.32
response error codes: 1,4-23
#GR
meaning: get ready status
primary response: the string "OK"
description: system status check; errors are returned on one-fixed-then-next basis
response error codes: 1-23
#GS
meaning: get slope
primary response: float, to the tenths
description: calibration slope; percents of theoretical
example: 98.2
response error codes: 1,4-23
#Gt
meaning: get temperature resolution
primary response: 0.06 or 0.12 or 0.25 or 0.50
description: current resolution of the T-sensor in degrees Celsius
response error codes: 1,6-9
#GT
meaning: get temperature
primary response: float, to the tenths
description: sample temperature measured in degrees Celsius
example: 22.5
response error codes: 1,6-9
#GV
meaning: get voltage
primary response float, to the tenths
description: voltage from pH-sensor measured in millivolts; can be negative
example: -123.4
response error codes: 1-5
#SLn
meaning: set LED state
    description:
  • n=0 to set LED OFF
  • n=1 to set LED ON
primary response: the string "OK"
response error codes: 1,28
#SPnx
meaning: set a calibration point
    description:
  • n=1 to set point 1
  • n=2 to set point 2
  • x=1 to use buffer 1; buffer 1 is pH 4.00 phthalate
  • x=2 to use buffer 2, buffer 2 is pH 7.00 phosphate (or pH 6.86 - needs code change)
  • x=3 to use buffer 3, buffer 3 is pH 10.01 carbonate
primary response: the string "OK"
response error codes: 1,4,5,24-26
#Stn
meaning: set temperature resolution
    description:
  • n=1 to set to 0.50°C
  • n=2 to set to 0.25°C
  • n=3 to set to 0.12°C
  • n=4 to set to 0.06°C
primary response: the string "OK"
response error codes: 1,6-10,27

Error codes and responses

Code  Response  Description
1 ERR1 Bad connection. (Check the assigned GPIO pin numbers or the cable.)
2 ERR2 The ADC-chip does not respond.
3 ERR3 The ADC-chip does not work properly.
4 ERR4 No EEPROM device found.
5 ERR5 Invalid EEPROM-chip record.
6 ERR6 No 1-wire device found.
7 ERR7 Temperature sensor bad CRC response (probable presence of multiple 1-wire devices).
8 ERR8 The temperature sensor ID does not match the user-set ID.
9 ERR9 The temperature sensor is not the HomeLab type sensor (DS18B20).
10 ERR10 The temperature sensor resolution is undefined.
11 ERR11 No calibration data is available.
12 ERR12 Invalid buffer number for calibration point 1 (must be 1,2 or 3).
13 ERR13 Invalid buffer number for calibration point 2 (must be 1,2 or 3).
14 ERR14 The pH of the calibration buffers is too close (difference must be > 1.0 pH).
15 ERR15 The buffer pH for calibration point 1 is out of the range 0 - 14 pH.
16 ERR16 The buffer pH for calibration point 2 is out of the range 0 - 14 pH.
17 ERR17 The voltage for calibration point 1 is out of range (theoretical value ±40 mV)*.
18 ERR18 The voltage for calibration point 2 is out of range (theoretical value ±40 mV)*.
19 ERR19 The temperature for calibration point 1 is out of the range 0°C - 100°C.
20 ERR20 The temperature for calibration point 2 is out of the range 0°C - 100°C.
21 ERR21 Invalid time and/or date for calibration point 1.
22 ERR22 Invalid time and/or date for calibration point 2.
23 ERR23 The time interval between the calibration points is longer than 50 min.
24 ERR24 Invalid buffer number.
25 ERR25 A parameter is out of limits.
26 ERR26 Invalid calibration point number.
27 ERR27 Can not set the temperature resolution.
28 ERR28 Invalid LED setting.
33 ERR33 Invalid request.
* the theoretical response value of a pH-probe for a buffer at 25 C is:
59.16 mV * ((buffer pH at 25 C) - 7)

A quick entry in calibration and pH measurement

To start measurements with a new board a calibration of the system has to be fulfilled first. Also periodic calibrations are needed to allow for the changes of the pH-electrode as these sensors tend to change with time. See below a simple sequence of user actions and requests to the A‑Server to calibrate the system.

#GR
Prior to calibration some tests of the connected board should be done. A successful general check of the system has to return "OK".
#Gt
Check what resolution the temperature sensor is set to. During a calibration procedure it is best to be 0.12°C or 0.06°C. Set it with #St3 or #St4.
1-st point
Calibration is a process where a person is involved to handle the sensors and buffers. Flush the pH-electrode and the temperature sensor with clean water. Select a buffer for the first calibration point and put the sensors in it.
#GV and #GT or #GL
Code some type of a cycle to get separately voltage and temperature or, alternatively, get a data line (#GL) of all measurements combined. Monitor the data from both sensors until it becomes stable enough to proceed.
#SP12
Save the last measured values as data for the first calibration point. If successful "OK" will be the response. While any of the buffers may be selected, this particular request shows that buffer 2 (pH 7.00 phosphate) was used for the point.
2-nd point
For the second calibration point select a different buffer and proceed the same way as described for the first one. For instance #SP21 sets the data of the 2-nd point after measuring buffer 1 (pH 4.00 phthalate).
#GC
Do a request for a thorough check of the integrity of the calibration data. A successful check should respond with "OK", which means that the calibration has been completed successfully.
#GS, #GA
Finally data concerning the quality of the pH-electrode and the performed calibration may be shown to the user. #GS returns the slope while #GA - the asymmetry.
#GP
Now the pH can be measured.

The response of each of the requests may result also in some of the listed errors. The code should handle these cases as well.

A stripped down minimum of requests during calibration:

1. #GR - get "OK"
2. immerse the sensors in the buffer and call
#GL until data values become steady
3. #SP1x - set the first point; replace x with a buffer number
4. repeat 2. and 3. for the second point (#SP2x)
5. #GC should return "OK"

Sketches Upload

Flashing of the A‑Vis  and the A‑Server  sketches is performed in the Arduino IDE. Tested IDE versions are 1.6.7 and 1.8.1.

Each of the sketches needs the HomeLab A‑Lib  library preinstalled. So, if not done yet, get the library and import it.

Download also the sketch zip-file. Unpack it and follow the procedure below.

  1. Load the program code in the editor.
    Use File > Open to find and, depending on the application, select the
    HomeLab-A-Vis-xxxxxxAV.ino ( A‑Vis )
    or the
    HomeLab-A-Server-xxxxxxAS.ino ( A‑Server )
    sketch. The "xxxxxx" would correspond to the software version number. Confirm if asked to create a folder for the sketch. If successful you should see the HomeLab code in the editor's code area.
  2. Select a GPIO-pin-set.
    In the code text select the GPIO-pin-set corresponding to the type of Arduino board the program is to be flashed in. Selection is done by uncommenting/commenting code lines as shown in the pictures below (click). One and only one GPIO-pins-set should be selected.

    If your Arduino board is not listed under any of the GPIO-pin-sets check if it is excluded by the HomeLab‑pH hardware requirements or contact us for an advice.

    GPIO-pins-set 1 selectedGPIO-pin-set 1 selected for:
    BT,
    Due,
    Duemilanove (ATmega328),
    Ethernet,
    Leonardo, Leonardo ETH,
    M0, M0 Pro,
    Mega, Mega 2560, Mega ADK,
    Pro (5v),
    Tian,
    Uno, Uno WiFi,
    Zero, Zero Pro.

    GPIO-pins-set 2 selectedGPIO-pin-set 2 selected for:
    Micro,
    Mini V05,
    Nano V3.

  3. Connect the Arduino controller board to the computer.
  4. Select the proper controller type in Tools > Board and a communication port in Tools > Port.
  5. Compile and flash the program in the controller's memory by Sketch > Upload. No error messages are shown if successful.

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.

Downloads

The sketches and the library are tested with Uno V3 and Nano models.

Library

Visit this page for guidance how to import a zip-library in the Arduino IDE or just follow the included README.md file. If a version of this library is already present, it has to be removed manually from the file system in advance. Otherwise the Arduino IDE will complain.

A‑Lib  version 0.3.0 Download

Visual interface sketch

Attn: Needs A‑Lib  preinstalled.

A‑Vis  version 180522AV Download

Server sketch

Attn: Needs A‑Lib  preinstalled.

A‑Server  version 180522AS Download