HomeLab Software for ESP8266

The free software presented 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 and Upload sections.

HomeLab-pH with ESP8266 and display

A summary of what hardware is needed:

WiFi Manager

The server has a WiFi manager with own visual interface. The manager allows for WiFi mode selection - access point (AP) or web station (STA). The user may also set the WiFi credentials and the server connection data.

When started for the first time the server goes ahead with the default AP mode and shows the WiFi manager interface. This happens unless changes has been made in the code settings to disable the manager or start the module in STA mode.

Once the user submits the data she/he has 60 s to confirm physical access by pressing the module on-board button. The server will restart with the saved connection settings. If there is a problem with them the WiFi manager will fall back to starting with the default settings as set in the code.

The WiFi manager is enabled by default and could be disabled by uncommenting a line in the code:

If not disabled the manager is available at

The WiFi settings are deleted by the following web command (see more details):

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 consists of a button bar and three areas where digital values are displayed. Just below the button bar is the pH value. The other two areas show the voltage generated by the pH-sensor and the sample temperature measured by the temperature sensor.
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.

MQTT settings

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.

    Published data:
  • the measured pH sensor voltage,
  • the measured temperature,
  • the calculated pH,
  • is pH temperature compensated (0 or 1),
  • is calibration data used in calculating pH (0 or 1),
  • the server uptime in milliseconds.
  • The data can be accessed by subscribing to the listed topics.

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.

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.) GET is the applied request method, with POST for setCalibrationData being the only notable exception. Responses are sent either as plain text or as JSON formatted string.

Here is a list of available requests with descriptions.

Delete the calibration data. Authorization must be set to 'no' in advance. See setAuthorization.
Request method GET
Content type text/html
Response A string:
  • ok, deleted.
  • Failed.
  • Failed, missing file.
  • Failed: write not allowed.
Delete the settings set by the WiFi Manager. Confirm deletion by simultaneously holding pressed the on-board button of the pH-module.
Request method GET
Content type text/html
Response Text containing only one of the following strings:
  • Done
  • Failed
  • Missing
Since version 1.3.240330.
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 on-board button of the pH-module.
Request method GET
Content type text/html
Query string
  • authorization=no - to do not require authorization;
  • authorization=button - to require authorization;
Request example
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' in advance. See setAuthorization. Note that data is POST-ed.
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.
Request body еxample {"slope" : "-58.60" , "asymmetry" : "0.13"}
Request body еxample {"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
Request example
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.


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.

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

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.

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 .


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.


Upload to ESP8266 memory

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.

Is the chip already running this software?

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 current_calibration_data.json

Edit the code before upload

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.

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 as default IP address. The optional display is supported as well. The MQTT support though is available only if STA mode is selected.

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

Connect as station. STA mode.

Set the mode to STA.

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

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

Send data to an MQTT broker

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.


Select your board.

Set a COM-port.

Upload the sketch.

Upload the sketch data.

Finally, how to access the measured data?

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


HL-ESP-server Download
version 1.3.240330
(requires HomeLab_pH library version 1.2+)
SHA256 checksum:

    Changes to version 1.2.230615:
  • WiFI manager visual interface is added.
  • The MQTT protocol support and features are temporarily dropped.

HomeLab_pH library Download
version 1.2.0
SHA256 checksum: