De Firmware

Wat je nodig hebt
Om de DONOFF firmware te kunnen compileren en naar een ESP-01 over te zetten, heb je het volgende nodig:

• De Arduino IDE
• De ESP8266 core extension (2.4.2 of 2.5.0)
• Het ‘ESP8266 Sketch Upload Tool’ geïnstalleerd
• De PUYA patch (voor de ESP8266 core versie 2.4.2)

Veel ESP-01 bordjes die je nu kunt kopen, hebben een flash-chip die problemen geeft bij het lezen van de inhoud van het flash-geheugen (ze hebben een Flash-Chip van het merk PUYA). Om de problemen het hoofd te bieden, is er een tijdelijke patch voor versie 2.4.2 (kijk hier) beschikbaar (waarschijnlijk zit deze patch verwerkt in versie 2.5.0 van de ESP8266 extensie). Voor versie 2.4.2 (en eerder) is het absoluut noodzakelijk dat je deze patch in de tool-chain aanbrengt.

WebSockets – een korte inleiding

Het world wide web is gemaakt met het idee dat een client (een browser bijvoorbeeld) een verzoek doet aan een server en dat de server dit verzoek honoreert met het versturen van een webpagina (request-response model). Het nadeel van deze methodiek is dat de server alleen iets naar een client kan sturen als de client daar specifiek om vraagt. Maar wat nu als een server nieuwe informatie heeft die hij naar de client toe wil sturen? Om dit probleem het hoofd te bieden, zijn verschillende strategieën ontwikkeld waarmee de server gegevens naar de client kan ‘pushen’. Een van de populairste strategieën (buiten AJAX) was ‘long-polling’. Hierbij houden de server en client de HTTP verbinding open tot de server data heeft om naar de client te pushen.

Het probleem van al deze oplossingen is dat ze de overhead van het HTTP protocol in zich hebben. Iedere ‘HTTP request’ verstuurt een berg aan headers en cookies naar de server. En dat wordt al snel een grote berg aan data die over de lijn verstuurd moet worden wat op zijn beurt weer voor vertragingen (latency) zorgt. Als je iets als een browser-based real-time systeem wilt bouwen, wil je juist zo min mogelijk ‘vertraging’ om de boel gesmeerd te laten werken.

Wat het www nodig heeft is een ‘in stand blijvende’, ‘lage vertraging’ verbinding waarmee transacties geïnitieerd door de client en/of de server worden ondersteund! En dat is precies wat WebSockets biedt en de DONOFF firmware maakt intensief gebruik van deze functionaliteit.

Hoe werken WebSockets

WebSockets onderhoudt een verbinding tussen de client en de server die door beide partijen gebruikt kan worden om boodschappen op ieder gewenst moment naar elkaar toe te sturen.
De client zet de WebSocket verbinding op door middel van een proces dat bekend staat als ‘WebSocket handshake’. Het proces begint als de client een normaal HTTP request naar de server stuurt. In dit request zit een zgn. ‘Upgrade header’ waardoor de server weet dat de client een WebSocket verbinding wil opbouwen.
Als de server het WebSocket protocol ondersteunt, gaat hij akkoord met de Upgrade en bevestigt dit aan de client door een Upgrade header terug te sturen.
Nu de handshake over-en-weer overeen gekomen is, wordt de tot dan gebruikte HTTP verbinding vervangen door een WebSocket verbinding over dezelfde onderliggende TCP/IP verbinding. Vanaf nu kunnen beide partijen (client en server) data naar elkaar toesturen. De data wordt via de WebSocket als boodschap (message) verstuurd via één of meerdere pakketjes die de verstuurde data bevatten (de payload).

Hoe de DONOFF firmware werkt

Voordat ik dieper inga op de werking van de DONOFF firmware, ligt ik eerst wat begrippen toe. Wat bedoel ik met:

• Master – dit is de DONOFF die de controle heeft over zijn eigen, local-Device en over alle Slave DONOFF’s
• Slave – dit is een DONOFF die alleen zijn eigen, local-Device, controleert
• Server – dit is de webserver op een DONOFF (een Master of een Slave)
• Client – dit is de browser die verbinding heeft met een DONOFF webserver. Het is de interface tussen de hardware en de gebruiker
• local-Device – dit is het fysieke device dat iedere DONOFF (Master of Slave) bedient

Nadat een DONOFF op het lichtnet wordt aangesloten zal het een webserver starten. Als de webserver een URL zoals:

“http://hostname.local/”

van de client ontvangt zal de server de index.html pagina naar de client sturen.
Dit index.html bestand bevat, naast de html code, ook Javascript code. De Javascript code zorgt ervoor dat er een WebSocket verbinding met de webserver wordt opgebouwd.

Nadat deze verbinding is opgebouwd, stuurt de client de boodschap “getDevInfo” naar de server waarop deze reageert door een boodschap met daarin de hostname van deze DONOFF, wat voor DONOFF dit is (Master of Slave) en welke firmware op de DONOFF draait.
Daarna stuurt de client een boodschap met de vraag om de meest recente versie van de DOM (“updateDOM”). De server stelt nu een DOM samen met daarin zijn local-Device (als het een Master is, van alle andere DONOFFS die hij kent) en stuurt deze terug naar de client.

Vanaf hier is alle communicatie tussen de client en de server ‘event driven’. Als de gebruiker een slider op het scherm verplaatst, zal de client dit merken en een nieuwe slider-waarde naar de server sturen die, op zijn beurt, de intensiteit van zijn local-Device zal aanpassen. Als de gebruiker op de Aan/Uit knop klikt, zal de client de nieuwe status naar de server sturen die vervolgens de noodzakelijke acties uitvoert om aan het verzoek van de gebruiker te voldoen.

Er is echter nog iets dat wordt getriggerd als de status van een device verandert:

• Als de DONOFF een Slave is zal het een HTTPrequest naar de DONOFF Master sturen met de nieuwe status van zijn local-Device. De Master zal deze informatie verwerken en de (Master) server zal deze nieuwe status naar zijn client sturen. Dus, als je de slider op de Slave verplaatst, zal de nieuwe slider positie óók zichtbaar worden op de client die met de Master verbonden is.
• Als de DONOFF een Master is, en het is geen verandering van zijn local-Device, dan zal de Master een HTTPrequest naar de DONOFF Slave sturen met de nieuwe status van het Slave-device die op zijn beurt zijn local-Device zal aanpassen en de (Slave) server zal de nieuwe status naar zijn client sturen die vervolgens de browser zal updaten. Kortom, iedere verandering op de Master client zal ook zichtbaar worden op de Slave client.

Als de Master een HTTPrequest van een Slave ontvangt, die hij nog niet kent, dan zal hij de nieuwe Slave gegevens in zijn device-list opnemen en een nieuwe DOM opbouwen. Vervolgens zal hij een ge-update DOM (met het nieuwe device erin) naar zijn client sturen. Het nieuwe device wordt vervolgens zichtbaar in de browser.
Deze informatie wordt in een HTTPrequest verstuurd:

 IPaddress // unieke identificatie van deze DONOFF Label // zoals in het scherm wordt getoond Type // is dit een D)immer of een S)chakelaar minState // wat is de laagste PWM waarde die ingesteld kan worden maxState // wat is de hoogste PWM waarde die ingesteld kan worden State // wat is de huidige PWM waarde OnOff // is de lamp Aan of Uit heartbeat // wanneer is deze DONOFF voor het laatst gezien?

Periodiek stuurt iedere Slave een HTTPrequest naar de Master om hem te laten weten dat hij nog steeds online is. Iedere keer dat de Master een HTTPrequest ontvangt, zal hij de heartbeat van de Slave resetten. Als de heartbeat waarde een bepaalde grens overschrijdt, zal de Master concluderen dat de Slave niet meer online is en de gegevens van deze Slave uit zijn device-lijst verwijderen, een nieuwe DOM opbouwen en naar zijn client sturen.

Multicast Domain Name System

De DONOFF firmware maakt intensief gebruik van de functionaliteit van het Multicast Domain Name System (mDNS). In kleine (lokale) computernetwerken vertaalt het mDNS-protocol hostnamen naar IP-adressen. Het is een zgn. zero-configuratie service. Dankzij dit protocol is het mogelijk om toegang te krijgen tot een server of ander apparaat door de mDNS-naam (hostname) te gebruiken in plaats van zijn IP-adres. Met andere woorden, als je "DONOFF.local" als URL in je browser intypt, zal mDNS het IP-adres van het DONOFF device opzoeken en de webpagina van de DONOFF Master (of Slave) presenteren.
De DONOFF firmware op de Slave gebruikt dit om het IP-adres van de DONOFF Master te vinden en veranderingen in het IP-adres bij te houden. DONOFF maakt geen gebruik van vaste IP-adressen, dus van tijd tot tijd kan het IP-adres van de DONOFF Master veranderen. Hoewel mDNS in de meeste netwerken "werkt", zijn er enkele (oudere) WiFiRouters en WiFi-extenders die de mDNS-pakketten blokkeren. Als je geen toegang hebt tot de DONOFF door zijn hostname (.local), moet je waarschijnlijk je router en/of extender (s) upgraden of alleen IP-adressen gebruiken.

DONOFF HTML and CSS

Ik ben geen held als het gaat om het ontwerp en de lay-out van webpagina's. Dit is de reden dat de DONOFF-interface vrij eenvoudig is. Ik heb alleen CSS gebruikt die ik begrijp en ik heb geen fancy library's, zoals bootstrap, gebruikt. Omdat de gebruikte html en CSS zo eenvoudig zijn, kun je de interface naar eigen wens aanpassen (en stuur me alsjeblieft screenshots van wat je hebt gemaakt)!