Software for ESP8266

The software which can be downloaded here is a sketch for the Arduino or equivalent IDE. It is aimed at carrying out the communication between ESP8266 microcontroller and HomeLab-pH module. The software also fits several use cases:


To prepare the system follow the instructions given in the Prerequisites•Libraries•Driver and Unzip•Set•Upload sections.

HomeLab-pH with ESP8266 and display

A summary of what hardware is needed:

Visual Interface

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:

Main screen

The visual interface main screen has a buttons bar and three areas where digital values are displayed. Just below the buttons bar the pH value is displayed. The other two displays show the voltage and the temperature values.
Redish icons may appear to indicate the pH value has been altered in a way that may impact its accuracy:
- the pH value is not temperature compensated,
- no calibration of the system has been performed.

Buttons bar


HomeLab-pH user interface - main screen

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.

show more


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


Occasionally the software sends some useful messages and warnings to the user. This button will conveniently show or hide them.
A button to access this site. For reference, if needed.

Access by HTTP Requests

Measured pH, temperature and other pieces of data are also accessible via a separate HTTP requests.
Here is a request example:
where is the IP-address of the ESP module. (It would probably be different for your network.) Response is sent as plain text or as JSON formatted string.

Here is a list of available requests with descriptions.

Delete the calibration data.
Request method GET
Content type text/html
Response A string:
  • ok, deleted.
  • Failed.
  • Failed, missing file.
  • Failed: write not allowed.
Check the status of the ADC chip on-board the pH module.
Request method GET
Content type text/html
Response A number:
  • 0 - no errors;
  • 1 - the ADC-chip does not respond;
  • 2 - the ADC-chip does not respond properly;
Get the status of the server write authorization. See setAuthorization.
Request method GET
Content type text/html
Response A string:
  • no - no authorization is required;
  • button - authorization is required;
Get the pH-module ID and other data written inside the pH module on-board EEPROM.
Request method GET
Content type application/json
Response A JSON formatted string with two members: board and eepromError. board is an object that holds either the EEPROM data or is empty. For eepromError see getEPRError.
Example {"eepromError" : "0" , "board":{"id" : "21406b00011" , "revision" : "4.0" , "offset" : "0.0" , "amplification" : "1.0000" , "R1" : "130.3" , "R2" : "130.3"}}
Example {"eepromError" : "2" , "board":{}}
Get the status of the button on-board the pH module.
Request method GET
Content type text/html
Response A number:
  • 0 - the button is not pressed;
  • 1 - the button is pressed;
Get the calibration data.
Request method GET
Content type application/json
Response A JSON formatted string or, if no data - an empty object. See also setCalibrationData.
Example {"slope" : "-58.60" , "asymmetry" : "0.13" , "averageT" : "24.40"}
Example {}
Check the status of the EEPROM chip on-board the pH module.
Request method GET
Content type text/html
Response A number:
  • 0 - no errors;
  • 1 - no EEPROM found;
  • 2 - invalid EEPROM-chip record;
Get voltage (mV), temperature (°C), button press status, pH, system uptime (ms), pHCompensation and calibration statuses.
Request method GET
Content type application/json
Response A JSON formatted string.
Example {"temperature" : "24.38" , "button" : "0" , "uptime" : "67119" , "adcError" : "0" , "voltage" : "172.2" , "pH" : "4.06" , "pHCompensation" : "1" , "calibration" : "1"}
Example {"temperature" : "" , "button" : "0" , "uptime" : "299254" , "adcError" : "0" , "voltage" : "172.3" , "pH" : "4.06" , "pHCompensation" : "0" , "calibration" : "1"}
Get the pH value.
Request method GET
Content type text/html
Response pH as float or as an empty string if error.
Example 7.52
Get the software version.
Request method GET
Content type text/html
Response A string.
Example 1.0.220310
Get the temperature (°C) measured by the sensor.
Request method GET
Content type text/html
Response Temperature as float or as an empty string if error.
Example 22.75
Get the temperature sensor ID and resolution (°C).
Request method GET
Content type application/json
Response A JSON formatted string with two members: tSensor and tSensorError. tSensor is an object that either holds the temperature sensor data or is empty.
Example {"tSensorError" : "0" , "tSensor":{"id" : "28ff0436b516033b" , "resolution" : "0.12" , "resolutionBits" : "11"}}
Example {"tSensorError" : "1" , "tSensor":{}}
Get the voltage (mV) generated by the pH-sensor.
Request method GET
Content type text/html
Response Voltage as float or as an empty string if error.
Example 312.5
Enable or disable the server write authorization. To confirm the change simultaneously hold pressed the button of the pH-module.
Request method GET
Content type text/html
Query string
  • no - set to no authorization is required;
  • button - set to authorization is required;
Response A string:
  • ok
  • Failed.
  • Failed writing.
  • Failed: hold the on-board button pressed.
  • Failed: unknown auth.
  • Failed: no parameter.
Set the calibration data to be applied in pH calculation. Authorization must be set to 'no'. See setAuthorization.
Request method POST
Content type application/json
Request body A JSON formatted string. While the JSON object may have various optional members, the 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.
Example {"slope" : "-58.60" , "asymmetry" : "0.13"}
Example {"slope" : "-58.60" , "asymmetry" : "0.13" , "averageT" : "24.00" , "timeStamp" : "1647103727489"}
Response A JSON formatted string:
  • {"status" : "ok"}
  • {"status" : "error", "msgStr" : "Not json!"}
  • {"status" : "error", "msgStr" : "Error writing to file."}
  • {"status" : "error", "msgStr" : "Failed: write not allowed."}
Set OFF the on-board LED.
Request method GET
Content type text/html
Response ok
Set ON the on-board LED.
Request method GET
Content type text/html
Response ok
Set the temperature sensor resolution by sending 'resolution' as a query parameter. Authorization must be set to 'no'. See setAuthorization.
Request method GET
Content type text/html
Query string
  • resolution=9 for 0.50 C
  • resolution=10 for 0.25 C
  • resolution=11 for 0.12 C
  • resolution=12 for 0.06 C
Response A string:
  • ok
  • Failed.
  • Failed: no parameter.
  • Failed: write not allowed.

Show Data on a Display

The measured data can be shown on a SSD1306 128x64 display.

HomeLab-pH module wired to SSD1306 display Connecting SSD1306 display.

To make active the display option uncomment a line in the code prior to the sketch upload.

Pay attention to the # and ! signs that may appear on the pH screen.

Sharp sign ' # ' is a warning that calibration has not yet been performed.

Exclamation mark ' ! ' indicates that the pH value shown is not temperature compensated.

Prerequisites • Libraries • Driver

This software, named HL-ESP-server, is a sketch intended to be flashed to ESP8266 microcontroller from the Arduino IDE. Visit this page for guidance on installing the IDE. Also for HL-ESP-server to work properly some libraries and other software has to be available or installed in advance in the Arduino IDE.

Here is the list of the libraries needed:
Arduino core for ESP8266 chip
SPIFFS filesystem uploader
HomeLab_pH, ver. 1.1+

And also, if a display is to be used:

There are three ways to install libraries in the Arduino IDE - by its Library Manager, as a .zip file and "manually". You may turn to the Arduino tutorial on this topic.

Note that the Arduino core for ESP8266 chip and the SPIFFS filesystem uploader are installed differently, though.

Also, 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 USB cable to connect the computer system with the module is plugged in, the system would recognize the chip and install the 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 in your ESP8266 microcontroller. Almost certainly it is either CH340, CP2102 or CH9102. So search the web e.g. for "CH340 USB to serial driver".

Install Arduino core for ESP8266 chip

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.

Restart the Arduino IDE, open the Boards Manager from Tools > Board menu, find the esp8266 platform and click the install button. The image here shows a proper installation is accomplished.


Install Libraries by the Library Manager

Open the Library Manager.

The ArduinoJson library is listed in the Library Manager so find it there and press the "Install" 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.


Install Libraries as .zip Files

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.

Here are links to download ESPAsyncWebServer library and ESPAsyncTCP library as .zip files.

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.

CAUTIONHL-ESP-server will not work with HomeLab_pH library version 1.0.0 .

After the installation check the libraries are listed (see the image).


Install SPIFFS filesystem uploader

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.



HL-ESP-server Download
version 1.0.220420
SHA256 checksum:

    Changes to version 1.0.220326:
  • Fix: Display not active when WiFi connection has failed.
  • Add: If WiFi failed show this on the display.
  • Add: Validation check by the UI: calibration slope to be between -30 and -90 mV/pH.
  • Add: Calibration data may be downloaded as file.
  • Change: By default start with IP-address of the module dynamically assigned.
  • Add: The user may select how the module's IP-address is assigned: router or user.
  • Add: Show the selected temperature scale also on the main screen.

HomeLab_pH library Download
version 1.1.0
SHA256 checksum:

Unzip • Set • Upload

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

After the code upload is accomplished any pre-existent HL‑ESP‑server code in the ESP module's memory will be lost. So would be any data related to an already performed calibration. Rather than to calibrate again you may want to existent calibration data be available after the uploading. Achieve this in two steps. First download in a browser the data as a file. Then to make the data ready for the future upload just 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 current_calibration_data.json

Start the Arduino IDE and open (File -> Open) the HL‑ESP‑server.ino sketch file.

Some changes inside the code have to be made before the sketch is uploaded.

Set the WiFi SSID and password to match the credentials of the network to connect to.

As default this sketch starts the ESP8266 module in STA (station) mode and the its IP address is dynamically assigned by the network router.

Uncommenting the line with 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 local_IP.

If a display is to be used uncomment the code line with USE_DISPLAY.

Select your board.

Set a COM-port.

Upload the sketch.

Upload the sketch data.

To get accurate values do not forget to calibrate the system beforehand.