HTTP-Protocol

Uit Nodo Wiki
Ga naar: navigatie, zoeken

Toepassing

De Nodo communiceert met de WebApp via het HTTP-protocol. Dit protocol is zeer flexibel en eenvoudig te koppelen aan WebServers met eigen web-applicaties. Deze pagina geeft een beschrijving van de wijze waarop de Nodo Commando verstuurt en ontvangt via HTTP. Deze informatie is van toepassing voor gebruikers die geen gebruik van de WebApp willen maken en een eigen toepassing willen ontwikkelen die kan communiceren met de Nodo.

We gaan er van uit dat u reeds kennis heeft van het HTTP protocol. Een korte uitleg kun je hier vinden: [1]

Uitwisseling van gegevens en basis instellingen

De HTTP bericht dat met de Nodo wordt uitgewisseld bestaat uit drie delen:

  1. Een HTTP-Request regel
  2. Header-lines
  3. Body-text

De HTTP-Request regel bevat informatie over events die de Nodo moet ontvangen of verzendt. De Header-lines bevatten meet statische informatie en worden niet gebruikt om informatie uit te wisselen richting Nodo. De Nodo verzendt echter wel Header regels die u mogelijk kunt gebruiken. De Body-text wordt gebruikt in bijzondere gevallen zoals het verzenden/ontvangen van een file.

Om de communicatie tussen de Nodo en een ander apparaat/toepassing tot stand te brengen, worden de volgende gegevens tussen Nodo en Host uitgewisseld:

  • Poort: Communicatie verloopt altijd via een poort. Zowel voor binnenkomende als voor uitgaande communicatie moet de poort worden ingesteld. Zie hiervoor de commando's PortInput en PortOutput.
  • Host: De Nodo moet weten waar events naar toe moeten worden gestuurd. Dit is de Server die communiceert met de Nodo. Instellen van de Host vindt plaats met het commando HTTPHost. Voor ontvangen van Events is deze instelling niet relevant.
  • IP-Protocol: De Nodo moet weten dat Events niet alleen naar RF, IR of een TelNet sessie worden gestuurd, maar ook volgens het HTTP-protocol via TCP-IP naar een Host. De Nodo kent twee mogelijkheden voor HTTP communicatie: een beveiligde mode en een onbeveiligde mode. Voor het inschakelen van HTTP communicatie en selecteren van de beveiligings mode, zie hiervoor het commando OutputIP.
  • Password: Het wachtwoord wordt niet verzonden, maar is nodig om in de beveiligde modus een sleutel te genereren die wordt gebruikt om events uit te wisselen tussen Nodo en de Host.
  • ID: Dit is een unieke identificatie die kan worden toegekend aan de Nodo. Als de Nodo events verstuurd wordt dit ID meeverstuurd zodat de ontvangende host weet welke Nodo het ontvangen event verzonden heeft. Instellen ven het ID vindt plaats met het commando ID.
  • Key: Dit is een veiligheidssleutel die er voor zorgt dat onbevoegden geen events naar de Nodo of de WebApp kunnen versturen. De Key wordt alleen in de beveiligde modus gebruikt.
  • Cookie: Om veiligheidsredenen is de beveiligings Key is een steeds opnieuw gegenereerde sleutel. Deze Key wordt berekend op basis het ingestelde wachtwoord en de steeds wisselende Cookies die de Nodo periodiek naar de Host stuurt.
  • IP Adres Nodo: Om een event naar de Nodo te versturen moet u het IP adres van uw Nodo weten. Tijdens het opstarten geeft de Nodo in haar welkomsttekt het lokale IP adres weer. Wilt uw uw Nodo vanaf internet bedienen dan is het IP adres van je internetaansluiting nodig. Deze is op te vragen met [WatIsMyIP.com]

Voorbeeld: Verzenden van een event naar de Nodo

Voor versturen van events naar de Nodo kunt u gebruik maken van een standaard browser, maar er zijn vele andere mogelijkheden. Zorg er voor dat de Nodo

Neem als basis een schone geresette Nodo (Reset). We gaan in dit voorbeeld uit van een onbeveiligde verbinding. Wees ervan bewust dat als de Nodo in de onbeveiligde mode staat, alle events, commando's en scripts open staan voor de buitenwereld! We stellen de Nodo in op onbeveiligde communicatie met de volgende regel:

Output HTTP,Off

Stel dat het IP adres van de Nodo 192.168.1.110 is, dan kan een event naar de Nodo worden verzonden door in een browser in de adresregel het volgende in te typen:

http://192.168.1.110:8080/?event=sound

Merk op dat het deel 8080 verwijst naar de poort waar de Nodo continue naar luistert. Geeft u niet de juiste poort op, dan ontvangt de Nodo niets.

Stel u wilt dat de Nodo een UserEvent 123,1 verstuurt, dan kan dit als volgt:

http://192.168.1.110:8080/?event=SendUserEvent%20123,1

Let op: In HTTP-requests moeten alle spaties worden vervangen door %20..

Beveiligde modus

De beveiligde mode werkt aanzienlijk ingewikkelder. Dit kan niet vanuit een standaard browser, maar hiervoor zult u in uw toepassing zelf een script voor moeten maken. Om in de beveiligde mode een Event naar de Nodo te sturen, moet aan de server zijde die verbinding maakt met de Nodo het volgende worden gedaan:

  1. Periodiek (ong. 1x per minuut) verstuurt de Nodo een cookie naar de server. Dit is een random hexadecimaal getal. Bewaar de laatste cookie.
  2. Zorg er voor dat het wachtwoord van de Nodo bekend is aan de server zijde. Let op dat dit een belangrijk veiligheids onderdeel is.
  3. Maak een string met de volgende inhoud "<cookie>:<password>", waarbij ,<cookie> en <password> de inhoud van de resp. variabelen zijn waar deze gegevens in zijn opgeslagen.
  4. Bereken de key. Dit is een MD5-Hash op basis van de hierboven berekende string. Een MD5-Hash is een sleutel van 32 tekens.
  5. Stel het HTTP-request samen en verzend deze naar het juiste adres en poort van de Nodo.

Een HTTP-Request kan er dan als volgt uit zien:

GET /?event=UserEvent%201&key=172077e45f97c38310a153304aba795e HTTP/1.1

Van Nodo naar server werkt in principe op dezelfde wijze, echter de server dient GEEN cookies te verzenden. Om veiligheidsredenen ligt dit initiatief altijd bij de Nodo. In een HTTP-request afkomstig van de Nodo zijn nog extra gegevens opgenomen zoals het ID en Unitnummer van de Nodo. Voorbeeld van een HTTP-request zoals door de Nodo verzonden:

GET /webapp/nodo.php?id=DFAJC31L&unit=1&key=172077e45f97c38310a153304aba795e&event=UserEvent%201,0 HTTP/1.1

De Body-text die de Nodo verzendt bevat ook een aantal bruikbare gegevens zoals datum, tijd en Nodo build versie.

Files op SDCard van de Nodo benaderen

Het is mogelijk om de inhoud van een file op de SDCard van de Nodo op te halen als body-text. Dit kan met: http://192.168.1.110:8080/?file=myfile Het is eveneens mogelijk om een file naar de SDCard van de Nodo te schrijven door de tag 'file=' op te nemen in het HTTP-request dat naar de Nodo wordt verstuurd. De bodytext in het HTML-bericht wordt dan opgeslagen in de root directory van de SDCard. De extentie van de files is altijd .DAT. Deze extentie wordt toegevoegd door de Nodo. Bestanden die groot zijn kunnen bij het ophalen erg veel tijd in beslag nemen. Gedurende deze tijd is de Nodo niet beschikbaar voor verwerken of ontvangen van events.

Enkele opmerkingen

  • Het is niet mogelijk om zowel de WebApp te gebruiken alsmede zelf HTTP events direct naar de Nodo te versturen. De WebApp maakt immers gebruik van de beveiligde modus met veiligheidssleutels.
  • De veiligheid van uw toepassing wordt vergroot als in de Nodo wordt ingesteld dat HTTP-events uitsluitend van één opgegeven server mag komen. Dit kan worden ingesteld met het commando [ClientIP].

Zie ook