WiFiThermostat/HTTP-web-interface-and-API.md

WiFiThermostat - HTTP web interface and API

Web interface

The thermostat runs a small web interface for direct control and configuration on HTTP port 80.

URL: http://[IP]/

It can be user/password protected using the options in Config Web.
An Admin-User can be set as well as 2 Non-Admin Users.
The Web interface includes the following functions:

• Control of the basic Thermostat settings (User-Controllable)
• Change the 2 reduction temperatures (User-Controllable)
• Configuration (Admin only)
  • Device and WiFi settings
  • Web Interface settings
  • MQTT settings
  • Thermostat Basic settings
  • Thermostat Advanced settings
  • Additional Functions settings
  • OTA Firmware Update
• Restart

HTTP API

The Device can be controlled using an HTTP API.
Most options can use either an API Token for basic protection, or user/password using basic authentication.
The API Token can can be configured on the Web Interface configuration page on the web interface.
Currently the following HTTP API calls are implemented:

Set target Temperature

Sets the heating target temperature.

METHOD: GET
API-URL: http://[IP]/setTemp?value=[VALUE]
API-URL: http://[IP]/setTemp?value=[VALUE]&token=[TOKEN]

Where [VALUE] is float in 0.5 steps, must be between configured setTempMin and setTempMax.
Lower values result as setTempMin result in setTemp = setTempMin, higher in setTemp = setTempMax.
Decimals other than .0 and .5 are rounded to the nearest valid value.

Set heating mode

Sets the heating mode.
Can be one of the following values:

• 0 - heating off
  
• 1 - normal heating mode ('ON')
  

METHOD: GET
API-URL: http://[IP]/setMode?value=[VALUE]
API-URL: http://[IP]/setMode?value=[VALUE]&token=[TOKEN]

Set heating preset

Sets the preset
Can be one of the following values:

• 0 - normal heating mode (no reduction)
  
• 1 - reduction 1 (reduced target temp)
  
• 2 - reduction 2 (more reduced target temp)
  

METHOD: GET
API-URL: http://[IP]/setPreset?value=[VALUE]
API-URL: http://[IP]/setPreset?value=[VALUE]&token=[TOKEN]

MQTT reconnect

Forces MQTT reconnect.
Needs to be authenticated or use TOKEN

METHOD: GET
API-URL: http://[IP]/?mqttreconnect
API-URL: http://[IP]/?mqttreconnect&token=[TOKEN]

Restart

Restarts the MCU
Needs to be authenticated or use TOKEN

METHOD: GET
API-URL: http://[IP]/?restart
API-URL: http://[IP]/?restart&token=[TOKEN]

Info

Returns some runtime information. Currently not much.

METHOD: GET
URL: http://[IP]/info

API

Returns a JSON string with some current data displayed on web interface.
Needs to be authenticated user or use TOKEN.
Provides a POST API for web interface buttons.

URL: http://[IP]/api

Example result:
{"devname":"WTherm-1234","ssid":"MyWiFi","WiFiNum":1,"uptime":"01:09","freeheap":35736, "mqttstate":"CONNECTED","mqtthost":"mqtt.lan","mqttreconn":2,"setTemp":23,"currSetTemp":21, "temp":22.8,"hum":40,"heating":false,"mode":1,"modeName":"heat","pset":1, "psetName":"Reduction 1","psetName0":"Normal","psetName1":"Reduction 1", "psetName2":"Reduction 2","tempLow":21,"tempLow2":17.5}

Where: | VarName | Description | -------------- | --------------------------------------------------------------------- | | devname | Device name | | ssid | WiFi SSID connected to | | WiFiNum | WiFi number from config connected to | | uptime | total runtime since last restart | | freeheap | free heap memory on ESP | | mqttstate | MQTT connection status | | mqtthost | MQTT broker connected to | | mqttreconn | MQTT reconnections since last boot | | setTemp | set target temperature | | currSetTemp | actual set target temperature (shows what reduction modes do) | | temp | current temperature reading from the DHT T/H sensor | | hum | current humidity reading from the DHT T/H sensor | | heating | false if heating is currently off, true if heating is currently on | | mode | heating mode (1 = on/heat, 0 = off) | | modeName | name of current heating mode (configurable via web interface) | | pset | current Preset number | | psetName | current Preset name | | psetName0 | Preset 0 name | | psetName1 | Preset 1 name | | psetName2 | Preset 2 name | | tempLow | set target temperature for Reduction mode 1 | | tempLow2 | set target temperature for Reduction mode 2 |

Additionally /api can take the following arguments as POST request, which are intended to be used by the web interface:
| Argument | Description | -------------- | --------------------------------------------------------------------- | | BtnPlus | Button target temperature plus | | BtnMinus | Button target temperature minus | | BtnPset0 | Button Set Preset 0 (Normal/None) | | BtnPset1 | Button Set Preset 1 (Reduction 1) | | BtnPset2 | Button Set Preset 2 (Reduction 2) | | BtnOn | Button Mode On | | BtnOff | Button Mode Off | | BtnL1Plus | Button Reduction 1 target temperature plus | | BtnL1Minus | Button Reduction 1 target temperature minus | | BtnL2Plus | Button Reduction 1 target temperature plus | | BtnL2Minus | Button Reduction 1 target temperature minus | | setTemp | set target temperature to VALUE (16.0 - 26.0) | | setMode | set heating mode to 0 or 1 | | setPreset | set heating preset to 0 (none), 1 (reduction 1) or 2 (reduction 2) |