Skip to content
Get started

RP2 BLE Tracker

The rp2_ble_tracker component scans for Bluetooth Low Energy advertisements on the Raspberry Pi Pico W and Pico 2 W — the platform analog of ESP32 BLE Tracker. It builds on the RP2040 BLE stack component and loads it automatically.

Scanning is active by default: the tracker sends scan requests asking devices for more data, and the scan response (which can carry extra data such as some device names) is merged into the advertisement before it is delivered. Set active: false under scan_parameters for a lighter passive scan. The radio is shared between WiFi and Bluetooth on these boards; the default scan parameters use a 30% duty cycle to leave the radio mostly free for WiFi.

NOTE

BLE sensor platforms such as ble_presence do not yet bind to this tracker; support arrives as those platforms migrate to the shared BLE layer in follow-up releases.

NOTE

bluetooth_proxy supports active GATT connections with this tracker (up to three connection slots) — see Platform Support.

# Example configuration entry
rp2_ble_tracker:

Configuration variables

Section titled “Configuration variables”

  • scan_parameters (Optional): Tune how the scan runs.

    • interval (Optional, Time): How often the radio opens a scan window. The controller accepts 2.5 ms to 10240 ms in 0.625 ms steps. Defaults to 100ms.
    • window (Optional, Time): How long the radio listens within each interval. Must not be larger than the interval; the same range and step apply. Defaults to 30ms.
    • duration (Optional, Time): Length of one scan period. In continuous mode the scan period restarts every duration; in non-continuous mode the scan stops after this long. Must cover at least three scan intervals. Defaults to 5min.
    • active (Optional, boolean): Whether to send scan requests asking devices for more data after their advertisement. The scan response is merged into the advertisement before delivery. Turning this off saves power on the advertising devices and radio time on the shared CYW43439. Defaults to true.
    • continuous (Optional, boolean): If true, scanning starts at boot and runs forever. If false, scanning does not start automatically; a scan is started with the rp2_ble_tracker.start_scan action and stops again after duration. Defaults to true.

  • rp2040_ble_id (Optional, ID): Manually specify the ID of the RP2040 BLE component this tracker uses.

  • id (Optional, ID): Manually specify the ID used to reference this component.

Automations:

  • on_ble_advertise (Optional, Automation): An automation to perform when a BLE advertising packet is received. Optionally filtered to a list of mac_addresses. A variable x of type API Reference: ble_device_base::ESPBTDevice is passed to the automation for use in lambdas. The shared trigger classes and variables are identical to ESP32 BLE Tracker.
  • on_ble_manufacturer_data_advertise (Optional, Automation): An automation to perform when a BLE advertising packet with matching manufacturer data is received (manufacturer_id required, mac_address optional). A variable x of type std::vector<uint8_t> holds the manufacturer data.
  • on_ble_service_data_advertise (Optional, Automation): An automation to perform when a BLE advertising packet with service data for service_uuid is received (mac_address optional). A variable x of type std::vector<uint8_t> holds the service data.
  • on_scan_end (Optional, Automation): An automation to perform when a scan period ends: once per duration while continuous is true, when the duration of a one-shot scan elapses, and on rp2_ble_tracker.stop_scan.

rp2_ble_tracker.start_scan Action

Section titled “rp2_ble_tracker.start_scan Action”

Start a Bluetooth scan. The optional templatable continuous overrides the scan mode until the next start_scan or stop_scan (the YAML-configured value itself is untouched); without it the mode configured under scan_parameters is restored (a previous stop_scan does not stick as “one-shot”). This differs from esp32_ble_tracker.start_scan, where an omitted continuous always forces a one-shot scan. Invoked while a scan is already running, a mode switch re-anchors the running scan’s duration window; a same-mode call is a no-op.

rp2_ble_tracker:
  scan_parameters:
    continuous: false


api:
  on_client_connected:
    - rp2_ble_tracker.start_scan:
        continuous: true
  on_client_disconnected:
    # fires for EVERY departing client (log viewer, CLI) — state_subscription_only
    # ignores logger-only clients, so scanning stops only when Home Assistant is gone
    - if:
        condition:
          not:
            api.connected:
              state_subscription_only: true
        then:
          - rp2_ble_tracker.stop_scan:

Configuration variables

Section titled “Configuration variables”
  • continuous (Optional, templatable, boolean): Override the scan mode until the next start_scan or stop_scan (the YAML-configured value itself is untouched). When omitted, the mode configured under scan_parameters is restored — a previous stop_scan does not stick as “one-shot”.

rp2_ble_tracker.stop_scan Action

Section titled “rp2_ble_tracker.stop_scan Action”

Stop the running Bluetooth scan; also cancels a start latched before setup. Accepts the bare-id shorthand (rp2_ble_tracker.stop_scan: my_tracker). It can be restarted with rp2_ble_tracker.start_scan.

on_...:
  - rp2_ble_tracker.stop_scan:

See Also

Section titled “See Also”