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.

BLE Security and Bonding​

(Since firmware 2.0.0)

RPC over Bluetooth requires pairing for all devices (except during the initial setup window). The device uses GATT security with encryption and authentication for all BLE RPC connections.

To use BLE RPC outside the initial setup window:

  1. Enable the RPC service by setting rpc.enable to true in the configuration
  2. Call BLE.StartPairing to allow new devices to bond

Bonding (Pairing)​

The device supports bonding with up to 20 BLE clients. Bonding establishes a trusted relationship between the Shelly device and a BLE client, storing encryption keys for future connections.

Bonding process:

  1. Client initiates a connection to the Shelly device
  2. Device uses "Just Works" pairing method
  3. Upon successful pairing, bond information is stored on both devices
  4. Subsequent connections from the bonded client are automatically authenticated

Bond storage limits:

  • Maximum of 20 bonded devices
  • When the limit is reached, new bonding attempts will fail until an existing bond is removed
  • Bonds persist across device reboots
  • Factory reset clears all stored bonds

Provisioning Integration​

During the device provisioning window, pairing is not required for BLE RPC connections:

  • pending and confirmed states: RPC connections are accepted without pairing
  • complete and locked states: Pairing is enforced for all BLE RPC connections

This allows initial device setup via Bluetooth without requiring pairing, while ensuring security once the device is fully provisioned.

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.

Date/Time Broadcast​

Effective since 2.0.0-beta1

Some BLU devices need to be time-aware and need a method to automatically sync their internal clock to the correct wall time. To make this possible, Shellies which have BTHome devices registered, or are enrolled as a Cloud BLE Gateway for any BLU devices will periodically send a "current time" beacon message. The message includes information about the current date, time and timezone settings in a manufacturer-specific AD structure with Manufacturer ID 0xFCD2, with the following format, where all multi-byte numbers are little-endian:

OffsetLengthTypeMeaning
01byte0x0d, Time and Timezone info block identifier
14uint32Current UNIX timestamp
54int32Standard timezone UTC offset, seconds
94uint32UNIX timestamp of DST start for current year
134uint32UNIX timestamp of DST end for current year
174int32DST shift in seconds

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.

Scan Filters​

since 2.0.0

Available on Gen3, Gen4 and Pro devices.
Exposed only in scripts through the BLE.Scanner.start

PropertyTypeDescription

filters

array of filter objects

Collection of filters to match against. Match is done by the Scanner and only matching results are delivered to clients. Each client can specify its own filters. A match is considered when any of the filters matches. A single filter maches when all of its conditions are satisfied. Omitted conditions are considered true.

PropertyTypeDescription

addrs

array of strings

List of device mac addresses to be seacrhed for. Optional.

name

name

Device name to be matched. Accepts wildcards - ? to match any single character and * to match zero or more arbitrary characters. Optional.

services

array of strings

List of 16, 32 or 128 bit service UUIDs to search for in the advertisement. Optional.

serviceData

object

Service data to be searched for. Optional.

PropertyTypeDescription

service

string

16, 32 or 128 bit service UUID. Required otherwise all data mathes.

dataPrefix

string

Starting bytes in the service data to match exactly unless masked. Optional.

mask

string

Mask bytes to apply to the dataPrefix. 0x00 for a wildcard and 0xFF for exact match. Must be the same length as dataPrefix. Optional.

manufacturerData

object

Manufacturer(Vendor) data to be searched for. Optional.

PropertyTypeDescription

companyIdentifier

number

Officially assigned vendor ID. Required otherwise all data mathes.

dataPrefix

string

Starting bytes in the manufacturer data to match exactly unless masked. Optional.

mask

string

Mask bytes to apply to the dataPrefix. 0x00 for a wildcard and 0xFF for exact match. Must be the same length as dataPrefix. Optional.

Methods​

BLE.SetConfig​

Parameters:

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

note

Available since 2.0.0.

This is a new method which implements generic mechanism to associate a bluetooth device with a Shelly device. Currently it is used only in Shelly BLU Gateway Gen3 and supports Shelly BLU TRV. It can be extended to support other devices. Usually the result of this method would be creating a dynamic component in the host device, corresponding to the requested target device, but implementing other behavior is also possible.

Request:

PropertyTypeDescription

target

number

required Target device bluetooth model ID. The method will trigger the behavior specific for this target. It will also accept 0 which is invalid model ID as a wildcard to determine the target, setting it to the first discovered supported device. The criterion is Shelly device in pairing mode

param

any

optional Parameter passed to the target specific implementation.

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

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

AssociationsStarted status change:

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

AssociationsEnded status change:

{"ble_assoc":null}

BLE.StartBluTrvAssociations​

note

As of 2.0.0 this method is deprecated and replaced with the new more general method BLE.StartAssociations. It is kept for backward compatibility but new implementations should use the new method and where possible this method should be replaced with the new, since it may be removed in a future release.

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}

BLE.StartPairing​

(Since firmware version 2.0.0)

Enables pairing mode on the device, allowing BLE clients to bond with the device.

Request:

PropertyTypeDescription

timeout

number

Duration in seconds for which pairing mode will be enabled. Defaults to 180 if not provided. Optional

Response:

PropertyTypeDescription

timeout

number

The actual timeout value applied

When pairing is started, the device will emit a status change notification:

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

BLE.StopPairing​

(Since firmware version 2.0.0)

Disables pairing mode on the device.

Request:

The method takes no parameters.

Response:

null on success

When pairing is stopped, the device will emit a status change notification:

{"pairing":null}

BLE.ListPairedDevices​

(Since firmware version 2.0.0)

Returns a list of all BLE devices that are bonded with the Shelly device.

Request:

The method takes no parameters.

Response:

An array of objects, each containing:

PropertyTypeDescription

addr

string

MAC address of the bonded device

ctime

number

Unix timestamp when the bond was created

atime

number

Unix timestamp of last access (connection)

BLE.DeletePairedDevice​

(Since firmware version 2.0.0)

Removes a bonded device from the device's bond storage.

Request:

PropertyTypeDescription

addr

string

MAC address of the bonded device to delete. Required

Response:

null on success or error

BLE.AdvertiseOnce​

(Since firmware version 2.0.0)

Triggers a single one-time BLE advertisement using the device's user advertising slot. The advertisement is transmitted once for approximately 3 seconds, then automatically stops. This method preempts any currently active advertisement.

note

The user advertising slot is shared with scripts. This method is available on all mains-powered devices (scripting support enabled).

note

The Flags AD structure is automatically prepended to adv_data by the firmware. Do not include a Flags entry in adv_data or scan_rsp.

Request:

PropertyTypeDescription

adv_data

string

Hex-encoded binary advertisement data. Must not include a Flags AD entry - default flags are prepended automatically. Maximum effective payload is 28 bytes (31 bytes total minus 3 bytes for auto-prepended flags). Required

scan_rsp

string

Hex-encoded binary scan response data. Maximum 31 bytes. Optional

Response:

null on success or error

Configuration​

The configuration of the Bluetooth Low Energy component controls the RPC service over Bluetooth.

note

(Since 2.0.0) The enable property has been removed. Bluetooth scanning now auto-activates when needed by scripts, BLU gateway, or BTHome, and automatically stops when no longer needed. Only the rpc.enable property remains to allow device control over the Bluetooth RPC channel.

PropertyTypeDescription

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

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

Status​

PropertyTypeDescription

addr

string

The device's Bluetooth MAC address with type suffix: ,p (public), ,rs (random static), ,rn (random non-resolvable), or ,rr (random resolvable). Example: "AA:BB:CC:DD:EE:FF,p"

flags

array of strings

(Since 2.0.0) When Bluetooth is active, contains one or more of: "scanning", "advertising", "connected". When Bluetooth is idle, this property is absent from the response. Status change notifications are emitted whenever the flags array changes.

pairing

object

(Since 2.0.0) Present only when pairing mode is active

PropertyTypeDescription

started_at

integer

Unix timestamp when pairing mode was enabled

duration

integer

Duration in seconds for which pairing mode is enabled

blutrv_assoc

object

BluTrvAssociations information, present only when associations are active

PropertyTypeDescription

duration

integer

Duration of the current associations procedure in seconds

started_at

integer

Unix timestamp of the start of the associations procedure

Events​

(Since firmware version 2.0.0)

The BLE component emits the following notification events related to pairing:

paired_device_added​

Emitted when a new BLE device has been successfully bonded.

{
  "component": "ble",
  "event": "paired_device_added",
  "info": {
    "addr": "AA:BB:CC:DD:EE:FF",
    "ctime": 1729259400,
    "atime": 1729259400
  }
}

paired_device_removed​

Emitted when a bonded device is removed (via BLE.DeletePairedDevice).

{
  "component": "ble",
  "event": "paired_device_removed",
  "info": {
    "addr": "AA:BB:CC:DD:EE:FF",
    "ctime": 1729259400,
    "atime": 1729259500
  }
}

Examples​

BLE.GetStatus example​

http://192.168.33.1/rpc/BLE.GetStatus

Response when Bluetooth is idle:

Response

{
  "addr": "44:17:93:ce:3f:08,p"
}

Response when Bluetooth is active:

Response

{
  "addr": "44:17:93:ce:3f:08,p",
  "flags": [
    "scanning",
    "advertising"
  ]
}

BLE.GetConfig example​

http://192.168.33.1/rpc/BLE.GetConfig

Response

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

BLE.SetConfig example​

http://192.168.33.1/rpc/BLE.SetConfig?config={"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.StartAssociations example​

http://192.168.33.1/rpc/BLE.StartAssociations?target=8&param=200&duration=120&rssi_thr=-80

Response

null

BLE.StartBluTrvAssociations example​

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

Response

null

BLE.StartPairing example​

http://192.168.33.1/rpc/BLE.StartPairing?timeout=60

Response

{
  "timeout": 60
}

BLE.StopPairing example​

http://192.168.33.1/rpc/BLE.StopPairing

Response

null

BLE.ListPairedDevices example​

http://192.168.33.1/rpc/BLE.ListPairedDevices

Response

[
  {
    "addr": "AA:BB:CC:DD:EE:FF",
    "ctime": 1729259400,
    "atime": 1729259500
  }
]

BLE.DeletePairedDevice example​

http://192.168.33.1/rpc/BLE.DeletePairedDevice?addr="AA:BB:CC:DD:EE:FF"

Response

null

BLE.AdvertiseOnce example​

http://192.168.33.1/rpc/BLE.AdvertiseOnce?adv_data="07095368656c6c79"

Response

null