Skip to main content

​
Overview

The /command endpoint lets you control thermostat settings programmatically from the Control API (port 8082).

​
Endpoint

POST http://your-server:8082/command
This endpoint has no authentication by default. Secure it with a reverse proxy if exposing publicly.

​
Request

​
Headers

POST /command HTTP/1.1
Host: your-server:8082
Content-Type: application/json

​
Body

{
  "serial": "02AB01AC012345678",
  "command": "set_temperature",
  "value": 21.5
}

​
Parameters

ParameterTypeRequiredDescription
serialstringYesDevice serial number
commandstringYesCommand name (see below)
valuevariesYesCommand value (type depends on command)

​
Supported Commands

​
set_temperature

Set the target temperature. Routes to the shared bucket.
Value typeDescriptionExample
numberSingle temperature in °C21.5
{"high": number, "low": number}Range mode (heat-cool){"high": 24, "low": 18}
{"serial": "02AB01AC012345678", "command": "set_temperature", "value": 21.5}

{"serial": "02AB01AC012345678", "command": "set_temperature", "value": {"high": 24, "low": 18}}
Temperatures are always in Celsius (4.5–32°C). The thermostat displays them in the user’s preferred scale. Temperature changes also set target_change_pending: true to wake the display.

​
set_mode

Set the HVAC mode. Routes to the shared bucket.
ValueDescription
"off"System off
"heat"Heating only
"cool"Cooling only
"heat-cool"Auto (maintains temperature range)
"emergency"Emergency heat (requires has_emer_heat)
{"serial": "02AB01AC012345678", "command": "set_mode", "value": "heat"}
The server checks device capabilities before applying the mode. Requesting heat on a cooling-only device returns a 400 error."eco" is not a valid mode here — use set_away instead to engage eco mode.

​
set_away

Enable or disable eco (away) mode via manual_eco_all in the structure bucket.
ValueDescription
trueEnable eco/away mode
falseReturn to normal operation
{"serial": "02AB01AC012345678", "command": "set_away", "value": true}
This uses manual_eco_all rather than the away field, because the firmware’s schedule preconditioning can revert away-triggered eco but respects manual eco. A manual_eco_timestamp is automatically set to the current time.

​
set_fan

Control the fan. Routes to the device bucket. Requires has_fan: true.
ValueDescription
"on"Run fan using stored duration preference (default 60 min)
"auto"Turn off fan timer (auto mode)
numberRun fan for this many seconds
{"serial": "02AB01AC012345678", "command": "set_fan", "value": "on"}

{"serial": "02AB01AC012345678", "command": "set_fan", "value": 1800}

​
set_eco_temperatures

Set the eco mode (away) temperature bounds. Routes to the device bucket. 
{
  "serial": "02AB01AC012345678",
  "command": "set_eco_temperatures",
  "value": {"high": 26.0, "low": 15.5}
}
FieldDescription
highUpper eco temperature in °C
lowLower eco temperature in °C

​
set_schedule

Replace the full weekly schedule. Routes to the schedule bucket (full replacement, not merge). 
{
  "serial": "02AB01AC012345678",
  "command": "set_schedule",
  "value": {
    "ver": 2,
    "schedule_mode": "HEAT",
    "days": {
      "0": [{"type": "HEAT", "time": 25200, "temp": 20.0}],
      "1": [{"type": "HEAT", "time": 25200, "temp": 20.0}]
    }
  }
}
Schedule format requirements:
  • ver must be 2
  • schedule_mode: "HEAT", "COOL", or "RANGE"
  • Day keys: "0" (Monday) through "6" (Sunday)
  • time: seconds from midnight (0–86399)
  • type: "HEAT", "COOL", or "RANGE"
  • RANGE type requires "temp-min" and "temp-max" instead of "temp"

​
set_schedule_mode

Change the active schedule mode without replacing the schedule. Routes to the shared bucket.
ValueDescription
"HEAT"Heat schedule
"COOL"Cool schedule
"RANGE"Heat-cool range schedule
{"serial": "02AB01AC012345678", "command": "set_schedule_mode", "value": "HEAT"}

​
set_device_setting

Set one or more cloud-writable device bucket fields. Routes to the device bucket. Only fields from the whitelist are accepted. 
{
  "serial": "02AB01AC012345678",
  "command": "set_device_setting",
  "value": {
    "temperature_scale": "F",
    "learning_mode": true
  }
}
CategoryFields
Safetylower_safety_temp_enabled, upper_safety_temp_enabled, lower_safety_temp, upper_safety_temp
Temperature locktemp_lock_on, temp_lock_pin_hash, temp_lock_high_temp, temp_lock_low_temp
Learninglearning_mode, preconditioning_enabled, preconditioning_active
Humiditytarget_humidity_enabled, target_humidity
Displaytemperature_scale, time_to_target, time_to_target_training_status
Sunblocksunlight_correction_enabled
Fanfan_timer_duration_minutes, fan_duty_cycle, fan_duty_start_time, fan_duty_end_time, fan_schedule_speed
Heat pumpheat_pump_aux_threshold_enabled, heat_pump_aux_threshold, heat_pump_comp_threshold_enabled, heat_pump_comp_threshold
Wiringequipment_type, heat_source
Hot waterhot_water_boost_time_to_end, hot_water_active
Filterfilter_reminder_enabled, filter_reminder_level
Localepostal_code, country_code

​
Response

​
Success (200 OK)

{
  "success": true,
  "data": {
    "object_key": "shared.02AB01AC012345678",
    "values": {
      "target_temperature": 21.5,
      "target_change_pending": true
    }
  }
}

​
Error (400 Bad Request)

{
  "success": false,
  "message": "Unknown command: set_foo"
}

{
  "success": false,
  "message": "Device does not support heating (can_heat=false)"
}

​
Error (500 Internal Server Error)

{
  "success": false,
  "message": "..."
}

​
Examples

curl -X POST http://your-server:8082/command \
  -H "Content-Type: application/json" \
  -d '{"serial": "02AB01AC012345678", "command": "set_temperature", "value": 21.5}'

​
Next Steps

GET /status

Query current device state

GET /api/devices

List all connected devices