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 enabled via the observer.enable configuration flag, the 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.

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.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
observer	object	Configuration of the BT LE observer Property Type Description enable boolean True if BT LE observer is enabled, false otherwise. Not applicable for battery-operated devices.

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