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•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,
e.g. http://192.168.1.67

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

Calibration

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

Info

There is some information available about the pH-board, ESP module, calibration data, etc. View it by clicking this button.

Settings

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.

Messages

Occasionally the software sends some useful messages and warnings to the user. This button will conveniently show or hide them.

MQTT settings

This button is active only if MQTT connections are enabled in the code prior to 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 this is only possible if 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:
http://192.168.1.67/getMeasuredData
where 192.168.1.67 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.

deleteCalibrationData
Delete the calibration data.
Request method GET
Content type text/html
Response A string:
  • ok, deleted.
  • Failed.
  • Failed, missing file.
  • Failed: write not allowed.
getADCError
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;
getAuthorization
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;
getBoardData
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":{}}
getButton
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;
getCalibrationData
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 {}
getEPRError
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;
getMeasuredData
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"}
getPH
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
getSoftwareVersion
Get the software version.
Request method GET
Content type text/html
Response A string.
Example 1.0.220310
getTemperature
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
getTSensorData
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":{}}
getVoltage
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
setAuthorization
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
  • authorization=no - to do not require authorization;
  • authorization=button - to require authorization;
Request example http://192.168.1.67/setAuthorization?authorization=button
Response A string:
  • ok
  • Failed.
  • Failed writing.
  • Failed: hold the on-board button pressed.
  • Failed: unknown auth.
  • Failed: no parameter.
setCalibrationData
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."}
setLedOFF
Set OFF the on-board LED.
Request method GET
Content type text/html
Response ok
setLedON
Set ON the on-board LED.
Request method GET
Content type text/html
Response ok
setTSensorResolution
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 http://192.168.1.67/setTSensorResolution?resolution=11
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
ESPAsyncTCP
ESPAsyncWebServer
ArduinoJson
SPIFFS filesystem uploader
HomeLab_pH, ver. 1.1+

And also, if a display is to be used:
Adafruit_GFX
Adafruit_SSD1306

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
https://arduino.esp8266.com/stable/package_esp8266com_index.json
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.

 

Downloads

HL-ESP-server Download
version 1.2.220730
SHA256 checksum:
a8a81fcd927d52346578faa3f8cc8cedf8bc8296d8cece44ee377321ad45048f

    Changes to version 1.0.220420:
  • New: MQTT protocol is supported. Broker address, port number and other settings can be set also through the user web interface.
  • New: ThingSpeak dashboard is supported as a remote data plotter.
  • New: The system may be started in AP (access point) mode to work as a stand alone pH meter.

HomeLab_pH library Download
version 1.1.0
SHA256 checksum:
245ecd52c80347a3be1ded90ccb4b522326539cdfba7c9d2d2a7303f1e9ee552

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

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

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.

Upload

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.