This article describes how to build devices based on ESP8266 Wi-Fi SoC using the DeviceHive firmware with the embedded web interface.
We just updated our firmware for ESP8266 to version 0.5 and this version has plenty of new features to use in local networks. If you are not aware, the DeviceHive firmware for ESP8266 connects your device to a cloud using a DeviceHive server. So the firmware allows controlling hardware connected to the chip’s pins via cloud services. With the latest version it’s possible to build a completely local solution or combine it with cloud connectivity.
The previous article about flashing and configuring the chip is here.
The latest binary release is available here.
That is an open source project under MIT license. The full source code can be found here.
So what’s new?
Local RESTful API
Each chip has a tiny HTTP server with the RESTful API endpoint. Its commands and the cloud services are the same. The full list of the commands can be found here.
For example, there is the ‘gpio/read’ command to get the state of the GPIO pins. And it doesn’t require connecting the chip to the cloud anymore. Simply use the local RESTful API http://device-id.local/api/gpio/read. The response to this request will be a JSON string containing all pin states.
If the chip doesn’t have an AccessKey specified, it is possible to get one using a regular browser:
Or using curl.
curl -i -X POST \
-H "Authorization: Bearer YourAccessKeyHere=" \
http://esp-demo.local/api/gpio/read
If the AccessKey is specified, it should be passed in the HTTP header. This key is used for authentication purposes both by the local RESTful API and a cloud server. The key is simply a password in a string format for the API.
The method can be either GET or POST — the command syntax remains the same. The command should be passed as a part of the URL request. The parameters are specified in the request body in JSON format.
mDNS
You may have noticed that in the previous example the esp-demo.local domain was used. The chip supports the Multicast Domain Name System, and all devices supporting mDNS in the local area network can resolve the chip’s IP address. Moreover it’s possible to discover all ESP8266 devices on the local network. And there is no need to use the DNS service.
mDNS works the same way as unicast DNS works, but requests are sent to a special multicast address. All devices supporting this protocol listen to this address and answer to requests. The domain name is equal to the DeviceId, which is configured as one of the chip’s parameters. The full domain name looks like DeviceId.local.
RFC6763 describes how to discover devices using mDNS. And it can be used to discover chips with our firmware.
There are plenty of libraries and utilities that support mDNS. For example, the DeviceId esp-demo chip can be discovered using the Avahi Discovery utility:
Some modern operation systems can discover mDNS domain names out-of-the box using browsers and other applications.
Popular Sensor Support
Usually a sensors’ protocol should be deployed to connect the sensor to the chip. Now the DeviceHive firmware supports a number of sensors out-of-the-box.
For example, the reading procedure for the DS18B20 temperature sensor is as follows:
- Initializing the sensor’s measurement procedure.
- Waiting for the sensor to measure the temperature.
- Reading the result after a short pause.
And this is quite a simple procedure.
It’s possible to read the temperature by simply sending the ‘devices/ds18b20/read’ command. The answer will provided in JSON format:
‘{“temperature”:24.5000}’.
The full list of supported sensors: https://github.com/devicehive/esp8266-firmware/blob/master/DeviceHiveESP8266.md
Here is a sample output from an MPU-6050 sensor (accelerometer, gyroscope and the onboard temperature sensor):
Local Web Server
Since we have the RESTful API based on the chip’s HTTP server, why don’t we host web pages on the same server?
Right after flashing the firmware, open http://deviceid.local/ in a web browser. There will be the chip’s web interface. By default it shows the following information:
- The short manual page;
- Tools for working with the RESTful API (the example page for sending commands and a base64 converter);
- A few examples using the RESTful API (you’ll be able to see the source code page in a browser);
- A simple (just for now) web page editor. The editor allows changing the chip’s main page using a browser.
The page size is limited to 64KiB.
Similar to the embedded samples, web pages can be uploaded to the chip. JavaScript is used to send commands to the chip and get results that can be displayed on a page. In addition, the same page may send requests to all chips across the local network.
Getting Things Done
And finally, let’s connect a DS18B20 temperature sensor and create a web interface for it. The sensor should be powered from the GND and 3V3 pins and connected to any GPIO pin. GPIO2 is located near the power pins, so let’s use it. The wire connection will look like this:
The photo shows the ESP8266 board which is popular with developers. These boards contain a power supply, a Micro-USB connector, and a USB-TTL adapter. Looks handy.
Using a board like this makes the flashing procedure much easier. Just connect a flasher, and a flashing utility will do the rest. Remarkable that these boards can be purchased from some marketplaces for $3-$4 with free worldwide shipping.
Now, let’s come back to the web interface. The chip already has an example page for the DS18B20 sensor. It is located here: http://deviceid.local/ds18b20.html. Let’s open it, enter the AccessKey if needed. And we can observe the real time temperature on the page.
The source code can be viewed directly in the browser. If you don’t like the page design, or you would like to add something (e.g. several sensor outputs), then you will have to create and upload a custom web page as described above.
For example, let’s create a simple web page that will control a relay.
<html>
<head>
<script type="text/javascript">
function send(onOff) {
localStorage['accesskey'] = document.getElementById('accesskey').value;
var xmlhttp = new XMLHttpRequest();
xmlhttp.open('POST', "http://" + window.location.hostname + '/api/gpio/write', true);
xmlhttp.setRequestHeader("Authorization", "Bearer " + localStorage['accesskey']);
xmlhttp.onreadystatechange = function() {
if(xmlhttp.readyState == 4){
if(xmlhttp.status < 200 || xmlhttp.status > 299) {
alert('ERROR: Command returned ' + xmlhttp.status + ' ' + xmlhttp.responseText, true);
}
}
}
var json = {}
json["5"] = onOff ? 1 : 0;
xmlhttp.send(JSON.stringify(json));
}
function init() {
document.getElementById('accesskey').value = localStorage['accesskey'];
}
</script>
</head>
<body onload="init()">
<label>AccesKey: </label><input type="password" id="accesskey"><br><br>
<input type="button" value="On" onclick="send(true);"> <input type="button" value="Off" onclick="send(false);">
</body>
</html>
This source code stores the AccessKey in local browser storage to avoid the need to enter it each time. XMLHttpRequest() is called on a button click, and it sends a request via the RESTful API.
Now upload the page to the chip.
An SSR-40DA solid state relay will trigger an electric motor powered by AC 220V. This relay can handle up to a 40 Ampere load, so it can be connected to something else, the motor here is just for fun. See the video below to find out how to connect the relay to the ESP8266 chip and how it will work.
Thank you very much for your attention. Stay tuned!