Skip to content

BLE Pairing

Summary

  • Internal name: Ble_pairing
  • Category: Bluetooth
  • Purpose: Pair (bond) with a BLE device that is already connected via Ble_connect.
  • 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 Pairing task initiates Android's Bluetooth bonding (pairing) process with a device that must already be connected via Ble_connect in the same workflow session. If the device is already bonded, the task returns immediately.

Like every "execute" BLE task (pairing, read/write characteristic), this task requires the device to be currently connected and registered — run Ble_connect with the same mac_ble first.

Input parameters

Parameter Type Required Possible values Android Compatibility AndroMate Compatibility Default
mac_ble String Yes A valid Bluetooth MAC address, must already be connected Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 ""
pairingTimeout Integer No Milliseconds to wait for the pairing/bonding to complete Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 20000

Output parameters

The BLE Pairing task produces no outputs. On success, the device's bond state becomes BONDED.

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 is not a valid Bluetooth MAC address.
BLE-TASK-005 MAC BLE Disconnected The device is not currently connected.
BLE-TASK-006 MAC BLE Not In Register The device was never connected via Ble_connect in this session.
BLE-TASK-011 No Active BLE GATT No active GATT connection is available for this device.
BLE-TASK-014 Pairing Error The bonding process failed (device reported BOND_NONE after BOND_BONDING).
BLE-TASK-013 Pairing Timeout Bonding did not complete within pairingTimeout.

Execution flowchart

flowchart TD
    Start([▶ Ble_pairing]) --> Prereq{BLE enabled, supported,\npermissions, location OK?}
    Prereq -->|No| E1[❌ BLE-TASK-001/002\nERROR-001/GPS-ERROR-003]
    Prereq -->|Yes| CheckMac{mac_ble valid,\nconnected, registered?}
    CheckMac -->|No| E2[❌ BLE-TASK-003/005/006/011]
    CheckMac -->|Yes| CheckBond{Already\nbonded?}
    CheckBond -->|Yes| Info[ℹ️ Log: already bonded]
    CheckBond -->|No| CreateBond[🔗 createBond]
    CreateBond --> Wait{Bond state changed\nwithin pairingTimeout?}
    Wait -->|BONDED| Success1[✅ Paired]
    Wait -->|BOND_NONE| E3[❌ BLE-TASK-014\nPAIRING_ERROR]
    Wait -->|Timeout| E4[❌ BLE-TASK-013\nPAIRING_TIMEOUT]

    Info --> Success([✅ VoidResult])
    Success1 --> Success
    E1 --> Error([❌ Exception])
    E2 --> Error
    E3 --> Error
    E4 --> Error

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style CreateBond fill:#fff9c4

How it works:

  1. Prerequisite checks: Bluetooth enabled/supported, permissions, location.
  2. Connection checks: mac_ble must be a valid, currently-connected, registered device (raises BLE-TASK-003/005/006/011 otherwise).
  3. Already bonded?: if so, logs it and returns.
  4. Create bond: calls Android's createBond() and listens for the bond-state-changed broadcast.
  5. Result: BONDED → success; BOND_NONE after BOND_BONDING → BLE-TASK-014; no response within pairingTimeout → BLE-TASK-013.

Input parameter details

1. Input parameter: mac_ble

The MAC address of the already-connected device to pair with.

Example

"mac_ble": "AA:BB:CC:DD:EE:FF"

2. Input parameter: pairingTimeout

How long to wait for the bonding process to complete, in milliseconds.

Example

"pairingTimeout": 15000

Details

  • Optional — defaults to 20000 (20 seconds).
  • Resolved at runtime — may reference a $variable.

Complete JSON example

{
  "Ble_connect": [
    { "id": "1", "mac_ble": "AA:BB:CC:DD:EE:FF" }
  ],
  "Ble_pairing": [
    {
      "id": "2",
      "title": "Pair with sensor",
      "mac_ble": "AA:BB:CC:DD:EE:FF",
      "pairingTimeout": 15000
    }
  ]
}