HomeLab 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.
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.
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
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
- You need A‑Lib HomeLab library installed in Arduino IDE when you:
- want to write your own applications for the HomeLab-pH meter or,
- want to use A‑Vis or A‑Lib sketches.
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.
Visual Interface
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.
Measurement - single shot or cyclic
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 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 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.
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.
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 choice of "1" within the Main menu now shows also the calibration data.
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.
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.
Callibration will not be allowed with missing temperature sensor.
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
| description: | pH-electrode asymmetry in millivolts |
| example: | 2.4 |
| description: | 1 indicates the board button is currently pressed |
| example: |
|
| 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 |
| example: | 10.32 |
| description: | system status check; errors are returned on one-fixed-then-next basis |
| description: | calibration slope; percents of theoretical |
| example: | 98.2 |
| description: | current resolution of the T-sensor in degrees Celsius |
| description: | sample temperature measured in degrees Celsius |
| example: | 22.5 |
| description: | voltage from pH-sensor measured in millivolts; can be negative |
| example: | -123.4 |
- description:
- n=0 to set LED OFF
- n=1 to set LED ON
- 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
- 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
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.
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.
- Load the program code in the editor.
Use 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. - 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-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-pin-set 2 selected for:
Micro,
Mini V05,
Nano V3. - Connect the Arduino controller board to the computer.
- Select the proper controller type in and a communication port in .
- Compile and flash the program in the controller's memory by . 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.
Visual interface sketch
Attn: Needs A‑Lib preinstalled.
A‑Vis version 191018AV Download
Server sketch
Attn: Needs A‑Lib preinstalled.