Shelly BLU TRV (Thermostatic Radiator Valve)

Short device name: SBTR-001AEU

Functional description

The device's main functionality is to maintain the set temperature in the room by precisely regulating the hot fluid flow trough the radiator.

There are additional functions (available when connected to a Shelly BLU Gateway):

• Schedules - the target temperature gan be automatically changed according to a preprogrammed schedule. Compatible with GEN2 schedules.
• Open window mode - if paired with a Shelly BLU Door Window - the target temperature is lowered while the door or window is opened.
• Child lock mode - if enabled, the target temperature cannot be changed from the rotarion of the TRV's ring.
• Display flip - the display can be flipped programmatically to reflect the orientation the installation.
• Display brightness - the brightness can be programmatically set.
• Temperature override mode - the temperature of the radiator can be temporary increased for fast heating of the room.
• Boost mode - similar to override, but sets the valve position to 100%, instead of the temperature.

In manual only mode, the available actions using the rotation ring are limited to:

What to do	How to do
Activate pairing mode	Single short press of the reset button (next to the battery cover)
ZigBee identify/stop identifying	Single short press the reset button (works only if the device is associated to a network)
Activate ZigBee pairing / Leave network	Press 3 times the reset button
Factory reset	Press and hold the reset button for more than 30 seconds
Show current temperature	Single short rotation of the ring
Set target temperature	Further longer rotation in any direction. If boost is active, the display would show on. Further rotation will cancel the boost and the target temperature will be set
Activate/Deactivate boost mode	Fast rotation from display off state (right=on, left=off)
Check battery level	Short and fast rotete 4 times in opposite directions when showint current temperature
Check pairing state (count)	Short rotation to the right from the battery level state
Activate BLE pairing	Short rotation to the right from previous state

The device emits BTHome data packets every 8 seconds with the currently set target temperature, measured temperature (aproximated using software to reflect the real room temperature) and the external temperature (if enabled and received).

Device specific settings

There are no device specific settings. Beacon mode is always active.

RPC channel service (_shOS_RPC_SVC_ID_)

Service UUID: 5f6d4f53-5f52-5043-5f53-56435f49445f

Characteristic	UUID	Type	Length	Properties	Function
_shOS_RPC_data___	5f6d4f53-5f52-5043-5f64-6174615f5f5f	byte	*	Read, Write bonded	Data sent or received trough the RPC channel
_shOS_RPC_tx_ctl_	5f6d4f53-5f52-5043-5f72-785f63746c5f	byte	*	Write	Data length to be sent
_shOS_RPC_rx_ctl_	5f6d4f53-5f52-5043-5f74-785f63746c5f	byte	*	Read, Notify, Indicate	Data length, available for rading. 0 == no data

Reading and writing data is possible on chinks, smaller or equal to the MTU size. Notify and Indicate are not used at the moment.

RPC commands

Note: This documentation covers the commands, sent trough GATT RPC Channel.

For information about how to use GATT RPC channel with Shelly BLU Gateway Gen3, refer to: https://shelly-api-docs.shelly.cloud/gen2/Devices/Gen3/ShellyBluGwG3#blutrvcall

More information about GATT RPC channel is available here: https://github.com/mongoose-os-libs/rpc-gatts/blob/master/README.md

Shelly.GetStatus

This method returns the status of all the components of the device.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required

Response

Property	Type	Description
sys	object	Information about the system Property Type Description time string Current time in the format HH:MM (24-hour time format in the current timezone with leading zero). null when time is not synced from NTP server. unixtime number Unix timestamp (in UTC) uptime number Time in seconds since last reboot ram_size number Total size of the RAM in the system in Bytes ram_free number Size of the free RAM in the system in Bytes cfg_rev number Configuration revision number state_rev number State revision number
temperature	object	Information about the temperature Property Type Description id number ID of temperature component tC number Temperature in degrees Celsius tF number Temperature in degrees Farenheit errors object Temperature component errors Reserved for future use Property Type Description
trv	object	TRV component information Property Type Description id number ID of TRV component pos number Valve position in percent steps number Stepper motor steps counter current_C number Current temperature in degrees Celsius target_C number Target temperature in degrees Celsius schedule_rev number Schedule revision counter errors object TRV component errors Only active errors Property Type Description not_calibrated string not_calibrated

Shelly.GetConfig

This method returns the configuration of all the components of the device.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required

Response

Property	Type	Description
sys	object	System component Property Type Description device object Device section Property Type Description name string Device name location object Location section Property Type Description lat number Geographical latitude lon number Geographical longitude ui object User interface section Property Type Description lock boolean Child lock t_units string C or F flip boolean Display flip brightness number Display brightness (1-7) ble object Location section Property Type Description interval_ms number BLE advertising interval beacon_count number BLE advertising beacon count in packet cfg_rev number Configuration version counter
temperature	object	Information about the temperature Property Type Description id number ID of temperature component offset number Temperature offset in degrees Celsius
trv	object	TRV component information Property Type Description id number ID of TRV component enable boolean Automatic regulation enabled override_enable boolean Temperature override enabled min_valve_position number Minimum valve position default_boost_duration number Default boos duration in seconds default_override_duration number Default override duration in seconds default_override_target_C number Default override target temperature in degrees Celsius flags object TRV component flags Only active flags Property Type Description floor_heating boolean Floor heatingnot mode accel boolean Accelerated heating mode auto_calibrate boolean Automatic calibration correction anticlog boolean Anti clog function

Shelly.FactoryReset

This method resets the configuration to its default state. Pairing information is preserved.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required

Response

null

Shelly.Reboot

This method reboots the device.

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required

Response

null

Shelly.GetDeviceInfo

This method returns a meaningful device information.

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required

Response

Property	Type	Description
id	string	Internal device name ID including the MAC address
mac	string	MAC address
fw_id	string	Firmware version ID
bl_ver	number	Bootloader version
app	number	Application name
model	string	Device model
batch	number	Production batch id
ver	string	Device version

Sys.SetTime

This method sets the device system time and time offset.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required
unixtime	number	Required
offset	number	Offset from GMT in seconds. Must equal to exact hours Required

Response

Returns null or error code

Trv.GetConfig

Get TRV configuration

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required

Response

Property	Type	Description
enable	boolean	true to enable the thermostat function Optional
flags	array of objects	Array of flags Optional. Property Type Description floor_heating boolean true for floor heating mode, If active, the TRV will use only the external temperature if available false otherwise. It is true by default. accel boolean true to enable accelerated heating, This mode aims to reach the target temperature faster, but overshot is possible auto_calibrate boolean true to enable the automatic calibration correction function, false otherwise. anticlog boolean true to enable anti clog prevention function. It would move the velve at least once in a week to prevent stuck valve, false otherwise. It is true by default.
min_valve_position	number	Minimal valve position in percent Optional

Trv.SetConfig

This method sets the configuration of the TRV.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required
config	array of objects	Configuration properties Property Type Description enable boolean true to enable the thermostat function Optional override_enable boolean true to enable Optional default_boost_duration number default boost duration in seconds Optional default_override_duration number default override duration in seconds Optional flags array of objects Array of flags Optional. Property Type Description floor_heating boolean true for floor heating mode, If active, the TRV will use only the external temperature if available false otherwise. It is true by default. accel boolean true to enable accelerated heating, This mode aims to reach the target temperature faster, but overshot is possible auto_calibrate boolean true to enable the automatic calibration correction function, false otherwise. anticlog boolean true to enable anti clog prevention function. It would move the velve at least once in a week to prevent stuck valve, false otherwise. It is true by default. min_valve_position number Minimal valve position in percent Optional default_override_target_C number Default override temperature in degrees Celsius Optional

Response

Returns null or error code.

TRV.SetTarget

Sets the target temperature in degrees Celsius.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required
target_C	number	Required

Response

Returns null or error code

TRV.SetFlag

Sets the target temperature in degrees Celsius.

Available TRV setting flags are: "floor_heating", "accel", "auto_calibrate", "anticlog"

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required
flag	string	Required

Response

Returns null or error code

TRV.ClearFlag

Clear the target temperature in degrees Celsius.

Request

Parameters:

Property	Type	Description
flag	string	Required

Response

Returns null or error code

TRV.Calibrate

Start stepper motor calibration process. Can take up to 10 seconds. The device will not respond to other commands during the calibration.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required

Response

Returns null or error code

The calibration success/fail is reported in the device status.

TRV.SetOverride

This method sets a temporary target temperature.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required
target_C	number	Temporaty target temperature in degrees Celsius Required
duration	number	Duration in seconds Required

Response

Returns null or error code

TRV.ClearOverride

This method terminates the previously started temperature override and returns the device to the normal target temperature.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required

Response

Returns null or error code

TRV.SetBoost

Temporary open the valve to maximum. Override target_C takes precedence over boost

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required
duration	number	Duration in seconds Optional

Response

Returns null or error code

TRV.ClearBoost

This method terminates the previously started boost state.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required

Response

Returns null or error code

TRV.SetExternalTemperature

Sets external temperature. With no parameters - use internal sensor instead of the external one.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required
t_C	number	External temperature in degrees Celsius Optional

Response

Returns null or error code

TRV.SetPosition

This method sets the valve position. Works only if the thermostat function is disabled in the config (Trv.SetConfig).

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required
pos	number	New valve position (0-100%) Required

Response

Returns null or error code.

Trv.AddScheduleRule

This method defines a new schedule rule. The timespecs format is Shelly Cron. 10 slots for schedule rules are available.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required
rule	array of objects	Arguments for the rule. Property Type Description enable boolean true to enable the execution of this job, false otherwise. It is true by default. timespec string As defined by cron. Note that leading 0s are not supported (e.g.: for 8 AM you should set 8 instead of 08). target_C number Target temperature to set when the condition in timespecs is met. Required

Response

Property	Type	Description
id	number	The id number of the created rule

Trv.UpdateScheduleRule

This method modifies an existing schedule rule.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required
rule_id	number	Rule id to modify
rule	array of objects	Arguments for the rule. Property Type Description enable boolean true to enable the execution of this job, false otherwise. It is true by default. timespec string As defined by cron. Note that leading 0s are not supported (e.g.: for 8 AM you should set 8 instead of 08). target_C number Target temperature to set when the condition in timespecs is met. Required

Response

Property	Type	Description
id	number	The id number of the created rule

Trv.RemoveScheduleRule

Remove a schedule rule.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required
rule_id	number	The rule id to remove Required

Response

Returns null or error code.

Trv.ListScheduleRules

List schedule rules.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required

Response

Returns a list of defined rules or null or error code.

Trv.ShowMessage

Shows a short running text on the display. Up to 10 characters.

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required
message	string	Text to show Required

Response

Returns null or error code

Trv.PairingComplete

Shows the result of an operation (e.g. pairing) on the display with "YES" or "NO".

Request

Parameters:

Property	Type	Description
id	number	ID of component. Always 0 Required
success	boolean	true or false Required

Response

Returns null or error code

Examples

Note: To execute the commands using Shelly BLU Gateway Gen3, refer to: https://shelly-api-docs.shelly.cloud/gen2/Devices/Gen3/ShellyBluGwG3#blutrvcall

Example call using BLU GW: https://shelly-api-docs.shelly.cloud/gen2/Devices/Gen3/ShellyBluGwG3/#blutrvcall-example

or

<gateway_ip_address>/rpc/BluTrv.call?id=<TRV_component_id>&method=<RPC_command>&params=<body_of_command_params>

TRV.SetConfig example

Example

{
  "id": 0,
  "config": {
    "enable": true,
    "override_enable": true,
    "default_boost_duration": 300,
    "default_override_duration": 300,
    "name": "abc",
    "flags": {
      "floor_heating": false,
      "accel": false,
      "auto_calibrate": true,
      "anticlog": true
    },
    "min_valve_position": 0,
    "default_override_target_C": 30
  }
}

Response

TRV.SetConfig HTTP GET Response

null

TRV.SetConfig Curl Response

{
  "id": 1,
  "params": null
}

TRV.SetConfig Mos Response

null

TRV.GetConfig example

Example

{
  "id": 0
}

Response

TRV.GetConfig HTTP GET Response

{
  "id": 0,
  "enable": true,
  "override_enable": true,
  "min_valve_position": 0,
  "default_boost_duration": 1800,
  "default_override_duration": 2147483647,
  "default_override_target_C": 8,
  "flags": []
}

TRV.GetConfig Curl Response

{
  "id": 1,
  "params": {
    "id": 0,
    "enable": true,
    "override_enable": true,
    "min_valve_position": 0,
    "default_boost_duration": 1800,
    "default_override_duration": 2147483647,
    "default_override_target_C": 8,
    "flags": []
  }
}

TRV.GetConfig Mos Response

{
  "id": 0,
  "enable": true,
  "override_enable": true,
  "min_valve_position": 0,
  "default_boost_duration": 1800,
  "default_override_duration": 2147483647,
  "default_override_target_C": 8,
  "flags": []
}

TRV.GetStatus example

Example

{
  "id": 0
}

Response

TRV.GetStatus HTTP GET Response

{
  "id": 0,
  "pos": 0,
  "steps": 0,
  "current_C": 21.76,
  "target_C": 9.19,
  "schedule_rev": 0,
  "errors": [
    "not_calibrated"
  ]
}

TRV.GetStatus Curl Response

{
  "id": 1,
  "params": {
    "id": 0,
    "pos": 0,
    "steps": 0,
    "current_C": 21.76,
    "target_C": 9.19,
    "schedule_rev": 0,
    "errors": [
      "not_calibrated"
    ]
  }
}

TRV.GetStatus Mos Response

{
  "id": 0,
  "pos": 0,
  "steps": 0,
  "current_C": 21.76,
  "target_C": 9.19,
  "schedule_rev": 0,
  "errors": [
    "not_calibrated"
  ]
}

TRV.Calibrate example

Example

{
  "id": 0
}

Response

TRV.Calibrate HTTP GET Response

null

TRV.Calibrate Curl Response

{
  "id": 1,
  "params": null
}

TRV.Calibrate Mos Response

null

Sys.GetConfig example

Example

{
  "id": 0
}

Response

Sys.GetConfig HTTP GET Response

{
  "device": {
    "name": ""
  },
  "location": {
    "lat": 0,
    "lon": 0
  },
  "ui": {
    "lock": false,
    "t_units": "C",
    "flip": false,
    "brightness": 7
  },
  "ble": {
    "interval_ms": 333,
    "beacon_count": 5
  },
  "cfg_rev": 1
}

Sys.GetConfig Curl Response

{
  "id": 1,
  "params": {
    "device": {
      "name": ""
    },
    "location": {
      "lat": 0,
      "lon": 0
    },
    "ui": {
      "lock": false,
      "t_units": "C",
      "flip": false,
      "brightness": 7
    },
    "ble": {
      "interval_ms": 333,
      "beacon_count": 5
    },
    "cfg_rev": 1
  }
}

Sys.GetConfig Mos Response

{
  "device": {
    "name": ""
  },
  "location": {
    "lat": 0,
    "lon": 0
  },
  "ui": {
    "lock": false,
    "t_units": "C",
    "flip": false,
    "brightness": 7
  },
  "ble": {
    "interval_ms": 333,
    "beacon_count": 5
  },
  "cfg_rev": 1
}

Sys.SetConfig example

Example

{
  "id": 0,
  "config": {
    "sys": {
      "device": {
        "name": ""
      },
      "location": {
        "lat": 43.0866,
        "lon": 25.2695
      },
      "ui": {
        "lock": false,
        "t_units": "C",
        "flip": false,
        "brightness": 7
      },
      "ble": {
        "interval_ms": 333,
        "beacon_count": 5
      },
      "cfg_rev": 2
    },
    "temperature:0": {
      "id": 0,
      "offset_C": 0
    },
    "trv:0": {
      "id": 0,
      "enable": true,
      "override_enable": false,
      "min_valve_position": 0,
      "default_boost_duration": 1800,
      "default_override_duration": 2147483647,
      "default_override_target_C": 8,
      "flags": []
    }
  }
}

Response

Sys.SetConfig HTTP GET Response

null

Sys.SetConfig Curl Response

{
  "id": 1,
  "src": "shellyplus2pm-a8032ab636ec",
  "params": null
}

Sys.SetConfig Mos Response

null

BTHome data

BTHome sensor data objects

id	name	data type	scale factor	description
0x00	packet id	uint8	1	revolving counter
0x01	battery	uint8	1	battery level in percent (0-100)
0x3A	button	uint8	1	button press event (Only when button is pressed)
0x45	temperature	sint16	0.1	target temperature in °C
0x45	temperature	sint16	0.1	current temperature in °C
0x45	temperature	sint16	0.1	external temperature in °C (only if available)

Button press events

id	name	example
0x01	single press	0x3A01
0x80	button hold	0x3AFE

ZigBee cluster data objects

General section

Cluster 0x0000 Basic

Attribute id	description
0x0000	ZCL version
0x0004	manufacturer name
0x0005	model identifier
0x0007	power source
0x000A	product code
0x000D	serial number
0x4000	sw build id
0xFFFD	cluster revision

Cluster 0x0001 Power Configuration

Attribute id	description
0x0021	battery percentage remaining

Cluster 0x0003 Identify

Attribute id	description
0xFFFD	cluster revision (client/server)
0x0000	identify time (server)

HVAC section

Cluster 0x0201 Thermostat

Attribute id	description
0x0000	local temperature
0x0003	abs min heat setpoint limit0x0004abs max heat setpoint limit
0x0011	occupied cooling setpoint
0x0012	occupied heating setpoint
0x0014	unoccupied heating setpoint
0x0015	min heat setpoint limit
0x0016	max heat setpoint limit
0x001B	control sequence of operation
0x001E	thermostat running mode
0x001C	system mode

ZLL section

Cluster 0x1000 ZLL Commissioning

Attribute id	description
0xFFFD	cluster revision