Millheat heater gen. 3 - local WiFi Control API - version 0x220727 (27.07.2022)

Overview

Following devices are supported:

Panel heaters - Generation 3.
Convection heaters - Generation 3.
Oil heaters - Generation 3.
Wi-Fi Socket - Generation 3.

Generation 3 heaters expose HTTP server, with a defined REST API. Local HTTP server works both when the device is connected to an existing WiFi network (to a router) or when the device is configured as an Access Point. In the first scenario, the device IP address can be found in the router clients list. In most cases, it is something like 192.168.1.105 or 10.0.0.95, depending on the local network configuration. Once you have an IP address, you can just type it in a web browser (assuming your device is connected to the same WiFi network) to see the main page. It contains a summary of the heater status and reference to this document. In the Access Point mode the heater has IP address 192.168.4.1.

HTTP Requests

All API requests are made by sending a HTTP request using one of the following methods, depending on the action being taken:

POST create a resource,
GET get a resource or list of resources.

Request data is passed as a JSON file content in the request body. Response data is also returned as a JSON file, with the scheme described below.

HTTP Responses

Each response will include aresult (result will be an object for single-record queries and an array for list queries) and status message. The status message contain the information of the result of the processing request. The list of status codes can be found in HTTP Response Codes. The result contains the result of a successful request. For example, a request to the GET status resource might return this:

{
   "name": "panel heater gen. 3",
   "custom_name": "",
   "version": "0x210927",
   "operation_key": "",
   "mac_address": "XX:XX:XX:XX:XX:XX",
   "status": "ok"
}

HTTP Response Status

Each response will be returned the field status with one of the following description:

ok - the request was successful,
Failed to parse message body - the request body is incorrect or the parameters are invalid,
Failed to execute the request - there was a problem with the processing request,
Length of request body too long - the length of the request body is to long,
Failed to create response body - there was a problem with the processing respone.

Resources

We provide a Postman collection with a set of requests that introduce the basic concepts of the API. The Postman collection and more information are available here. In the collection {{heater_addresss}} is the variable which determines the IP address of the device.

Authentication

After setting API key with POST/set-api-key every request on every endpoint would need to contain this key as header. This operation (settign API key) triggers product to restart to change HTTP server to HTTPS server. That server uses self-signed certificate which can generate some warning massages but will provide better security. Header's key must be "Authentication" and it's value should be API key.

Basic communication

GET/status
POST/soft-reset
POST/hard-reset
POST/reboot
GET/temperature-calibration-offset
POST/temperature-calibration-offset
GET/control-status
GET/operation-mode
POST/operation-mode
GET/commercial-lock
POST/commercial-lock
GET/child-lock
POST/child-lock
GET/open-window
POST/open-window
GET/weekly-program
POST/weekly-program
GET/non-repeatable-timers
POST/non-repeatable-timers
GET/display-unit
POST/display-unit
GET/set-temperature
POST/set-temperature
GET/oil-heater-power
POST/oil-heater-power
GET/predictive-heating-type
POST/predictive-heating-type
POST/overwrite-weekly-program
GET/vacation-mode
POST/vacation-mode
GET/timezone-offset
POST/timezone-offset
POST/set-temperature-in-independent-mode-now
GET/additional-socket-mode
POST/additional-socket-mode

Advanced communication

GET/pid-parameters
POST/pid-parameters
GET/cloud-communication
POST/cloud-communication
POST/ota-update
GET/config-parameter
POST/config-parameter
POSTpost/max-heater-power
POST/ablecloud-message
GET/scan-wifi
POST/device-config
GET/hysterersis-parameters
POST/hysterersis-parameters
GET/limited-heating-power
POST/limited-heating-power
GET/controller-type
POST/controller-type
POST/set-custom-name
POST/increase-set-temperature
POST/decrease-set-temperature
POST/set-api-key
GET/commercial-lock-customization
POST/commercial-lock-customization

Examples

Here, we provide example Python scripts which can control the Millheat heater gen. 3 via the REST API:

examples/python/basic_control.py script queries the current control status to obtain current temperature and control signal (how much the heater is heating). Then it changes the set temperature every minute.
examples/python/temperature_control.py script queries the status of the status device and set and get the temperature in a given temperature type. Then it changes the set temperature every minute.
examples/python/timers.py script sets a few timers scheduled for the next few minutes, and queries the status to confirm the proper behavior. Note that the script doesn't need to keep running to have the timers working - they are stored and executed inside the device.

We also provide a simple example to control the Millheat heater gen. 3 with a Bash script:

In examples/bash/query_ambient_temperature.sh script the ambient temperature is returned every second.

`GET`/status

Return a quick summary of the device information.

Returned parameters

Field	Type	Description
name	string	the name of the device
custom_name	string	the custom name of the device
version	string	the API version number
operation_key	string	if there is some operation problem (like broken temperature sensor), it may be reported in this field
mac_address	string	device's MAC (Media Access Control) address

Example

Request

Postman:
```
GET http://{{heater_address}}/status
```
Request body: empty

Curl:

curl -X GET -H "Content-Type: application/json" http://{{heater_address}}/status

Response:

{
   "name": "panel heater gen. 3",
   "custom_name": "",
   "version": "0x210927",
   "operation_key": "",
   "mac_address": "XX:XX:XX:XX:XX:XX",
   "status": "ok"
}

`POST`/soft-reset

Perform a soft-reset of the device (configuration).

Example

Request

Postman:

POST http://{{heater_address}}/soft-reset

Request body: empty

Response

The soft-reset performs before sending response.

`POST`/hard-reset

Perform a hard-reset of the device.

Example

Request

Postman:

POST http://{{heater_address}}/hard-reset

Request body: empty

Response

The hard-reset performs before sending response.

`POST`/reboot

Perform a reboot of the heater control MCU

Example

Request

Postman:
```
POST http://{{heater_address}}/reboot
```
Request body: empty

Response

The reboot performs before sending response.

`GET`/temperature-calibration-offset

Return the current value of temperature sensor calibration offset.

Returned parameters

Field	Type	Description
value	float	the calibration offset value in Celsius degrees

Example

Request

Postman:

GET http://{{heater_address}}/temperature-calibration-offset

Request body: empty

Curl:

curl -X GET -H "Content-Type: application/json" http://{{heater_address}}/temperature-calibration-offset

Response

{
   "value": 2.5,
   "status": "ok"
}

`POST`/temperature-calibration-offset

Set a new value of temperature sensor calibration offset.

Body parameters

Field	Type	Description
value	float	the calibration offset value in Celsius degrees

Example

Request

Postman:

POST http://{{heater_address}}/temperature-calibration-offset

Request body:

{
   "value": 2
}

Curl:

curl -X POST -H "Content-Type: application/json" -d '{"value": 2}' http://{{heater_address}}/temperature-calibration-offset

Response

{
    "status": "ok"
}

`GET`/control-status

Return detailed information about the current device state and control status.

Returned parameters

Field	Type	Description
ambient_temperature	float	the temperature measured by sensor in Celsius degrees (with calibration offset value included)
current_power	float	the current heating power in Watts
control_signal	float	the control signal of the PID regulator (0-100%)
lock_active	string	the lock status (see ELockStatus)
open_window_active_now	string	the open widows status (see EOpenWindowStatus)
raw_ambient_temperature	float	the temperature measured by sensor in Celsius degrees without calibration offset value
set_temperature	float	the current set temperature in Celsius degrees
switched_on	float	true if the device is switched on - whether it is set to working, with heating
connected_to_cloud	bool	the information whether device has connection with the cloud
operation_mode	string	the current mode of operation (see EOprationMode)

Example

Request

Postman:

GET http://{{heater_address}}/control-status

Request body: empty

Curl:

curl -X GET -H "Content-Type: application/json" http://{{heater_address}}/control-status

Response

{
   "ambient_temperature": 22,
   "current_power": 5,
   "control_signal": 100,
   "lock_active": "Child lock",
   "open_window_active_now": "Enabled not active now",
   "raw_ambient_temperature": 21,
   "set_temperature": 1,
   "switched_on": false,
   "connected_to_cloud": true,
   "operation_mode": "Control individually",
   "status": "ok"
}

`GET`/operation-mode

Return the current operation mode.

Returned parameters

Field	Type	Description
mode	string	the current operation mode (see EOprationMode)

Example

Request

Postman:

GET http://{{heater_address}}/operation-mode

Request body: empty

Response

{
   "mode": "Control individually",
   "status": "ok"
}

`POST`/operation-mode

Set the operation mode.

Body parameters

Field	Type	Description
mode	string	the operation mode to set (see EOprationMode)

Example

Request

Postman:

POST http://{{heater_address}}/operation-mode

Request body:

{
   "mode": "Control individually"
}

Response

{
   "status": "ok"
}

`GET`/commercial-lock

Return the status of the commercial lock.

Returned parameters

Field	Type	Description
value	bool	the status of the commercial lock

Example

Request

Postman:

GET http://{{heater_address}}/commercial-lock

Request body: empty

Response

{
   "value": true,
   "status": "ok"
}

`POST`/commercial-lock

Set status of the commercial lock.

Body parameters

Field	Type	Description
value	bool	the status of the commercial lock to set

Example

Request

Postman:

GET http://{{heater_address}}/commercial-lock

Request body:

{
   "value": true
}

Response

{
    "status": "ok"
}

`GET`/child-lock

Return the status of the child lock.

Returned parameters

Field	Type	Description
value	bool	the status of the child lock

Example

Request

Postman:

GET http://{{heater_address}}/child-lock

Request body: empty

Response

{
   "value": false,
   "status": "ok"
}

`POST`/child-lock

Set status of the child lock.

Body parameters

Field	Type	Description
value	bool	the status of the child lock to set

Example

Request

Postman:

GET http://{{heater_address}}/child-lock

Request body:

{
   "value": false
}

Response

{
   "status": "ok"
}

`GET`/open-window

Return the current state of the open window functionality and its configuration parameters.

Returned parameters

Field	Type	Description
active_now	bool	true if open window functionality was activated and is active now
drop_temperature_threshold	float	the required temperature drop to trigger (activate) the open window functionality (in Celsius degrees)
drop_time_range	int	the time range when a drop of temperature will be expected (in seconds)
enabled	bool	the state of the open window functionality, true if open window functionality is enabled
increase_temperature_threshold	int	the time range when an increase of temperature will be expected (in seconds)
max_time	int	the maximum time duration of the open window activeness

Example

Request

Postman:

GET http://{{heater_address}}/open-window

Request body: empty

Response

{
   "active_now": false,
   "drop_temperature_threshold": 5,
   "drop_time_range": 900,
   "enabled": true,
   "increase_temperature_threshold": 3,
   "increase_time_range": 900,
   "max_time": 3600,
   "status": "ok"
}

`POST`/open-window

Change the open window functionality parameters or enable/disable it.

Body parameters

Field	Type	Description
drop_temperature_threshold	float	the required temperature drop to trigger (activate) the open window functionality (in Celsius degrees)
drop_time_range	int	the time range when a drop of temperature will be expected (in seconds)
enabled	bool	the state of the open window functionality, true if open window functionality is enabled
increase_temperature_threshold	int	the time range when an increase of temperature will be expected (in seconds)
increase_time_range	float	the time range when an increase of temperature will be expected
max_time	float	the maximum time duration of the open window activeness

Example

Request

Postman:

POST http://{{heater_address}}/open-window

Request body:

{
    "drop_temperature_threshold": 5,
    "drop_time_range": 900,
    "enabled": true,
    "increase_temperature_threshold": 3,
    "increase_time_range": 900,
    "max_time": 3600
}

Response

{
   "status": "ok"
}

`GET`/weekly-program

Return the weekly program.

Returned parameters

Field	Type	Description
active	bool	state of the weekly program: true if is active, if false, the device works as an independent device
timers	list<string, int>	repeating pairs of values. A single pair represents time and value when the temperature mode should be changed. Time is a week time, in minutes since Monday 00:00, when to switch to a specific temperature type (set in the second field of the pair) (see ETemperatureType)

Example

Request

Postman:

GET http://{{heater_address}}/weekly-program

Request body: empty

Curl:

curl -X GET -H "Content-Type: application/json" http://{{heater_address}}/weekly-program

Response

{
    "timers": [
        {
            "name": "Comfort",
            "timestamp": 12
        },
        {
            "name": "Away",
            "timestamp": 30
        },
        {
            "name": "Sleep",
            "timestamp": 50
        }
    ],
    "active": false,
    "status": "ok"
}

`POST`/weekly-program

Set the weekly program or repeatable timers. One also needs to set the timezone-offset. The device needs to connect to the WiFi to synchronize the time with NTP server after each restart.

To have the weekly program working, one needs to set operation-mode to "Weekly program" mode.

To have the repeatable timers working, one needs to set operation-mode to "Independent device" mode.

Body parameters

Field	Type	Description
timers	list<string, int>	repeating pairs of values. A single pair represents time and value when the temperature mode should be changed. Time is a week time, in minutes since Monday 00:00 when to switch to a specific temperature type (set in the second field of the pair). For available temperature types (see `GET` set temperature) and ETemperatureType)

Example

Request

Postman:

POST http://{{heater_address}}/weekly-program

Request body:

{
	"timers": [
		{
            "name": "Comfort", 
            "timestamp": 12
        },
		{
            "name": "Away", 
            "timestamp": 30
        },
		{
            "name": "Sleep", 
            "timestamp": 50
        }
	]
}

Curl:

url -X POST -H "Content-Type: application/json" -d '{"timers": [{"name": "Comfort", "timestamp": 12},{"name": "Away", "timestamp": 30},{"name": "Sleep", "timestamp": 50}]}' http://{{heater_address}}/weekly-program

Response

{
   "status": "ok"
}

`GET`/non-repeatable-timers

Return the non-repeatable timers.

Returned parameters

Field	Type	Description
active	bool	true if operation mode is "Independent device" (see EOprationMode), false otherwise
timers	list<string, int>	repeating pairs of values. A single pair represents time and value when the temperature mode should be changed. Time defines when to switch to a specific temperature type (set in the second field of the pair). Time is as local unix timestamp, but in minutes, e.g. on 17.05.2021 the time is 27020801.

Example

Request

Postman:

GET http://{{heater_address}}/non-repeatable-timers

Request body: empty

Response

{
    "non_repeatable_timers": [
        {
            "name": "Normal",
            "timestamp": 27245338
        },
        {
            "name": "Off",
            "timestamp": 27245339
        },
        {
            "name": "Normal",
            "timestamp": 27245340
        },
        {
            "name": "Off",
            "timestamp": 27245341
        }
    ],
    "active": true,
    "status": "ok"
}

`POST`/non-repeatable-timers

Set the non-repeatable timers.

One also needs to set the timezone-offset. The device needs to connect to the WiFi to synchronize the time with NTP server after each restart. To have the non-repeatable timers working, one needs to set operation-mode to "Independent device" mode. Please refer to example script examples/python/timers.py

Body parameters

Field	Type	Description
timers	list<string, int>	A single pair represents time and value when the temperature mode should be changed. Time defines when to switch to a specific temperature type (set in the second field of the pair). Time is as local unix timestamp (so timezone is included), but in minutes, e.g. on 17.05.2021 the time is 27020801. Allowed temperature types for timers: "Normal", "Off", "AlwaysHeating"

Example

Request

Postman:

POST http://{{heater_address}}/non-repeatable-timers

Request body:

{
	"non_repeatable_timers": [
		{
            "name": "Off", 
            "timestamp": 12
        },
		{
            "name": "Away", 
            "timestamp": 30
        },
		{
            "name": "Sleep", "
            timestamp": 50
        }
	]
}

Response

{
   "status": "ok"
}

`GET`/display-unit

Return the current temperature units used on the display.

Returned parameters

Field	Type	Description
value	string	the current temperature units: "Celsius" or "Fahrenheit"

Example

Request

Postman:

GET http://{{heater_address}}/display-unit

Request body: empty

Response

{
   "value": "Farenheit",
   "status": "ok"
}

`POST`/display-unit

Set the current temperature units used on the display.

Body parameters

Field	Type	Description
value	string	the temperature units: "Celsius" or "Fahrenheit" to set

Example

Request

Postman:

POST http://{{heater_address}}/child-lock

Request body:

{
   "value": "Farenheit"
}

Response

{
   "status": "ok"
}

`GET`/set-temperature

Return temperature of the specified in body of the request temperature type. In operation modes Control individually and Independent device one usally is interested in Normal temperature type.

Returned parameters

Field	Type	Description
value	float	the temperature in Celsius to set

Body parameters

Field	Type	Description
type	string	the temperature type to get (see ETemperatureType)

Example

Request

Postman:

GET http://{{heater_address}}/set-temperature

Request body:

{
   "type": "Normal"
}

Curl:

curl -X GET -H "Content-Type: application/json" -d  '{"type": "Normal"}' http://{{heater_address}}/set-temperature

Response

{
   "value": 30,
   "status": "ok"
}

`POST`/set-temperature

Set temperature of the specified temperature type. This endpoint doesn't put the device in specific mode, it just sets the temperature for chosen mode. One cannot send "Off" type using this endpoint as temperature for Off mode cannot be set (it is set to specified value by default). If operation mode is "Control individually" or "Independent device" one is usually interested in "Normal" temperature type.

Body parameters

Field	Type	Description
type	string	the temperature type to set (see ETemperatureType)
value	float	the temperature in Celsius to set

Example

Request

Postman:

POST http://{{heater_address}}/set-temperature

Request body:

{
   "type": "Normal",
   "value": 30
}

Curl:

curl -X POST -H "Content-Type: application/json" -d '{"type": "Normal", "value": 30}' http://{{heater_address}}/set-temperature

Response

{
   "status": "ok"
}

`GET`/oil-heater-power

Return the max heating level in percentage of the nominal wattage. Oil heater allows setting 3 different max power settings (40, 60 or 100% of the power), done by selecting number of active heating elements.

Returned parameters

Field	Type	Description
heating_level_percentage	int	the heating level in percentage

Example

Request

Postman:

GET http://{{heater_address}}/oil-heater-power

Request body: empty

Response

{
   "value": 100,
   "status": "ok"
}

`POST`/oil-heater-power

Set the max heating level in percentage of the nominal wattage. Oil heater allows setting 3 different max power settings (40, 60 or 100% of the power), done by selecting number of active heating elements.

Body parameters

Field	Type	Description
heating_level_percentage	int	the heating level in percentage: 0, 40, 60 or 100 to set

Example

Request

Postman:

POST http://{{heater_address}}/oil-heater-power

Request body:

{
    "heating_level_percentage": 100
}

Response

{
   "status": "ok"
}

`GET`/predictive-heating-type

Return the predictive heating type.

Returned parameters

Field	Type	Description
predictive_heating_type	string	the predictive heating type (see EPredictiveHeatingType)

Example

Request

Postman:

GET http://{{heater_address}}/predictive-heating-type

Request body: empty

Response

{
   "predictive_heating_type": "Off",
   "status": "ok"
}

`POST`/predictive-heating-type

Set the predictive heating type.

Body parameters

Field	Type	Description
predictive_heating_type	string	the predictive heating type (see EPredictiveHeatingType) to set

Example

Request

Postman:

POST http://{{heater_address}}/predictive-heating-type

Request body:

{
    "predictive_heating_type": "Off"
}

Response

{
   "status": "ok"
}

`POST`/overwrite-weekly-program

Overwrite the weekly program.

Body parameters

Field	Type	Description
duration	int	the overwrite weekly program duration minutes
type	string	the temperature type to set (see ETemperatureType)

Example

Request

Postman:

POST http://{{heater_address}}/overwrite-weekly-program

Request body:

{
    "duration": 1,
    "type": "Away"
}

Response

{
   "status": "ok"
}

`GET`/vacation-mode

Get the vacation mode settings.

Returned parameters

Field	Type	Description
start_timestamp	int	the 32 bit timestamp in minutes
end_timestamp	int	the 32 bit timestamp in minutes

Example

Request

Postman:

GET http://{{heater_address}}/vacation-mode

Request body: empty

Response

{
   "start_timestamp": 0,
   "end_timestamp": 0,
   "status": "ok"
}

`POST`/vacation-mode

Set the vacation mode settings.

Body parameters

Field	Type	Description
start_timestamp	int	the 32 bit timestamp in minutes (0 for no vacation mode) to set
end_timestamp	int	the 32 bit timestamp in minutes (0 for no vacation mode) to set

Example

Request

Postman:

POST http://{{heater_address}}/vacation-mode

Request body:

{
   "start_timestamp": 0,
   "end_timestamp": 0
}

Response

{
   "status": "ok"
}

`GET`/timezone-offset

Get the timezone offset.

Returned parameters

Field	Type	Description
timezone_offset	int	the timezone offset in minutes from -840 to +720

Example

Request

Postman:

GET http://{{heater_address}}/timezone-offset

Request body: empty

Response

{
   "timezone_offset": 1440,
   "status": "ok"
}

`POST`/timezone-offset

Set the timezone offset. Required to have weekly program and timers working.

Body parameters

Field	Type	Description
timezone_offset	int	Device timezone offset in minutes

Example

Request

Postman:

POST http://{{heater_address}}/timezone-offset

Request body:

{
    "timezone_offset": 60
}

Response

{
    "status": "ok"
}

`POST`/set-temperature-in-independent-mode-now

Change temperature in independent mode now. Use values 0.0 and 99.0 to set ALWAYS_ON and ALWAYS_OFF, respectively. Apart from changing value for some temperature type, in "Independent device" operation mode, one also needs to call this command to change the current temperature.

Body parameters

Field	Type	Description
temperature	float	the temperature value to set

Example

Request

Postman:

POST http://{{heater_address}}/set-temperature-in-independent-mode-now

Request body:

{
   "temperature": 12.0
}

Response

{
   "status": "ok"
}

`GET`/additional-socket-mode

Only for socket heaters

Return the additional socket mode.

Returned parameters

Field	Type	Description
additional_mode	int	the additional socket mode

Example

Request

Postman:

GET http://{{heater_address}}/additional-socket-mode

Request body: empty

Response

{
   "additional_mode": 3,
   "status": "ok"
}

`POST`/additional-socket-mode

Only for socket heaters

Set the additional socket mode.

Body parameters

Field	Type	Description
additional_mode	int	the additional mode <0 - 4> to set

Example

Request

Postman:

POST http://{{heater_address}}/additional-socket-mode

Request body:

{
   "additional_mode": 3
}

Response

{
   "status": "ok"
}

`GET`/pid-parameters

Only for panel heaters

Return PID parameters of the temperature PID controller.

Returned parameters

Field	Type	Description
kp	float	the proportional part gain
ki	float	the integral part gain
kd	float	the derivative part gain
kd_filter_N	float	the derivative filter time coefficient
windup_limit_percentage	float	the windup limit for integral part from 0 to 100

Example

Request

Postman:

GET http://{{heater_address}}/pid-parameters

Request body: empty

Response

{
   "kp": 70,
   "ki": 0.02,
   "kd": 4500,
   "kd_filter_N": 60,
   "windup_limit_percentage": 95,
   "status": "ok"
}

`POST`/pid-parameters

Only for panel heaters

Set PID parameters. Setting PID parameters will change current regulator type to PID. PID regulator works only with panel heater.

Body parameters

Field	Type	Description
kp	float	the proportional part gain
ki	float	the integral part gain
kd	float	the derivative part gain
kd_filter_N	float	the derivative filter time coefficient
windup_limit_percentage	float	the windup limit for integral part from 0 to 100

Example

Request

Postman:

POST http://{{heater_address}}/pid-parameters

Request body:

{
    "kp": 70,
    "ki": 0.02,
    "kd": 4500,
    "kd_filter_N": 60,
    "windup_limit_percentage": 95,
    "status": "ok"
}

Response

{
   "status": "ok"
}

`GET`/cloud-communication

Return the cloud communication activeness status.

Returned parameters

Field	Type	Description
value	bool	the cloud communication activeness status, true if device is allowed to communicate with cloud

Example

Request

Postman:

GET http://{{heater_address}}/cloud-communication

Request body: empty

Response

{
   "value": true,
   "status": "ok"
}

`POST`/cloud-communication

Allows disabling cloud communication completely. Requires a reboot after this command.

Body parameters

Field	Type	Description
value	bool	the cloud communication activeness status, true if device is allowed to communicate with cloud

Example

Request

Postman:

POST http://{{heater_address}}/cloud-communication

Request body:

{
    "value": false
}

Response

{
   "status": "ok"
}

`POST`/ota-update

Perform OTA update, to replace the firmware. The device needs to have Internet access to perform it.

Body parameters

Field	Type	Description
address	string (url)	the address to firmware binary for the heater, http address allowed

Example

Request

Postman:

POST http://{{heater_address}}/ota-update

Request body:

{
	"value": false
}

Response

{
   "status": "ok"
}

`GET`/config-parameter

Return the configuration parameter determined by the name in request message.

Body parameters

Field	Type	Description
name	string	the name of the parameter to get

Returned parameters

Field	Type	Description
value	string	the value of the parameter

Example

Request

Postman:

GET http://{{heater_address}}/config-parameter

Request body:

{
   "name": "Set"
}

Response

{
   "value": "",
   "status": "ok"
}

`POST`/config-parameter

Set the configuration parameter determined by the name in request message.

Body parameters

Field	Type	Description
name	string	the name of the parameter to set
vaule	string	the value of the parameter

Example

Request

Postman:

POST http://{{heater_address}}/cloud-communication

Request body:

{
   "name": "Set",
   "value": 70
}

Response

{
   "status": "ok"
}

`POST`/max-heater-power

Set max heater power in Watts.

Body parameters

Field	Type	Description
power	int	the value of the heater power in Watts
calibrate	bool	whether to perform the calibration with the chip measuring the power usage

Example

Request

Postman:

POST http://{{heater_address}}/max-heater-power

Request body:

{
   "power": 12,
   "calibrate": false
}

Response

{
   "status": "ok"
}

`POST`/ablecloud-message

Send a message and process it as if it would come from AbleCloud module.

Body parameters

Field	Type	Description
message_code	int	code of the message
data	string	the binary data as hex string, e.g. string "1AB2550C" would be parsed to binary array {0x1A, 0xB2, 0x55, 0x0C}

Example

Request

Postman:

POST http://{{heater_address}}/ablecloud-message

Request body:

{
    "message_code": 3,
    "data": 4443
}

Response

{
    "status": "ok"
}

`GET`/scan-wifi

The heater has to be configured in the access mode (AP) mode. Then, you have to be connected to the network provided by your heater and check the IP adress which has format "192.168.4.x". The request should be post on this address.

Returns the list of WiFi networks scanned by ESP32, ordered by best signal (maximum 20 networks).

Returned parameters

Field	Type	Description
wifi	list	the list of WiFi networks scanned by ESP32

Example

Request

Postman:
```
GET http://192.168.4.x/scan-wifi
```
Request body: empty

Response

{
   "value": "",
   "status": "ok"
}

`POST`/device-config

Body parameters

Field	Type	Description
ssid	string	the SSID of the WiFi
password	string	the password of the WiFi
connectivity_option	string	the connectivity option (see ECloudAndServerCommunicationType)

Example

Request

Postman:

POST http://{{heater_address}}/device-config

Request body:

{
   "ssid": "wifi_ssid",
   "password": "wifi_password",
   "connectivity_option": "sta_cloud_and_local_api"
}

Response

{
   "status": "ok"
}

`GET`/hysteresis-parameters

Get current hysteresis setting.

Returned parameters

Field	Type	Description
temp_hysteresis_upper	float	upper offset (set temp + this -> stop heat)
temp_hysteresis_lower	float	lower offset (set temp - this -> start heat)

Example

Request

Postman:

GET http://192.168.4.x/hysteresis-parameters

Request body: empty

Response

{
    "temp_hysteresis_upper": 2,
    "temp_hysteresis_lower": 1,
    "regulator_type": "hysteresis",
    "status": "ok"
}

`POST`/hysteresis-parameters

Set hysteresis parameters. Setting hysteresis parameters will change current regulator type to hystersis.

AFTER CHANGING HYSTERESIS PARAMETERS RESTART IS REQUIRED

Body parameters

Field	Type	Description
temp_hysteresis_upper	float	upper offset (set temp + this -> stop heat)
temp_hysteresis_lower	flaot	lower offset (set temp - this -> start heat)

Example

Request

Postman:

POST http://{{heater_address}}/hysteresis-parameters

Request body:

{
  "temp_hysteresis_upper": 1,
  "temp_hysteresis_lower": 1,
}

Response

{
   "status": "ok"
}

`GET`/limited-heating-power

Get current maximum limited heating power (percentage of maximum power) (only Panel and Storage heater).

Only for panel heaters

Returned values

Field	Type	Description
limited_heating_power	int	percentage of maximum power that heater can use. Value in range 10 - 100.
status	str	"ok" or error message

Example

Request

Postman:

GET http://{{heater_address}}/limited-heating-power

Response

{
    "limited_heating_power": 75,
    "status": "ok"
}

`POST`/limited-heating-power

Only for panel heaters

Set current maximum limited heating power (percentage of maximum power) (only Panel and Storage heater).

Body parameters

Field	Type	Description
limited_heating_power	int	percentage of maximum power that heater can use. Value in range 10 - 100.

Example

Request

Postman:

POST http://{{heater_address}}/limited-heating-power

Request body:

{
  "limited_heating_power": 75,
}

Response

{
   "status": "ok"
}

`GET`/controller-type

Get current current regulator controller type. Hysteresis controller is available for oil, convertor and socket heaters. Slow PID is available for panel and storage heaters.

Returned values

Field	Type	Description
regulator_type	str	type of current controller type ("pid" or "hysteresis_or_slow_pid")
status	str	"ok" or error message

Example

Request

Postman:

GET http://{{heater_address}}/controller-type

Response

{
    "regulator_type": "hysteresis_or_slow_pid",
    "status": "ok"
}

`POST`/controller-type

Set current current regulator controller type. Hysteresis controller is available for oil, convertor and socket heaters. Slow PID is available for panel and storage heaters.

Body parameters

Field	Type	Description
regulator_type	str	type of current controller type ("pid", "hysteresis_or_slow_pid" or "unknown" - no change)

Example

Request

Postman:

POST http://{{heater_address}}/controller-type

Request body:

{
  "regulator_type": "unknown",
}

Response

{
   "status": "ok"
}

`POST`/set-custom-name

Change your device's custom name.

Body parameters

Field	Type	Description
device_name	str	new device custom name, it can have at most 32 characters

Example

Request

Postman:

POST http://{{heater_address}}/set-custom-name

Request body:

{
  "device_name": "My new custom name",
}

Response

{
   "status": "ok"
}

`POST`/increase-set-temperature

Increase set temperature by one 0.5*C.

Body parameters

None

Example

Request

Postman:

POST http://{{heater_address}}/increase-set-temperature

Request body:

None

Response

{
   "status": "ok"
}

`POST`/decrease-set-temperature

Decrease set temperature by 0.5*C.

Body parameters

None

Example

Request

Postman:

POST http://{{heater_address}}/decrease-set-temperature

Request body:

None

Response

{
   "status": "ok"
}

`POST`/set-api-key

Set API key to authenticate users. BE CAREFULL!!! To reset API key one need to perform factory reset.

Body parameters

Field	Type	Description
api_key	str	new API key, enables authentication and HTTPS server, it can have at most 63 characters

Example

Request

Postman:

POST http://{{heater_address}}/set-api-key

Request body:

{
  "api_key": "asdasd"
}

Response

{
   "status": "ok"
}

`GET`/commercial-lock-customization

Get commercial lock with range of possible temperature to change.

Returned values

Field	Type	Description
enable	bool	sets commercial lock state
min_allowed_temp_in_commercial_lock	float	minimal temperature that can be set while device has active commercial lock
max_allowed_temp_in_commercial_lock	float	maximal temperature that can be set while device has active commercial lock

Example

Request

Postman:

GET http://{{heater_address}}/commercial-lock-customization

Response

{
    "enabled": false,
    "min_allowed_temp_in_commercial_lock": 11,
    "max_allowed_temp_in_commercial_lock": 30,
    "status": "ok"
}

`POST`/commercial-lock-customization

Set commercial lock with range of possible temperature to change.

Body parameters

Field	Type	Description
enable	bool	sets commercial lock state
min_allowed_temp_in_commercial_lock	float	minimal temperature that can be set while device has active commercial lock
max_allowed_temp_in_commercial_lock	float	maximal temperature that can be set while device has active commercial lock

Example

Request

Postman:

POST http://{{heater_address}}/commercial-lock-customization

Request body:

{
    "enabled": false,
    "min_allowed_temp_in_commercial_lock": 11,
    "max_allowed_temp_in_commercial_lock": 30
}

Response

{
   "status": "ok"
}

Fields

ELockStatus

The ELockStatus variable allow to set one of the following lock mode:

Value	Description
"No lock"	all buttons are active
"Child lock"	buttons on the device not active. In order to activate the child lock please turn on the heater and before 5 seconds pass, press the settings button for 3 seconds and release.
"Commercial lock"	buttons on the device not active. In order to activate the commercial lock please turn on the heater and before 10 seconds pass, press the settings button for 3 seconds and release.

EOpenWindowStatus

The Open Windows function is activated instantly when temperature drops within x1 min by x2 degrees or more. The heater will automatically stop heating and FO will be displayed on in the display of the heater. The heater will automatically start heating again if temperature will increase at least by x3 degrees within x4 minutes.

Value	Description
"Disabled not active now"	Open Windows functionality is disabled, so it is not working at all
"Enabled active now"	Open Window functionality is active, but the window is not detected as open, so the heater operates normally
"Enabled not active now"	Open Window functionality is active, and the window is detected as open, so the heater is not heating

EOprationMode

The Heater may operate in four operation modes:

Value	Description
"Off"	the device is in off mode, it is not possible to send any comands to the device. The device doesn't follow neither weekly program nor it is in independent mode, nor in control individually
"Weekly program"	follow the weekly program, changing temperature by display buttons changes the temperature of the current temperature mode
"Independent device"	follow the single set value, with timers enabled
"Control individually"	follow the single set value, but not use any timers or weekly program
"Invalid"

ETemperatureType

Value	Description
"Off"	The temperature is set to default value of 0 (so that heater will not heat at all) that cannot be changed by the user. As one cannot set temperature for this type, it cannot be sent through set-temperature endpoint
"Normal"	a single value, used for operation modes "Independent device" and timers
"Comfort"	Temperature defined for type Comfort
"Sleep"	Temperature defined for type Sleep
"Away"	Temperature defined for type Away
"AlwaysHeating"	Heat all the time, regardless of the temperature. One cannot set temperature for this type.

In weekly program one can set all of these types. For timers, one can set only "Normal", "Off", "AlwaysHeating" types.

EPredictiveHeatingType

Defines type of predictive heating functionality.

Value	Description
"Off"	No predictive heating. Temperature will be change exactly with the weekly program timer
"Simple"	Simple predictive heating. Temperature will be change before the timer, with a fixed time for each Celsius degree
"Advanced"	Advanced predictive heating. Temperature will be change before the timer, with a time based on the current room model. Model is estimated while running.

ECloudAndServerCommunicationType

Defines how the device communicated via WiFi and cloud.

Value	Description
"sta_cloud_without_local_api"	Device connects to the router. Cloud is enabled, but this WiFi API is disabled
"sta_cloud_and_local_api"	Device connects to the router. Cloud and this WiFi API both enabled
"sta_local_api_without_cloud"	Device connects to the router. Cloud is disabled, but this WiFi API is enabled
"ap_local_api_without_cloud"	Device behaves as Access Point. One can connect to the device via WiFi and communicate through this WiFi API

mxmzdlv/Generation_3_REST_API

Millheat heater gen. 3 - local WiFi Control API - version 0x220727 (27.07.2022)

Overview

HTTP Requests

HTTP Responses

HTTP Response Status

Resources

Authentication

Basic communication

Advanced communication

Examples

GET/status

Returned parameters

Example

Request

Response:

POST/soft-reset

Example

Request

Response

POST/hard-reset

Example

Request

Response

POST/reboot

Example

Request

Response

GET/temperature-calibration-offset

Returned parameters

Example

Request

Response

POST/temperature-calibration-offset

Body parameters

Example

Request

Response

GET/control-status

Returned parameters

Example

Request

Response

GET/operation-mode

Returned parameters

Example

Request

Response

POST/operation-mode

Body parameters

Example

Request

Response

GET/commercial-lock

Returned parameters

Example

Request

Response

POST/commercial-lock

Body parameters

Example

Request

Response

GET/child-lock

Returned parameters

Example

Request

Response

POST/child-lock

Body parameters

Example

Request

Response

GET/open-window

Returned parameters

Example

Request

Response

POST/open-window

Body parameters

`GET`/status

`POST`/soft-reset

`POST`/hard-reset

`POST`/reboot

`GET`/temperature-calibration-offset

`POST`/temperature-calibration-offset

`GET`/control-status

`GET`/operation-mode

`POST`/operation-mode

`GET`/commercial-lock

`POST`/commercial-lock

`GET`/child-lock

`POST`/child-lock

`GET`/open-window

`POST`/open-window

`GET`/weekly-program

`POST`/weekly-program

`GET`/non-repeatable-timers

`POST`/non-repeatable-timers

`GET`/display-unit

`POST`/display-unit

`GET`/set-temperature

`POST`/set-temperature

`GET`/oil-heater-power

`POST`/oil-heater-power

`GET`/predictive-heating-type

`POST`/predictive-heating-type

`POST`/overwrite-weekly-program

`GET`/vacation-mode