Skip to main content
Version: 1.0

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:

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

Observer​

caution

Observer is obsoleted as of 1.5.0-beta1. Since 1.5.0-beta1 observer functionality is automatic using the Enhanced Scan Manager.

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. The observer functionality is applicable for the CloudRelay and BTHome features.

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 relaying received advertisement packets to Shelly Cloud service, to enable scene triggers. It publicly exports List and ListInfos methods, while other functions are internal only. Prior to 1.5.0-beta1 CloudRelay functionality required the Bluetooth Observer to be enabled. Since 1.5.0-beta1 necessary functionality is enabled automatically if needed.

note

CloudRelay is not supported on Gen 4 devices in Zigbee mode.

Bluetooth Scan​

Shelly devices hardware supports only one running Bluetooth scan at a given moment, but several device features require using such scan and a scan manager is needed. The scan manager serves as an arbiter of the scan requests and clients can request receiving the results of the scan. Currently Bluetooth Cloud Relay, BTHome and the Scripts BLE Scanner can act as Scan Manager clients. The Scan Manager was rewritten and improved since 1.5.0-beta1. The Scan Manager interface itself is not exposed externally but the two implementaions introduce some differences in the behavior of clients.

note

Bluetooth Scan is not supported on Gen 4 devices in Zigbee mode.

ScanManager​

Effective prior to 1.5.0-beta1

This Scan Manager is based on the concept of scan owner. The first client requesting a Bluettoth scan becomes the owner and further requests will fail, but the clients can subscribe for events of the currently running scan. The owner is cleared when the scan ends. The owner also determines the scan options and they cannot be changed until ownership is released. With this Scan Manager Cloud Relay and BTHome share the scan with the Observer functionality and Scripts compete for the scan.

Enhanced Scan Manager​

Effective since 1.5.0-beta1

This Scan Manager effectively is the owner of the scan and it starts and stops it as needed. Clients request delivery of scan events and the manager keeps track and tries to satisfy all requests, starting a scan and merging the options supplied with each request effectively applying the most aggressive combination. A client needs to submit a scan request and cannot just subscribe to existing scan. With this Scan Manager Cloud Relay and BTHome transparently for the user submit scan requests when needed and share the same scan options. In Scripts each script can submit a scan request with the BLE.Scanner.Start method and receive scan events after subscribing. The Scan Manager will adjust the scan parameters according to the options supplied and its merge algorithm. In some cases if there are more than one scan requests the effective scan options may be different from the requested.

Scan Options​

PropertyTypeDescription

duration_ms

number

duration of the scan in ms, -1 for perpetual (continuous) scan. Defaults to 5000.

active

boolean

start an active scan if true, or passive if false. Defaults to false.

interval_ms

number

scan interval in ms. Defaults to 241.

window_ms

number

scan window in ms. Defaults to 61 in Scripts.

since 1.5.0-beta1
PropertyTypeDescription

rssi_thr

number

RSSI threshold for delivered scan results, filtered to those with RSSI greater than the threshold. Defaults to 0, meaning no filtering.

Methods​

BLE.SetConfig​

Properties:

PropertyTypeDescription

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:

PropertyTypeDescription

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:

PropertyTypeDescription

offset

number

optional offset of the first item to return, defaults to 0

Response:

PropertyTypeDescription

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

PropertyTypeDescription

MAC

object

Information about the device received in its last received advertisement. Device MAC address is used as the object key

PropertyTypeDescription

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:

PropertyTypeDescription

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.

PropertyTypeDescription

enable

boolean

True if bluetooth is enabled, false otherwise

rpc

object

Configuration of the rpc service

PropertyTypeDescription

enable

boolean

True if rpc service is enabled, false otherwise

as of 1.6.0-beta1
PropertyTypeDescription

keep_running

boolean

When set to true changing configuration will require restart. When set to false or absent change will be applied runtime

Obsoleted as of 1.5.0-beta1
PropertyTypeDescription

observer

object

Configuration of the BT LE observer

PropertyTypeDescription

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. Prior to 1.6.0-beta1 changing configuration requires restart. Since restart is not required, see also note above.

note

Runtime change of bluetooth status introduced with 1.6.0-beta1 is handled transperantly in BTHome, Cloud Relay and Scirpts stopping and starting initiated bluetooth scans as needed.

Status​

PropertyTypeDescription

blutrv_assoc

object

BluTrvAssociations information, present only when associations are active

PropertyTypeDescription

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​

http://192.168.33.1/rpc/BLE.GetStatus

Response

{}

BLE.GetConfig example​

http://192.168.33.1/rpc/BLE.GetConfig

Response

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

BLE.SetConfig example​

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

Response

{
  "restart_required": true
}

BLE.CloudRelay.List example​

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

Response

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

BLE.CloudRelay.ListInfos example​

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

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​

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

Response

null