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.
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 ).
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.
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.
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.
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.
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.
The transmission rate to correctly communicate with the software is 9600 bauds.
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.
PUTTY terminal emulator is used to illustrate the functionality of the A‑Vis software. Click on the images for larger view.
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.
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.
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.
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.
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.
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.
|description:||pH-electrode asymmetry in millivolts|
|description:||1 indicates the board button is currently pressed|
|description:||a single line of measured parameters and their values|
|example:||V: 112.1 [mV] T: 23.4 [C] BTN: 0 pH: 5.01|
|description:||current pH value|
|description:||system status check; errors are returned on one-fixed-then-next basis|
|description:||calibration slope; percents of theoretical|
|description:||current resolution of the T-sensor in degrees Celsius|
|description:||sample temperature measured in degrees Celsius|
|description:||voltage from pH-sensor measured in millivolts; can be negative|
|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.|
|* the theoretical response value of a pH-probe for a buffer at 25 C is:
59.16 mV * ((buffer pH at 25 C) - 7)
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.
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"
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.
If you have found a bug or have a proposal for improving the user experience, please share it with us at the contact form.
The sketches and the library are tested with Uno V3 and Nano models.
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.
Attn: Needs A‑Lib preinstalled.
Attn: Needs A‑Lib preinstalled.