A summary of what hardware is needed:
The visual interface is used to view the measured data and to calibrate the system. Also information about the system is displayed and some parameters like temperature scale or server write authorization can be set. The visual interface is accessible at the ESP8266 module IP address,
There are several ways to find the module's address:
The meter has to be calibrated in short time periods as pH-electrodes are not quite famous for their stability. Calibration accuracy may be affected if temperature is not measured. So, in this case the button may not be active to prevent starting the procedure. When calibration is active its first screen will show a few types of alternative modes to choose from. The user interface in each mode is mostly self-explanatory.
Two points calibration
Calibration with user set iso-potential data.
InfoThere is some information available about the pH-board, ESP module, calibration data, etc. View it by clicking this button.
Some of the actions in this screen are saved server side and thus affect all clients. This is why deleting calibration data or changing the temperature sensor resolution requires server write authorization, i.e. access has to be set to "allowed". The user may change the access to allowed/not allowed by clicking the change button while simultaneously holding the on-board button pressed. As a precaution, after you are done with the settings set the server write access to "not allowed". This will prevent further changes via not secure local network.
User may also select the data request interval which allows for the latency of the network. In our tests we found the 1.5 s long interval as being the best. Select a longer one if you find the system blocked and messages like "Error occurred during the transaction." or "Error. The pH module is not responding." appear. Changing the data request interval is not affected by the server write access as it is saved at the client side.
MessagesOccasionally the software sends some useful messages and warnings to the user. This button will conveniently show or hide them.
ATTENTIONMQTT features are temporarily disabled since version 1.2.240105.
This button is active only if MQTT connections are enabled prior to code uploading.
Some setting of the MQTT connection like broker address and port, username and password for authenticated access can be set here. Others are only listed for user reference. Publish interval is also available to be selected. When ready with the edits press the button submit & connect to reconnect the broker. Note that it is possible to submit only when server write access is allowed. Whether the broker is connected or not can be judged by the status shown against publishing pH now. The status is either 'yes' or 'no'. It takes some time for the connection to be re-established and the status updated.
ThingSpeak MQTT Devices are accessed in a slightly different way. So, except for the publish time interval, all settings of a ThingSpeak dashboard should be made in the code before upload.
Here is a list of available requests with descriptions.
board is an object that holds either the EEPROM data or is empty. For
eepromError see getEPRError.
tSensor is an object that either holds the temperature sensor data or is empty.
slope and the
asymmetry are obligatory. Both have float numbers as values. The
asymmetry represents the measured sensor offset at pH = 7.00 in millivolts.
The measured data can be shown on a SSD1306 128x64 display.
Sharp sign ' # ' is a warning that calibration has not yet been performed.
Exclamation mark ' ! ' indicates that the pH value shown is not temperature compensated.
The following description is checked against Arduino IDE versions 1.8.x .
To work properly HL‑ESP‑server needs some libraries and other software to be available or installed in advance. Libraries in the Arduino IDE are installed either by its Library Manager, as a .zip file or "manually". Turn to the Arduino tutorial on this topic. (Note that the Arduino core for ESP8266 chip and the SPIFFS filesystem uploader are installed in a special way.)
Here is the list of the libraries needed:
Arduino core for ESP8266 chip
SPIFFS filesystem uploader
HomeLab_pH, ver. 1.2+
And also, if a display is to be used:
To upload the software to the microcontroller's memory a driver for its communication chip has to be available in the computer OS. Normally, once the computer system with the module are connected, the system would recognize the chip and install a suitable driver automatically. If this does not happen you have to download the driver from the web and install it manually. Check the type of the communication chip of your ESP8266 microcontroller. Almost certainly it is either CH340, CP2102 or CH9102. So search the web for e.g. "CH340 USB to serial driver".
A freshly installed Arduino IDE does not support the ESP8266 chip, but it does offer way of achieving "unofficial" support. To add support to a huge number of ESP8266 modules go to
File -> Preferences
add the URL
to the text field "Additional Board Manager URL's" and press the OK button.
If the measured data is going to be also shown on an SSD1306 display use the Library Manager to install the Adafruit_GFX and Adafruit_SSD1306 libraries. Confirm also installation of dependences, if asked.
ESPAsyncTCP, ESPAsyncWebServer and HomeLab_pH are not available in the Library Manager list. So, they have to alternatively be installed as .zip files using
Sketch -> Include Library -> Add .ZIP Library.
The HomeLab_pH library is available to download at the Downloads section of this site. Note that any previous installation present in the Arduino Sketchbook location has to be deleted manually.
After the installation check the libraries are listed (see the image).
CAUTIONHL‑ESP‑server will not work with HomeLab_pH library version 1.0.0 .
The HL‑ESP‑server code consists of two parts - compiled program and web server files. The latter are flashed using a special "filesystem uploader". It does not come with the Arduino IDE and has to be installed separately. Download it from this link and install as described at the SPIFFS filesystem uploader home page.
After the installation
ESP8266FS > tool directory should contain the esp8266fs.jar file.
This section describes how to upload the HL‑ESP‑server code to the ESP module's memory. Before get the things running check what prerequisites are needed. Also download and unzip the HL‑ESP‑server.zip archive.
Any pre-existent HL‑ESP‑server code will be lost during the upload to the ESP module's memory. So would be the data related to an already performed calibration after the upload of the program data. Rather than to calibrate again you may prefer the already existent calibration data be available after the new upload. To achieve this first download the calibration data in a browser as a file. Then move the downloaded file to the 'data' directory of the freshly unzipped HL‑ESP‑server code. Note that if needed the file should be properly renamed to
Some changes inside the code have to be made before the sketch is uploaded.
Select the WiFi working mode of the ESP module as access point (AP) or station (STA). The default is AP. In this mode the module may work as standalone pH meter available at "HL-ESP" as default SSID and http://192.168.4.1 as default IP address. The optional display is supported as well. The MQTT support though is available only if STA mode is selected.
When this sketch starts the ESP8266 module in STA (station) mode its IP address is dynamically assigned by the network router.
Uncommenting the line with
define USE_STATIC_IP allows the user make the module's IP address a static one. Then assign it by changing the
local_IP as needed. Take note of its value to later point your browser to. Also if necessary change the gateway value to be in the same subnet as the
ATTENTIONMQTT features are temporarily disabled since version 1.2.240105.
If an MQTT broker is to be connected uncomment the code line with
define ENABLE_MQTT. This will make effective the settings of the MQTT connection. Broker address and port, username and password, etc. can be set in the code itself prior to its uploading or later through the web user interface.
The ThingSpeak MQTT Device is connected in a special way and you may not use the visual web interface to edit the settings. Instead set username, password, channel ID and client ID before the code is uploaded. These edits take effect only if the code lines with
define USE_THINGSPEAK and
define ENABLE_MQTT are both uncommented.
All set variables have to correspond to the credentials of a registered ThingSpeak MQTT device.
local_IP address set (see above),
To get accurate values do not forget to calibrate the system beforehand.
(requires HomeLab_pH library version 1.2+)
HomeLab_pH library Download