Skip to content

BLE Scanner

Summary

  • Internal name: Ble_scanner
  • Category: Bluetooth
  • Purpose: Scan for nearby BLE devices for a fixed duration, optionally filtered by signal strength, name, or MAC address, and return the list found.
  • Task type: Normal

Compatibility

  • Minimum AndroMate version: 1.1.0

  • Maximum AndroMate version: 1.1.0

  • Minimum Android: Android 13 (API 33)

  • Maximum Android tested: Android 16 (API 36)

  • Supported manufacturers:

    • ✅ All manufacturers

  • Required permissions:

    • BLUETOOTH_SCAN
    • BLUETOOTH_CONNECT
    • Device location enabled (required by Android for BLE operations)

Detailed description

The BLE Scanner task scans for nearby Bluetooth Low Energy devices for ScanDurationMs milliseconds, applying any of three optional filters (minimum signal strength, device-name substring, MAC-address substring), and returns every matching device found as a JSON array — each device seen only once (deduplicated by MAC address).

Use this task to discover devices before connecting to them with Ble_connect, e.g. when the exact mac_ble isn't known ahead of time.

Input parameters

Parameter Type Required Possible values Android Compatibility AndroMate Compatibility Default
ScanDurationMs Integer No Milliseconds to scan for Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 30000
RssiMin Integer No Minimum signal strength (dBm, e.g. -70); 0 = no filter Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 0
name_filter String No Case-insensitive substring the device name must contain; "" = no filter Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 ""
mac_ble String No Substring the device MAC address must contain; "" = no filter Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 ""

Output parameters

Parameter Type Condition Android Compatibility AndroMate Compatibility Default
json_array_output String (JSON array) Always, on success Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 <ANDROMATE_NULL_VALUE>

json_array_output

A JSON array of matching device objects, e.g. [{"mac": "AA:BB:CC:DD:EE:FF", "name": "Sensor01", "rssi": -58}, ...]. Empty array if nothing matched.

Exceptions

Code Exception Name Description
BLE-TASK-001 Bluetooth Not Enabled Bluetooth is turned off on the device.
BLE-TASK-002 Bluetooth Not Supported This device does not support Bluetooth.
ERROR-001 Permission Not Granted BLUETOOTH_SCAN or BLUETOOTH_CONNECT was not granted.
GPS-ERROR-003 Disabled Location Settings Device location is disabled — required by Android for BLE.
BLE-TASK-003 Invalid MAC Format mac_ble filter is set but is not a valid MAC (sub)string.

Execution flowchart

flowchart TD
    Start([▶ Ble_scanner]) --> Prereq{BLE enabled, supported,\npermissions, location OK?}
    Prereq -->|No| E1[❌ BLE-TASK-001/002\nERROR-001/GPS-ERROR-003]
    Prereq -->|Yes| CheckMac{mac_ble filter\nvalid format?}
    CheckMac -->|No| E2[❌ BLE-TASK-003\nINVALID_MAC]
    CheckMac -->|Yes| Scan[📡 Start BLE scan]
    Scan --> Filter[🔍 Filter each result:\nRSSI, name, MAC]
    Filter --> Dedup[🗂 Deduplicate by MAC]
    Dedup --> WaitDuration{ScanDurationMs\nelapsed?}
    WaitDuration -->|No| Filter
    WaitDuration -->|Yes| Build[📋 Build JSON array]
    Build --> StoreResult[💾 Store json_array_output]
    StoreResult --> Success([✅ JsonArrayTaskResult])

    E1 --> Error([❌ Exception])
    E2 --> Error

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style Scan fill:#fff9c4
    style StoreResult fill:#c8e6c9

How it works:

  1. Prerequisite checks: Bluetooth enabled/supported, permissions, location.
  2. Validate mac_ble filter: if set, must be a valid MAC-address format.
  3. Scan: starts a BLE scan for ScanDurationMs milliseconds.
  4. Filter each result: skipped if below RssiMin, or if the device name doesn't contain name_filter, or if the address doesn't contain the mac_ble filter.
  5. Deduplicate: each MAC address is reported only once, even if seen multiple times during the scan.
  6. Store: writes the matching devices as a JSON array into json_array_output.

Input parameter details

1. Input parameter: ScanDurationMs

How long to scan for, in milliseconds.

Example

"ScanDurationMs": 15000

Details

  • Optional — defaults to 30000 (30 seconds).

2. Input parameter: RssiMin

Minimum signal strength (dBm) a device must have to be included.

Example

"RssiMin": -70

Details

  • Optional — 0 (default) means no RSSI filtering.
  • More negative = weaker signal; e.g. -90 is far/weak, -40 is very close/strong.

3. Input parameter: name_filter

Case-insensitive substring the device's advertised name must contain.

Example

"name_filter": "sensor"

Details

  • Optional — empty string (default) means no name filtering.
  • Devices with no advertised name are excluded when this filter is set.

4. Input parameter: mac_ble

Substring the device's MAC address must contain — used here as a filter, not a target.

Example

"mac_ble": "AA:BB"

Details

  • Optional — empty string (default) means no MAC filtering.

Complete JSON example

{
  "Ble_scanner": [
    {
      "id": "1",
      "title": "Find nearby sensors",
      "ScanDurationMs": 15000,
      "RssiMin": -70,
      "name_filter": "sensor",
      "json_array_output": "$FOUND_DEVICES"
    }
  ]
}