Bluetooth Low Energy

The Bluetooth Low Energy component is called BLE. It handles bluetooth services of a device. The Bluetooth Low Energy component uses BLE as RPC namespace and provides the methods:

• BLE.GetConfig to obtain the component's configuration
• BLE.SetConfig to update the component's configuration
• BLE.GetStatus to obtain the component's status

It uses the key ble when enumerated in objects including multiple component payloads, like Shelly.GetStatus.

Observer

To support Shelly Bluetooth peripheral devices, the BLE component can act as a perpetual BT LE Observer. When bluetooth is enabled via the enable flag and at least one peripheral device is added to Cloud Relay, or if BTHome functionality is available on the Shelly device and there is at least one created BTHome device, the Shelly device will run a constant passive Bluetooth LE scan and relay received advertisement packets to Shelly Cloud service, to enable scene triggers.

note

Enabling the observer relay functionality might impact BLE advertisement scanner in scripts. A requested interval and window for scanning in scripting might get adjusted to allow for the coexistence of both functionalities.

note

Observer is not applicable for battery-operated devices.

CloudRelay

CloudRelay is a feature of the BLE component supporting Shelly BLU devices managed by the Shelly Cloud, providing information advertised by these devices to the Cloud. It publicly exports List and ListInfos methods, while other functions are internal only.

Methods

BLE.SetConfig

Properties:

Property	Type	Description
config	object	Configuration that the method takes

Find more about the config properties in config section

BLE.GetConfig

Find the BLE.GetConfig response properties in config section

BLE.GetStatus

Find more about the status response properties in status section

BLE.CloudRelay.List

Returns a list of MAC adresses for the devices managed by the Cloud.

Request:

The method doesn't take any paramters.

Response:

Property	Type	Description
rev	number	Internal revision of the list
addrs	array of strings	The list of MAC addresses for the managed devices

BLE.CloudRelay.ListInfos

Returns extended information about data received from the devices managed by the Cloud. The response is paginated.

Request:

Property	Type	Description
offset	number	optional offset of the first item to return, defaults to 0

Response:

Property	Type	Description
ts	number	Unix timestamp of the repsonse
offset	number	Offset in the list of the first item in the current page
count	number	Number of items in the current page
total	number	Total number of items in the list
devices	array of objects	Property Type Description MAC object Information about the device received in its last received advertisement. Device MAC address is used as the object key Property Type Description name string or null Device name from the advertisement taken from localname. Will be populated only during active scans model number Internal model id of the device. Will be populated only during active scans, otherwise will show 0 which is invalid model id sdata object Service data from the advertisement. Object keys are UUIDs of the service data and values are their base64 encoded contents. If not present object will be empty. mdata object Manufacturer data from the advertisement. Object keys are manufacturer UUIDs and values are the base64 encoded contents of the data. If not present object will be empty. last_seen number Unix timestamp of the last recieved advertisement

BLE.StartBluTrvAssociations

note

Available only on devices that support BLUTRV devices. Currently Shelly BLU Gateway Gen3

Associate BLUTRV device with the gateway or associate already associated BLUTRV device with BTHome temperature and/or window sensors (BLUHT, BLUDW) which can either be existing or will be added.

Request:

Property	Type	Description
blutrv_id	number	optional If not specified discover and associate new BLUTRV device with the gateway or Id of the BluTrv component instance to perform sensor associations (device doesn't need to be in pairing mode in this case)
duration	number	optional Max discovery duration, seconds. Defaults to 30 if not provided.
rssi_thr	number	optional Defaults to -80 if not provided.

Response:

null on success or error

StartBluTrvAssociations will add a status entry when active and will emit status change notifications on start and end.

AssociationsStarted status change:

{"blutrv_assoc":{"duration":30,"started_at":1729259344}}

AssociationsEnded status change:

{"blutrv_assoc":null}

Configuration

The configuration of the Bluetooth Low Energy component shows whether the bluetooth connection is enabled.

Property	Type	Description
enable	boolean	True if bluetooth is enabled, false otherwise
rpc	object	Configuration of the rpc service Property Type Description enable boolean True if rpc service is enabled, false otherwise

note

Currently only rpc service is implemented, but a global enable flag is maintained for possible other future BLE functionality implementation. If either of the enable flags is set to false the device is not advertised. Changing the configuration requires restart.

Status

Property	Type	Description
blutrv_assoc	object	BluTrvAssociations information, present only when associations are active Property Type Description duration integer Duration of the current associations proecdure in seconds started_at integer Unix timestamp of the start of the associations procedure

Examples

BLE.GetStatus example

BLE.GetStatus HTTP GET Request

http://192.168.33.1/rpc/BLE.GetStatus

BLE.GetStatus Curl Request

curl -X POST -d '{"id":1,"method":"BLE.GetStatus"}' http://${SHELLY}/rpc

BLE.GetStatus Mos Request

mos --port ${PORT} call BLE.GetStatus

Response

BLE.GetStatus HTTP GET Response

{}

BLE.GetStatus Curl Response

{
  "id": 1,
  "src": "shellyplus1pm-441793ce3f08",
  "params": {}
}

BLE.GetStatus Mos Response

{}

BLE.GetConfig example

BLE.GetConfig HTTP GET Request

http://192.168.33.1/rpc/BLE.GetConfig

BLE.GetConfig Curl Request

curl -X POST -d '{"id":1,"method":"BLE.GetConfig"}' http://${SHELLY}/rpc

BLE.GetConfig Mos Request

mos --port ${PORT} call BLE.GetConfig

Response

BLE.GetConfig HTTP GET Response

{
  "enable": true,
  "rpc": {
    "enable": true
  }
}

BLE.GetConfig Curl Response

{
  "id": 1,
  "src": "shellyplus1pm-441793ce3f08",
  "params": {
    "enable": true,
    "rpc": {
      "enable": true
    }
  }
}

BLE.GetConfig Mos Response

{
  "enable": true,
  "rpc": {
    "enable": true
  }
}

BLE.SetConfig example

BLE.SetConfig HTTP GET Request

http://192.168.33.1/rpc/BLE.SetConfig?config={"enable":true,"rpc":{"enable":true}}

BLE.SetConfig Curl Request

curl -X POST -d '{"id":1,"method":"BLE.SetConfig","params":{"config":{"enable":true,"rpc":{"enable":true}}}}' http://${SHELLY}/rpc

BLE.SetConfig Mos Request

mos --port ${PORT} call BLE.SetConfig '{"config":{"enable":true,"rpc":{"enable":true}}}'

Response

BLE.SetConfig HTTP GET Response

{
  "restart_required": true
}

BLE.SetConfig Curl Response

{
  "id": 1,
  "src": "shellyplus1pm-441793ce3f08",
  "params": {
    "restart_required": true
  }
}

BLE.SetConfig Mos Response

{
  "restart_required": true
}

BLE.CloudRelay.List example

BLE.CloudRelay.List HTTP GET Request

http://192.168.33.1/rpc/BLE.CloudRelay.List

BLE.CloudRelay.List Curl Request

curl -X POST -d '{"id":1,"method":"BLE.CloudRelay.List"}' http://${SHELLY}/rpc

BLE.CloudRelay.List Mos Request

mos --port ${PORT} call BLE.CloudRelay.List

Response

BLE.CloudRelay.List HTTP GET Response

{
  "rev": 8,
  "addrs": [
    "5c:c7:c1:f0:db:60"
  ]
}

BLE.CloudRelay.List Curl Response

{
  "id": 1,
  "src": "shellyplus1pm-441793ce3f08",
  "params": {
    "rev": 8,
    "addrs": [
      "5c:c7:c1:f0:db:60"
    ]
  }
}

BLE.CloudRelay.List Mos Response

{
  "rev": 8,
  "addrs": [
    "5c:c7:c1:f0:db:60"
  ]
}

BLE.CloudRelay.ListInfos example

BLE.CloudRelay.ListInfos HTTP GET Request

http://192.168.33.1/rpc/BLE.CloudRelay.ListInfos

BLE.CloudRelay.ListInfos Curl Request

curl -X POST -d '{"id":1,"method":"BLE.CloudRelay.ListInfos"}' http://${SHELLY}/rpc

BLE.CloudRelay.ListInfos Mos Request

mos --port ${PORT} call BLE.CloudRelay.ListInfos

Response

BLE.CloudRelay.ListInfos HTTP GET Response

{
  "ts": 1732804839,
  "offset": 0,
  "count": 1,
  "total": 1,
  "devices": [
    {
      "5c:c7:c1:f0:db:60": {
        "name": null,
        "model": 0,
        "sdata": {
          "fcd2": "RAAVAWQ6AQ=="
        },
        "mdata": {},
        "last_seen": 1732804835
      }
    }
  ]
}

BLE.CloudRelay.ListInfos Curl Response

{
  "id": 1,
  "src": "shellyplus1pm-441793ce3f08",
  "params": {
    "ts": 1732804839,
    "offset": 0,
    "count": 1,
    "total": 1,
    "devices": [
      {
        "5c:c7:c1:f0:db:60": {
          "name": null,
          "model": 0,
          "sdata": {
            "fcd2": "RAAVAWQ6AQ=="
          },
          "mdata": {},
          "last_seen": 1732804835
        }
      }
    ]
  }
}

BLE.CloudRelay.ListInfos Mos Response

{
  "ts": 1732804839,
  "offset": 0,
  "count": 1,
  "total": 1,
  "devices": [
    {
      "5c:c7:c1:f0:db:60": {
        "name": null,
        "model": 0,
        "sdata": {
          "fcd2": "RAAVAWQ6AQ=="
        },
        "mdata": {},
        "last_seen": 1732804835
      }
    }
  ]
}

BLE.StartBluTrvAssociations example

BLE.StartBluTrvAssociations HTTP GET Request

http://192.168.33.1/rpc/BLE.StartBluTrvAssociations?blutrv_id=200&duration=120&rssi_thr=-80

BLE.StartBluTrvAssociations Curl Request

curl -X POST -d '{"id":1,"method":"BLE.StartBluTrvAssociations","params":{"blutrv_id":200,"duration":120,"rssi_thr":-80}}' http://${SHELLY}/rpc

BLE.StartBluTrvAssociations Mos Request

mos --port ${PORT} call BLE.StartBluTrvAssociations '{"blutrv_id":200,"duration":120,"rssi_thr":-80}'

Response

BLE.StartBluTrvAssociations HTTP GET Response

null

BLE.StartBluTrvAssociations Curl Response

{
  "id": 1,
  "src": "shellyblugwg3-3030f9ed6698",
  "params": null
}

BLE.StartBluTrvAssociations Mos Response

null