The firmware

What you need
To compile and transfer the DONOFF firmware to an ESP-01 you will need:

• The Arduino IDE
• The ESP8266 core extension (2.4.2 or 2.5.0)
• Installed the 'ESP8266 Sketch Upload Tool'
• The PUYA patch (for the ESP8266 core version 2.4.2)

Many ESP-01 boards that you can buy now have a flash chip that causes problems reading the contents of the flash memory (they have a PUYA brand Flash Chip). To address the issues, there is a temporary patch for version 2.4.2 (look here) available (probably this patch is included in version 2.5.0 of the ESP8266 extension). For version 2.4.2 (and earlier) it is imperative that you apply this patch in the tool chain.

WebSockets – a brief introduction

The world wide web was created with the idea that a client (a browser, for example) makes a request to a server and that the server honors this request by sending a web page (request-response model). The disadvantage of this method is that the server can only send something to a client if the client specifically requests it. But what if a server has new information that it wants to send to the client? To cope with this problem, several strategies have been developed that allow the server to "push" data to the client. One of the most popular strategies (outside of AJAX) was long-polling. The server and client keep the HTTP connection open until the server has data to push to the client.

The problem with all these solutions is that they involve the overhead of the HTTP protocol. Every 'HTTP request' sends a mountain of headers and cookies to the server. And that quickly becomes a large mountain of data that has to be sent over the line, which in turn causes delays (latency). If you want to build something like a browser-based REAL -time system, you want as little 'lag' as possible to keep things running smoothly.

What the www needs is a 'persistent', 'low delay' connection that supports client and/or server initiated transactions! And that is exactly what WebSockets offers and the DONOFF firmware makes extensive use of this functionality.

How do WebSockets work

WebSockets maintains a connection between the client and the server that can be used by both parties to send messages to each other at any time.
The client establishes the WebSocket connection through a process known as 'WebSocket handshake'. The process starts when the client sends a normal HTTP request to the server. This request contains a so-called 'Upgrade header' through which the server knows that the client wants to establish a WebSocket connection.
If the server supports the WebSocket protocol, it agrees to the Upgrade and confirms it to the client by returning an Upgrade header.
Now that the handshake has been agreed upon, the HTTP connection used until then is replaced by a WebSocket connection over the same underlying TCP/IP connection. From now on, both parties (client and server) can send data to each other. The data is sent via the WebSocket as a message via one or more packets containing the sent data (the payload).

How the DONOFF firmware works

Before I go deeper into the operation of the DONOFF firmware, I first explain some concepts. What do I mean by:

• Master – this is the DONOFF that has control over its own local-Device and over all Slave DONOFFs
• Slave – this is a DONOFF that controls only its own local-Device
• Server – this is the web server on a DONOFF (either a Master or a Slave)
• Client – this is the browser that connects to a DONOFF web server. It is the interface between the hardware and the user
• local-Device – this is the physical device that each DONOFF (Master or Slave) serves

After a DONOFF is connected to the mains it will start a web server. If the web server has a URL like:

“http://hostname.local/”

from the client, the server will send the index.html page to the client.
This index.html file contains, in addition to the html code, also Javascript code. The Javascript code ensures that a WebSocket connection is established with the web server.

After this connection has been established, the client sends the message “getDevInfo” to the server to which it responds by a message containing the hostname of this DONOFF, what type of DONOFF this is (Master or Slave) and which firmware is running on the DONOFF.
The client then sends a message asking for the most recent version of the DOM (“updateDOM”). The server now builds a DOM containing its local-Device (if it's a Master, of all the other DONOFFS it knows of) and sends it back to the client.

From here on, all communication between the client and server is event driven. If the user moves a slider on the screen, the client will notice this and send a new slider value to the server which, in turn, will adjust the intensity of its local-Device. When the user clicks the On/Off button, the client will send the new status to the server, which will then take the necessary actions to fulfill the user's request.

However, there is something else that is triggered when a device's state changes:

• If the DONOFF is a Slave it will send an HTTP request to the DONOFF Master with the new status of its local-Device. The Master will process this information and the (Master) server will send this new status to its client. So, if you move the slider on the Slave, the new slider position will also be visible on the client connected to the Master.
• If the DONOFF is a Master, and it is not a change of its local-Device, then the Master will send an HTTP request to the DONOFF Slave with the new status of the Slave-device, which in turn will change its local-Device and (Slave) server will send the new status to its client which will then update the browser. In short, every change on the Master client will also be visible on the Slave client.

If the Master receives an HTTP request from a Slave that it does not yet know, it will include the new Slave data in its device list and build a new DOM. It will then send an updated DOM (with the new device in it) to its client. The new device will then be visible in the browser.
This information is sent in an HTTP request:

IPaddress // unique identification of this DONOFF Label // as shown in the screen Type // is this a D)immer or a S)switch minState // what is the lowest PWM value that can be set maxState // what is the highest PWM value that can be set State // what is the current PWM value OnOff // is the lamp On or Off heartbeat // when was this DONOFF last seen?

Periodically, each Slave sends an HTTP request to the Master to let it know that it is still online. Every time the Master receives an HTTP request, it will reset the Slave's heartbeat. If the heartbeat value exceeds a certain limit, the Master will conclude that the Slave is no longer online and remove this Slave's data from its device list, build a new DOM and send it to its client.

Multicast Domain Name System

The DONOFF firmware makes extensive use of the functionality of the Multicast Domain Name System (mDNS). In small (local) computer networks, the mDNS protocol translates host names into IP addresses. It is a so-called zero-configuration service. Thanks to this protocol, it is possible to access a server or other device by using its mDNS name (hostname) instead of its IP address. In other words, if you type "DONOFF.local" as the URL in your browser, mDNS will look up the IP address of the DONOFF device and present the web page of the DONOFF Master (or Slave).
The DONOFF firmware on the Slave uses this to find the IP address of the DONOFF Master and track changes in the IP address. DONOFF does not use fixed IP addresses, so from time to time the IP address of the DONOFF Master may change. Although mDNS "works" in most networks, there are some (older) WiFiRouters and WiFi extenders that block the mDNS packets. If you can't access the DONOFF by its hostname (.local), you probably need to upgrade your router and/or extender(s) or use IP addresses only.

DONOFF HTML and CSS

I'm not a hero when it comes to web page design and layout. This is the reason that the DONOFF interface is quite simple. I've only used CSS I understand and I haven't used any fancy libraries like bootstrap. Since the html and css used are so simple, you can customize the interface to your liking (and please send me screenshots of what you made)!