Skip to main content
Version: 1.0

Shelly BLU Gateway Gen3

The following components are available in Shelly BLU Gateway Gen3:

BluTrv​

Methods​

BluTrv.GetStatus​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance

Response:

Find the BluTrv.GetStatus response properties in status section

BluTrv.GetConfig​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance

Response:

Find the BluTrv.GetConfig response properties in config section

BluTrv.SetConfig​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance

config

object

Configuration that the method takes

Response:

PropertyTypeDescription

restart_required

boolean

BluTrv.Delete​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance

Response:

null on success or error

BluTrv.Call​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance

method

string

required RPC method to invoke on the TRV device

params

object

optional RPC parameters to invoke the selected method with

Response:

Result of the RPC call. Response may be delayed up to one minute although normally should be recieved within 10 seconds.

BluTrv.GetRemoteStatus​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance

Response:

Object containing remote device status, see example below.

BluTrv.GetRemoteConfig​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance

Response:

Object containing remote device config, see example below.

BluTrv.GetRemoteDeviceInfo​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance

Response:

Object containing remote device info, see example below.

BluTrv.UpdateFirmware​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance

bootloader

boolean

optional Defaults to false is not provided

url

string

optional If not specified TRV device will be updated with the latest firmware, also depending on the bootloader flag

Response:

null on success or error

BluTrv.CheckForUpdates​

Request

This method doesn't take any arguments.

Response

PropertyTypeDescription

fw_id

string

Version of the latest firmware in the repository

Associations​

The Shelly BLU Gateway Gen3 supports Associtions of BLUTRV devices with the gateway and BTHome temperature and/or window sensors (BLUHT, BLUDW) with a BLUTRV device. The Associations procedure can be started by pressing the pair button on the gateway, through an RPC from the BLE namespace or can be automatically triggered if already associted BLUTRV device enters pairing mode.

Status​

PropertyTypeDescription

id

number

Id of the BluTrv component instance

target_C

number

TRV device target temperature in Celsius from remote status

current_C

number

TRV device current temperature in Celsius from remote status

pos

number

TRV device valve position percentage from remote status

errors

array of strings

Descriptive names of possible errors on the TRV device from remote status

rssi

number

Last received RSSI of the TRV device

battery

number

Last received battery percentage of the TRV device

packet_id

number

Last received packet_id from the TRV device

last_updated_ts

number

Last received packet from the TRV device timestamp

paired

boolean

Is TRV device paired with the gateway (should laways be true)

rpc

boolean

Is TRV device RPC capable (should laways be true)

rsv

number

The value of the 6-bit state counter received from the TRV device. When changed remote state (config, status and device_info) is updated and change is reflected here. -1 if no data is yet received from the TRV device

note

The properties target_C, current_C, pos and errors are advised only for Home Assistant integration purposes and are not the recommended way to track TRV device status. They are included in BluTrv.GetStatus response and will trigger status changes but that is not true for other TRV device status properties. To obtain full TRV device status you still need to call BluTrv.GetRemoteStatus when rsv changes.

Configuration​

PropertyTypeDescription

id

number

Id of the BluTrv component instance

addr

string

read-only The bluetooth address of the TRV device

name

string or null

User defined name of the BluTrv component

key

string or null

Encrytion key of the BluTrv compoennt. Must be set if Device is encypted

trv

string

read-only Linked BTHome TRV device (internal use)

temp_sensors

array of strings

read-only Associated Temperature sensor from a BLUH&T device. Can be at most one

dw_sensors

array of strings

read-only Associated Window sensors from BLUDoorWindow device. Can be many

meta

object or null

Object for storing meta data (internal use)

Webhook Events​

There are two events related to the BluTrv component that can trigger webhooks:

  • blutrv.temperature_change - produced when the temperature reported in the current_C field of remote status of the component changes with more than 0.5 degrees Celsius.

blutrv.temperature_change supports two attributes, that can be used to compose conditional webhooks:

PropertyTypeDescription

tC

number

New temperature in Celsius

tF

number

New temperature in Fahrenheit

  • blutrv.position_change - produced when the valve position reported in the remote status of the component changes with more than 5 percent.

blutrv.position_change supports one attribute, that can be used to compose conditional webhooks:

PropertyTypeDescription

position

number

New valve position in percent

Examples​

BluTrv.GetStatus example​

http://192.168.33.1/rpc/BluTrv.GetStatus?id=200

Response

{
  "id": 200,
  "target_C": 4.3,
  "current_C": 24.7,
  "pos": 0,
  "errors": [
    "not_calibrated"
  ],
  "rssi": -41,
  "battery": 100,
  "packet_id": 64,
  "last_updated_ts": 1736161958,
  "paired": true,
  "rpc": true,
  "rsv": 19
}

BluTrv.GetConfig example​

http://192.168.33.1/rpc/BluTrv.GetConfig?id=200

Response

{
  "id": 200,
  "addr": "28:68:47:f0:2a:b9",
  "name": null,
  "key": null,
  "trv": "bthomedevice:200",
  "temp_sensors": [
    "bthomesensor:200"
  ],
  "dw_sensors": [],
  "meta": null
}

BluTrv.SetConfig example​

http://192.168.33.1/rpc/BluTrv.SetConfig?id=200&config={"name":"mytrv"}

Response

{
  "restart_required": false
}

BluTrv.Delete example​

http://192.168.33.1/rpc/BluTrv.Delete?id=200

Response

null

BluTrv.Call example​

http://192.168.33.1/rpc/BluTrv.Call?id=200&method="TRV.SetTarget"&params={"id":0,"target_C":22}

Response

null

BluTrv.GetRemoteStatus example​

http://192.168.33.1/rpc/BluTrv.GetRemoteStatus?id=200

Response

{
  "v": 17,
  "ts": 1728654569,
  "status": {
    "sys": {
      "time": "16:49",
      "unixtime": 1728654568,
      "last_sync_ts": 1728654544,
      "offset": 10800,
      "uptime": 686741,
      "ram_size": 29736,
      "ram_free": 11896,
      "cfg_rev": 5,
      "state_rev": 17
    },
    "temperature:0": {
      "id": 0,
      "tC": 23.71,
      "tF": 74.69,
      "errors": []
    },
    "trv:0": {
      "id": 0,
      "pos": 0,
      "steps": 5938,
      "current_C": 24.09,
      "target_C": 22,
      "override": {
        "started_at": 1728654567
      },
      "schedule_rev": 0,
      "errors": [
        "not_calibrated"
      ]
    }
  }
}

BluTrv.GetRemoteConfig example​

http://192.168.33.1/rpc/BluTrv.GetRemoteConfig?id=200

Response

{
  "v": 17,
  "ts": 1728654569,
  "config": {
    "sys": {
      "device": {
        "name": ""
      },
      "location": {
        "lat": 43.0866,
        "lon": 25.2695
      },
      "ui": {
        "lock": false,
        "t_units": "C",
        "flip": false,
        "brightness": 7
      },
      "ble": {
        "interval_ms": 73,
        "beacon_count": 4
      },
      "cfg_rev": 5
    },
    "temperature:0": {
      "id": 0,
      "offset_C": 0
    },
    "trv:0": {
      "id": 0,
      "enable": true,
      "min_valve_position": 0,
      "default_override_target_C": 8,
      "flags": []
    }
  }
}

BluTrv.GetRemoteDeviceInfo example​

http://192.168.33.1/rpc/BluTrv.GetRemoteDeviceInfo?id=200

Response

{
  "v": 17,
  "ts": 1728654569,
  "device_info": {
    "id": "shellyblutrv-ecd5b5a7db28",
    "mac": "ECD5B5A7DB28",
    "fw_id": "20241004-125638/main@4b7c4712+",
    "bl_ver": 1,
    "app": "BluTRV",
    "model": "BluTRV",
    "batch": "1",
    "ver": "0.0.1a1"
  }
}

BluTrv.UpdateFirmware example​

http://192.168.33.1/rpc/BluTrv.UpdateFirmware?id=200

Response

null

BluTrv.CheckForUpdates example​

http://192.168.33.1/rpc/BluTrv.CheckForUpdates

Response

{
  "fw_id": "20241004-125638/main@4b7c4712+"
}