Software for ESP8266

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:

A web server presents a browser interface to view the measured data and calibrate the module.
All the data may also be accessed in portions via separate HTTP calls.
pH, temperature and sensor voltage may optionally be shown on an eventually wired small display.
Use as stand-alone pH meter by starting the ESP module in AP mode (requires no router connection).
Visual interface letting the user set the WiFi credentials and server access.

To prepare the system follow the instructions given in the Prerequisites and Upload sections.

A summary of what hardware is needed:

a Homelab pH-module, a temperature sensor and an optionally connected HomeLab isolator module,
an ESP8266 controller and some wires to connect it to the module (see the wiring),
a suitable USB cable to upload the software to the controller,
a device with a browser to show the visual interface,
optionally, a small SSD1306 128x64 display to only visualize the data,
a pH probe, and
a power source.

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
http://<ESP-module-LAN-address>/wifimanager.html

The WiFi settings are deleted by the following web command (see more details):
http://<ESP-module-LAN-address>/deleteWiFiSettings

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:

in the Arduino IDE Serial Monitor window - start the monitor and reset the module,
if available, a display shows the address on system reset,
in the code itself if, before uploading the sketch in the microcontroller memory, the user chose to have a static IP-address (see the Upload section),
check the router web interface and,
finally, a LAN scanner is always helpful.

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

Calibration

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.

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

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.

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.

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

deleteWiFiSettings

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.

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

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

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
ESPAsyncTCP
ESPAsyncWebServer
ArduinoJson
SPIFFS filesystem uploader
HomeLab_pH, ver. 1.2+

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

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

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

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.

Upload

Select your board.

Set a COM-port.

Upload the sketch.

Upload the sketch data.

Finally, how to access the measured data?

to view it by the visual interface, point your browser to the local_IP address set (see above),
get separate chunks of data by sending specific http requests in your browser,
view it at the Serial monitor of the Arduino IDE at baud rate of 115200,
view it on a connected small display.

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

Downloads

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

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:
be6a153d3d551112e0da84e5fd32ebd13c3a4b933c92c77730c9acf156edaa3b