Geplaatst op door Dennis Bor

ESP8266 firmware: HTML requests

Laatst bijgewerkt op 26 maart 2019.

Dit document beschrijft de momenteel beschikbare HTML requests en de daarbij behorende waarden:

/findSlave

Methode: GET

Zoekt naar het eerst beschikbare (en compatibel) apparaat op de I2C bus en toont status, hardware-adres, aantal sensoren en aantal schakelbare stekkers of een foutstatus. De ESP fungeert als master en het andere apparaat (bijvoorbeeld een Arduino Uno) als slave.

Uitvoer:

  • status: “ok” indien gevonden, anders “no”
  • address: het hardware adres van het gevonden I2C-apparaat, waarbij waarden tussen 0-127 mogelijk zijn. Wordt alleen getoond bij status “ok”.
  • sensors: het aantal sensoren van het gevonden I2C-apparaat, waarbij waarden tussen 0 en 31 ondersteund worden. Wordt alleen getoond bij status “ok”.
  • outlets: het aantal schakelbare stekkers van het gevonden I2C-apparaat, waarbij waarden tussen 0 en 31 ondersteund worden. Wordt alleen getoond bij status “ok”.
{
    "status":"ok",
    "address":16,
    "sensors":1,
    "outlets":0
}

/getAdmin

Methode: GET

Toont de gebruikersnaam van de webinterface. Het wachtwoord wordt uiteraard om veiligheidsredenen niet getoond.

Uitvoer:

  • username: gebruikersnaam van de webinterface, standaard “admin”.
{
    "username":"admin"
}

/setAP

Methode: POST

Stelt SSID en passphrase van het eigen access point in.

Het SSID wordt gecontroleerd op juistheid:

  • minimaal 2 en maximaal 32 karakters lang.
  • geen spaties aan begin of eind.
  • toegestane ASCII karakters zijn 32 t/m 126, met uitzondering van 34, 36, 43, 63, 91, 92 en 93 (“$+?[\]).
  • het eerste karakter mag niet gelijk zijn aan ASCII codes 33, 35 en 59 (!#;).

De passphrase wordt gecontroleerd op juistheid:

  • minimaal 8 en maximaal 63 karakters lang.
  • toegestane ASCII karakters zijn 32 t/m 126.
  • een lege passphrase wordt geaccepteerd en resulteert in een open netwerk.

Vereiste parameters:

  • ap_ssid: het gewenste SSID voor het access point.

Optionele parameters:

  • ap_passphrase: de gewenste passphrase voor het access point.

Uitvoer:

  • status: ‘ok’ indien de parameters geaccepteerd worden, anders ‘no’.
{
    "status":"ok"
}

/getAP

Methode: GET

Toont de SSID van het eigen access point.
Het wachtwoord wordt uiteraard om veiligheidsredenen niet getoond.

Uitvoer:

  • ap_ssid: SSID van eigen access point
{
    "ap_ssid":"DennisBor-IoT"
}

/getAPI

Methode: GET

Toont informatie over de verbinding met de DennisBor IoT API.

Uitvoer:

  • api_status: Verbindingsstatus met API (0 = Niet verbonden, 1 = Verbonden).
  • api_url: URL naar de API, standaard ‘api.dennisbor.com’.
  • api_key: sleutel waarmee API gegevensuitgewisseling tot stand gebracht kan worden.
  • api_secret: geheime code waarmee API gegevens opgeslagen kunnen worden op de server.
  • sha1_fingerprint: SHA1 sleutel van de API server.
  • sha1_bypass: er kan een bypass ingesteld worden om SHA1 verificatie over te slaan. (0 = veilig, 1 = bypass).
{
    "api_status": 1,
    "api_url": "api.dennisbor.com",
    "api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "api_secret": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
    "sha1_fingerprint": "00 11 22 33 44 55 66 77 88 
        99 AA BB CC DD EE FF 00 11 22 33",
    "sha1_bypass": 0 
}

/setAPI

Methode: POST

Slaat de opgegeven instellingen voor verbinding met de DennisBor IoT API op. Er vindt controle plaats op lengte van API-key, API-secret en SHA1-fingerprint. Er vindt controle plaats op juistheid van het formaat van de SHA1-fingerprint. Indien er een fout optreedt, dan krijgt de uitvoer een extra parameter “errno”.

Vereiste parameters:

  • api_url: URL van de API server.
  • api_key: sleutel waarmee API gegevensuitgewisseling tot stand gebracht kan worden.
  • api_secret: geheime code waarmee API gegevens opgeslagen kunnen worden op de server.
  • sha1_bypass: er kan een bypass ingesteld worden om SHA1 verificatie over te slaan. (0 = veilig, 1 = bypass).

Optionele parameters:

  • sha1_fingerprint: SHA1 sleutel van de API server. Deze parameter is niet verplicht omdat er een bypass ingesteld kan worden.

Uitvoer:

  • status: ‘ok’ indien instellingen geaccepteerd worden, anders ‘no’. Let op dat, ook al worden instellingen geaccepteerd, dit niet wil zeggen dat er ook een verbinding tot stand gebracht kan worden. De verbindingsstatus kan opgevraagd worden met /getAPI. Indien status ‘no’, dan krijgt de uitvoer een extra parameter ‘errno’ met als waarde een foutcode.
{
    "status": "ok"
}

of

{
    "status": "no",
    "errno": 5
}

Mogelijke foutcodes:

  • 1: Incomplete call. Er ontbreken verplichte parameters.
  • 2: Lengte API key onjuist. Lengte moet 32 karakters zijn.
  • 3: Lengte API secret onjuist. Lengte moet 32 karakters zijn.
  • 4: Lengte SHA1 fingerprint onjuist. De fingerprint kan opgegeven worden als string met of zonder scheidingstekens, waarbij als scheidingsteken een spatie of dubbele punt gebruikt mag worden. De lengte met scheidingstekens moet 59 karakters zijn of zonder scheidingstekens 40 karakters.
  • 5: SHA1 fingerprint bevat ongeldige tekens. De fingerprint mag alleen bestaan uit hexadecimale tekens (0-F).
  • 6: Onjuiste API URL of SHA1 fingerprint komt niet overeen met de fingerprint van de server.

/setWifi

Methode: POST

Probeert te verbinden met het opgegeven access point en stelt deze, indien gelukt, in als standaard. Indien de verbindingspoging mislukt, dan wordt teruggevallen op het laatst bekende netwerk.

Vereiste parameters:

  • ssid: SSID waarmee verbonden moet worden.
  • passphrase: passphrase van het te verbinden SSID.
  • connection_attempts: aantal verbindingspogingen alvorens teruggevallen wordt op access point modus.
  • mdns_hostname: multicast DNS hostname waarmee verbonden kan worden zonder IP-adres.

Uitvoer:

  • status: ‘ok’ indien parameters geaccepteerd worden, anders ‘no’. Deze status heeft niets te maken met of de verbindingspoging al dan niet geslaagd is. Doordat de verbinding tijdelijk verbroken wordt door het wisselen van access point is het onmogelijk naderhand uitvoer te geven.
{
    "status":"ok"
}

/getWifi

Methode: GET

Toont de instellingen van het access point waarmee verbinding wordt gemaakt. Het wachtwoord wordt uiteraard om veiligheidsredenen niet getoond.

Uitvoer:

  • ssid: SSID waarmee verbinding wordt gemaakt.
  • connection_attempts: maximaal aantal verbindingspogingen alvorens overgeschakeld wordt naar stand-alone modus (de ESP fungeert dan zelf als access point).
  • mdns_hostname: mDNS (multicast DNS) hostname die gebruikt kan worden om verbinding te maken zonder het IP adres te weten.
{
    "ssid":"DennisBor-IoT",
    "connection_attempts":25,
    "mdns_hostname":"dennisbor_iot"
}

/listWifi?performscan=true

Methode: GET

Zoekt naar beschikbare WiFi netwerken en toont het aantal gevonden netwerken. De reden dat niet direct alle netwerkgegevens getoond worden, is dat de ESP8266 beschikt over een zeer beperkt geheugen. Wanneer er een groot aantal netwerken gevonden zou worden, zou dit na genereren van een grote JSON-string resulteren in een crash.

Uitvoer:

  • count: het aantal gevonden WiFi netwerken.
{
    "count":15
}

Na deze functie kan ‘/listWifi?getnetwork=<index>’ aangeroepen worden, om per netwerk informatie te laden.

/listWifi?getnetwork=<index>

Methode: GET

Toont informatie van het opgegeven netwerk. Netwerken worden geïdentificeerd met nummers, waarbij het eerste nummer index 0 krijgt. Bij een netwerkaantal van 15 zijn indices 0-14 toegestaan. Deze functie kan pas aangeroepen worden na ‘/data_listwifi?performscan=true’.

Uitvoer:

  • ssid: SSID van gevonden netwerk
  • channel: netwerkkanaal van gevonden netwerk
  • rssi: RSSI (Received Signal Strength Indicator) ofwel signaalsterkte van gevonden netwerk.
  • security: beveiligingsmethode van het gevonden netwerk (2 = WPA, 4 = WPA2, 5 = WEP, 7 = open netwerk, 8 = WPA2)
{
    "ssid":"DennisBor",
    "channel":11,
    "rssi":-52,
    "security":4
}

/login

Methode: POST

Probeert in te loggen aan de hand van opgegeven POST-gegevens en zal, afhankelijk van of inloggen gelukt is, pagina index.html laden of anders een ‘401: unauthorized’ foutmelding geven.

Vereiste parameters:

  • username: gebruikersnaam van de webinterface
  • password: wachtwoord van de webinterface

Deze functie heeft geen uitvoer.

/logout

Methode: GET

Logt de gebruiker uit, waarna pagina login.html geladen wordt.

Deze functie heeft geen uitvoer.

/status

Methode: GET

Toont statusinformatie van de ESP8266 module.

Uitvoer:

  • mode: verbindingsmodus (client: verbonden met het opgegeven netwerk of ap: access-point).
  • ssid: in client-modus het SSID van het netwerk waarmee verbonden is of in het geval van AP-modus de eigen netwerknaam.
  • ip: IP-adres van de module. In clientmodus wordt hier het verkregen IP-adres getoond of in AP-modus het eigen IP-adres (altijd 192.168.4.1).
{
    "mode": "ap",
    "ssid": "https://www.dennisbor.com",
    "ip": "192.168.4.1"
}