Skip to main content
Version: 1.0

Shelly BLU Gateway Gen3

Shelly BLU Gateway Gen3 is a device with a special purpose to serve as a gateway for controlling certain Shelly BLU Devices. It was initially developed for Shelly BLU TRV.

The following components are available in Shelly BLU Gateway Gen3:

Associations​

The Shelly BLU Gateway Gen3 supports Associations of supported devices. Currently Shelly BLU TRV. The associations for BLU TRV will either add a BluTrv component to the gateway or associate an existing with BTHome temperature and/or window sensors (BLUHT, BLUDW). The Associations procedure can be started, through the BLE.StartAssociations RPC or by pressing the pair button on the gateway, which is reserved only for the BLU TRV and for the BLU TRV can be automatically triggered if already associated BLU TRV device enters pairing mode to associate BLUHT or BLUDW sensors.

BluTrv​

This is a special component corresponding to the Shelly BLU TRV device. It exports its specific functionality.

Methods​

BluTrv.GetStatus​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance. Required

Response:

Find the BluTrv.GetStatus response properties in its status section

BluTrv.GetConfig​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance. Required

Response:

Find the BluTrv.GetConfig response properties in its config section

BluTrv.SetConfig​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance. Required

config

object

Configuration that the method takes. Required

Response:

PropertyTypeDescription

restart_required

boolean

BluTrv.Delete​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance. Required

Response:

null on success or error

BluTrv.Call​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance. Required

method

string

RPC method to invoke on the TRV device. Required

params

object

RPC parameters to invoke the selected method with. Optional

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. Required

Response:

Object containing remote device status, see example below.

BluTrv.GetRemoteConfig​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance. Required

Response:

Object containing remote device config, see example below.

BluTrv.GetRemoteDeviceInfo​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance. Required

Response:

Object containing remote device info, see example below.

BluTrv.UpdateFirmware​

Request:

PropertyTypeDescription

id

number

Id of the BluTrv component instance. Required

bootloader

boolean

Flag to request bootloader update instead of firmware. Defaults to false. Optional

url

string

URL to download firmware (or bootloader) from. Default is the latest. Optional

Response:

null on success or error

BluTrv.CheckForUpdates​

Request

This method takes no parameters.

Response

PropertyTypeDescription

fw_id

string

Version of the latest firmware in the repository

BluTrv 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

key

boolean

Encryption key configured

paired

boolean

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

rpc

boolean

Is TRV device RPC capable (should always 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.

BluTrv 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

AES encryption key of the BluTrv component. Must be set if Device is encrypted. Not displayed in GetConfig response.

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)

BluTrv 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,
  "key": false,
  "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,
  "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+"
}