The ESP8266 SDK comes with a very useful set of examples in the directory IoT_Demo. With it I built and operated some useful devices, namely the DHT11 and DHT22 temperature and humidity sensor and the BME280 temperature, humidity, and pressure sensor. This latter device has an i2c interface. The data is sent to my account at iot.espressif.cn where it can be accessed with a browser, or can be accessed using curl commands with json data from any other client. For the latter one can also use a python script to make this easy.
All development was done in Oracle VM Virtualbox on a Win7 machine using the Espressif ubuntu bundle: Linux esp8266-VirtualBox 3.13.0-32-generic #57-Ubuntu SMP Tue Jul 15 03:51:12 UTC 2014 i686 i686 i686 GNU/Linux. Device communication was done with an USB UART with 3.3 volts out and I used the serial console in PUTTY on the Win7 machine.
Hardware
The devices are the esp-12F (ESP8266MOD) mounted to a self-designed PCB that plugs directly into an USB 5 volt wall charger, thus eliminating any dangling power cords. The PCB has a one amp 5 volt to 3.3 volt regulator along with reset button. It also has a pin header that accomodates the UART connection as well as GPIO pins. Sensors mount to a daughter board that plugs into the pin header. Except for the daughter board, the device is enclosed in a 3D printed enclosure with cover that has been modified from a design found at Thingiverse. All of this is seen in the image below.
DHT11 sensor mounted to the daughter board that plugs into the device.
Project Flow
This project was actually a logical series of individual projects where each project built on the previous one. It began with building the IoT_Demo defining the “light” application, except there was no LED light sensor attached initially. This allowed me to work through a variety of issues. Once this was working, the LED daughter board was attached and complete communication with the cloud account was accomplished. Then the project changed with the addition of code and code changes to send DHT11 and DHT22 sensor data to the cloud. Finally, code addition and code changes were incorporated to send BME280 sensor data to the cloud. This sensor, unlike the DHT sensors, connects to the ESP8266 by i2C. This resulted in devices of all three types seen here:
All three IoT devices.
Note that the temperature/humidity devices are tethered to a flex cable so they are not affected by the heating from the ESP8266 device and at the same time can be more easily be placed in the environment that is to be measured. The following descriptions are in order of the project flow.
Building the IoT Demo for LIGHT_DEVICE
As mentioned, getting the project built and communicating with my cloud account at iot.espressif.cn required working through several issues. To accomplish this the “user_light” project was built since I could build and operate the device and add the tri-color LED daughter board later. Sending color commands to the device does not require the sensor to be present. The following is a step-by-step description of getting this project running successfully.
First step is to set in “user_config.h” the #define LIGHT_DEVICE to 1 and make sure that #define ESP_PLATFORM is also set to 1. Lastly set #define ESP_DOMAIN “iot.espressif.cn”. This is the URL where the cloud account exists. (One can also create an account at “iot.espressif.com”. This is a different server.)
Then in “user_light.h” set PRIV_PARAM_START_SEC 0xFC and in “user_esp_platform.h” set ESP_PARAM_START_SEC 0xFD.
This next step fixes one of the issues encountered and usually only needs to be done once. The linker script found at ESP8266_NONOS_SDK/ld/eagle.app.v6.ld will likely have a default value for the length of the application’s binary eagle.irom0text.bin that is too small. To fix this problem set the value indicated in the image: The value with the red box is large enough for the various IoT projects. Note that the value with the blue box is the origin of where eagle.irom0text.bin will be located.
STEP 5: choose spi size and map 0= 512KB( 256KB+ 256KB) 2=1024KB( 512KB+ 512KB) 3=2048KB( 512KB+ 512KB) 4=4096KB( 512KB+ 512KB) 5=2048KB(1024KB+1024KB) 6=4096KB(1024KB+1024KB) 7=4096KB(2048KB+2048KB) not support ,just for compatible with nodeMCU board 8=8192KB(1024KB+1024KB) 9=16384KB(1024KB+1024KB) enter (0/2/3/4/5/6/7/8/9, default 0): 6 (we have 4MB flash size and want 1024KB partitions)
Before building the project and flashing a device, one normally at this point creates the device at the account at iot.espressif.cn and downloads a master key bin file that is flashed to the device. Without it the device cannot be activated at the cloud account, but will still operate in softAP mode and can be sent curl commands directly. How to create an account and create devices at the cloud server can be found on the server itself.
Once “gen_misc.sh” has been run the project specific files are found in the bin/ directory, namely eagle.flash.bin and eagle.irom0text.bin. The flash tool is now used to flash the device. In the following please note the addresses where the various files are to be located in flash. (Also note that in the image the application specific files have been moved out of the VM Virtualbox to a directory called firmware on the Win7 machine where also sit the files blank.bin and esp_init_data_default.bin. The flash tool in installed on the Win7 machine and therefore all files must sit on that machine.)The second issue encountered is that devices can have their flash memory wired either QI0 or DI0. If they are not wired for QI0, then the flash will proceed to a successful conclusion but the device will not boot successfully. Also note that the build and the flash have to be the same. If built as QI0 but the flashtool is DIO, the boot will also fail. So, in gen_misc.sh change STEP 4 accordingly as well as the selection in the flashtool.
The final step is to allow the device to self-activate at the cloud account by sending a curl command to switch the device from softAP mode to station mode along with data for your local WIFI’s SSID and password. Recall that the device already has burned in ROM the URL of the cloud set in 1 above as well as the master key. The following command was sent from an Ubuntu 16.04 machine (note that data is sent in JSON form and the number for “token” is just an arbitrary number):
curl -X POST -H “Content-Type:application/json” -d ‘{“Request”:{“Station”:{“Connect_Station”:{“ssid”:”yourSSID”, “password”:”yourpassword”, “token”:”3214567890123456789012345678901234567123″}}}}’ http://192.168.4.1/config?command=wifi
Once the curl command is received the device will change to station mode, will connect to “yourSSID”, will become connected to the internet, and then will send an “activate” request to the cloud server using the master key as the authorization token. At the cloud the device will show it was activated:After activation the device will always boot up in station mode and connect to the cloud server. At this point everything is working and the only thing that remains is to connect the daughter board with the tri-color LED and begin sending curl commands to control it.
LIGHT_DEVICE Operation
The tri-color LED that was purchased was already mounted on a small PCB with a pin header. As seen in the photo a daughter board was fashioned into which the LED board plugged and in turn plugged into the pin header of the ESP8266 device.
Tri-color LED mounted to daughter board.
Port Pins and Set Up
The port pins for Red Blue Green are PWM driven. The set up for this is depicted completely in the image below. Note that there are four pins driven by the PWM interface but only three are used. On the left note the definitions that are found in “user_light.h”.
Operation and How Light Settings Actually Work
Now operation of the light setting is done via curl commands. But before we begin we have to fix another of those issues that have been mentioned. Initial testing showed that the settings for green were always 0 when the device was monitored with the UART. It was found that in the function user_esp_platform_set_info in “user_esp_platform.c” the parsing of “z” is incorrect since the contents of pdata for “z” do not end with a “,”. Rather “z” is the last data point and the pointer pbuf was changed to:
One other issue was found, and this was a problem with the document 2b-esp8266_sdk_iot_demo_en_v1.3. On page 19 it states the “x” is frequency, range 1 – 500, and “y” (red), “z” (green), and “k” (blue) have a range of 0 – 255. This is not quite right and in fact wrong. The truth is much more complicated. These settings did not get full brightness from the LED. When the device boots the LED comes on much brighter. By monitoring the device during boot the settings are:
These numbers bear no relationship to what is stated in the document. At first this greatly confused me. Where is the frequency, supposedly the value of x? Clearly P and prd refer to period, not frequency. And what is the meaning of the r, g, b values that default to this particular value of 22222? In order to get clear answers to these questions, a series of curl commands that set the light parameters were sent to a device and the red channel was observed on a DSO(digital oscilloscope). The below example sends x=1000 and y=11111.
After series of measurements it was found that x is the period and y is 22.222 times the ON time in microseconds. These settings are independent from each other. Therefore, it cannot be said that they is the duty cycle since that is a percent of the period value. y sets the absolute ON time, so long as the period is long enough. If the period is shortened below the value of ON time set by y, then the ON time becomes fixed as the value of the period. For y to again control then its value has to be accordingly lowered. One other point: y, z, and k values clamp at 22222 even though a larger value may be sent. At the cloud account the larger value is reported but the actual value on the device remains at 22222.
On time setting clamps at 22222
One last point. When the device is connected to the cloud and a client send as curl command interrogating the device parameters, the cloud always reports the values that were last sent to the device. Therefore, when the device boots up anew, it boots to the default values described above and does not report these values to the cloud. So, both client and cloud do not have information of the values of the newly booted device.
DHT11/DHT22 Temperature/Humidity Sensor
To use this sensor a number of changes and additions are made. One of the first things to do is get the necessary source and include files for the sensor here. Put the respective files in the directories driver/ and include/driver/. The uart function is not used.
Changes and Additions
In “user_config.h” change out the light device for the sensor device and humiture sub device.
In the file gpio16.hcomment out#define GPIO_INTERRUPT_ENABLE. Interrupts are not used and enabling them will cause a compiler error due to a bug in the code.
In dht22.c the following replacement must be made – sleepms(250) is not permissible:
//argument is uint16 - not exceed 65
sleepms(63);
sleepms(63);
sleepms(64);
The next and last change is a temporary one and its explanation will clear up some possible confusion. This was another issue found. Initially in user_config.h one should comment out #define SENSOR_DEEP_SLEEP. For the device to wake up from deep sleep, the RST pin must be jumpered to connect to the GPIO16 pin. The jumper from RST to GPIO16 must be added after flashing and activating. Otherwise it will not flash or boot properly. With the jumper in place I found the device would not flash. Also it was unresponsive to the reset button given that the LED did not flash upon RST. It appears that the full code needs to be executing before the behavior is proper. The full code does not execute until after the device activates. Therefore with DEEP_SLEEP commented out the os_timer takes over and the device reconnects and sends data every 1000 milliseconds. So, after debugging the code and activating the device at the cloud successfully, one adds back #define SENSOR_DEEP_SLEEP, rebuilds the code, flashes the device, and then adds the jumper. The device will now operate where it sleeps, wakes up, reconnects, and sends data every 30 seconds. This is a desireable mode of operation because the device uses little energy when sleeping. This is a possible mode for battery operation.
Activation and Operation
At the account at iot.espressif.cn create the device, download the master key bin file, flash it to 0xfe000, and then from any client send the curl command described above for the light device in step 8.
Two units were commissioned, one with DHT11 sensor and the other with the DHT22 sensor. The main apparent difference between the two is the latter has another decimal point of precision. Here is shown the DHT22 active at the cloud:
Temperture and Humidity Sensor
The BME280 Temperature, Humidity, and Pressure Sensor
This sensor is made by Bosch and information about it is found here. To get the drivers that were used in this project download them from here. To begin remove the drivers for the DHT11 sensor from the driver/ directory and copy to the directory only the two files shown, leaving the others as is. The directory should appear as shown:
One last item. The file i2c_master.h has been changed a bit in that GPIO13 is defined as the SDA line and GPIO14 is defined as the SDL line. Here it is in its entirety:
Changes and Addition to Switch to the BME280 Sensor
This is similar to the DHT11/22 sensors in that most of the changes are in user_esp_platform.c. To begin, in esp_platform_init(void) make the following changes:
Lastly, comment out #define SENSOR_DEEP_SLEEP. Instead the timer in user_esp_platform_recon_cb will define the timing of the reconnect cycle with the cloud. Therefore, the device can be activated normally without the issue of connecting RST to GPIO16 as with the DHT11/22 sensors.
Build, Activate, and Operate the BME280
After building and flashing, the device can be created and activated at the cloud account like the devices above. Here is shown the device sending temperature, humidity, and atmospheric pressure data approximately every 6 seconds:
Testing of BME280 and DHT22 Sensors
It is straightforward to compare the temperature and humidity values of these sensors to each other. However, how can one get an idea of their humidity accuracy? The answer is easy. Put them in a sealed container with a saturated solution of common table salt. For this testing there were one DHT22 sensor, one DHT22 sensor, and three BME280 sensors.
Saturated Salt Solutions for Humidity Testing
One can easily find on the web tables for the equilibrium values of humidity versus temperature for a variety of common saturated salt solutions. When a salt solution that is saturated is placed in a sealed container the humidity of the air space above the solution equilibrates to a particular value less than 100 % RH. Here is a quote from an Omega Engineering brochure:
Saturated Salt Solutions A very convenient method to calibrate humidity sensors is the use of saturated salt solutions. At any temperature, the concentration of a saturated solution is fixed and does not have to be determined. By providing excess solute, the solution will remain saturated even in the presence of modest moisture sources and sinks. When the solute is a solid in the pure phase, it is easy to determine that there is saturation.
Here is the set up used. Note that a tight seal is required and one knows the salt solution is saturated when it becomes slushy with a lot of salt that no longer dissolves. One should choose a container and salt bath size so that the air space is not so large that it takes quite long before equilibrium is reached after the lid is put on.
Saturated salt chamber with NaCl
Two salts were used. Common table salt and pharmaceutical grade magnesium chloride. In the table one can see the relative humidity is quite constant around room temperature.
Temperature (C)
NaCl (%RH)
MgCl2 (%RH)
15
75.61 ± 0.18
33.30 ± 0.21
20
75.47 ± 0.14
33.07 ± 0.18
25
75.29 ± 0.12
32.78 ± 0.16
Results
Before doing the humidity testing it was first determined that for the BME280 there were some self-heating effects caused by the very short standby time of 0.5 milliseconds between measurements within the device. This value is set by the value BME280_TSB_05 in esp_platform_init(void) and was changed to BME280_TSB_1000 , one second. This had the effect of increasing the RH reading 1.5 to 2.0 % RH and slightly reducing the temperature reading by about 0.5 C.
This table contains all of the results.
Results
It can be seen that all sensors agree reasonably well with each other on temperature. Much less so on humidity. Any table salt must be at least 97.5 % pure, so it seems that salt purity may not explain the variation in the numbers in this column. Also, only two devices report the forecasted 75 % RH. Regarding the magnesium chloride being pharmaceutical grade suggests a high purity material, but the supplier did not mark the purity on the product. So, the three devices all reported a result a little above the forecasted 33 % RH. One last comment worth making is that one can test 100 % RH by not adding any salt at all. However, the sensors become wet and do not readily recover, particularly the DHT sensors. This topic is not covered in this post.
Conclusions
Three types of IoT devices were developed using the ESP8266 and the SDK provided by Espressif. Along the way in this post various issues that were encountered were addressed as well as the apparent mystery regarding how the tri-colored LED device is actually controlled. The two types of temperature/humidity devices were compared and humidity accuracy was tested using two different saturated salt baths. The results suggest neither device type is very accurate measuring humidity.
