Skip to content

BLE Connect

Summary

  • Internal name: Ble_connect
  • Category: Bluetooth
  • Purpose: Open (or confirm) a BLE GATT connection to a device by its MAC address, so later BLE tasks (read/write/pairing) can use it.
  • 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 Connect task opens a GATT connection to a Bluetooth Low Energy device identified by its MAC address, and registers that connection so subsequent BLE tasks (Ble_readChar, Ble_writeChar, Ble_pairing, Ble_disconnect) can reuse it by referencing the same mac_ble.

If the device is already connected, the task does nothing and reports it as already connected — safe to call more than once with the same MAC.

Every BLE task shares the same prerequisite checks: Bluetooth must be enabled and supported on the device, the app must hold BLUETOOTH_SCAN/BLUETOOTH_CONNECT permissions, and device location must be enabled (an Android platform requirement for BLE, not an AndroMate choice).

Input parameters

Parameter Type Required Possible values Android Compatibility AndroMate Compatibility Default
mac_ble String Yes A valid Bluetooth MAC address, e.g. AA:BB:CC:DD:EE:FF Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 ""
connect_duration_timeout Integer No Milliseconds to wait for the connection to establish Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 30000

Output parameters

The BLE Connect task produces no outputs. It registers the GATT connection internally for other BLE tasks to reuse by mac_ble.

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.

Note: if the connection attempt times out, the task does not raise an exception — it logs the timeout and completes, leaving the device unconnected. Subsequent BLE tasks referencing that mac_ble will then fail with BLE-TASK-011 (No Active BLE GATT).

Execution flowchart

flowchart TD
    Start([▶ Ble_connect]) --> Prereq{BLE enabled, supported,\npermissions, location OK?}
    Prereq -->|No| E1[❌ BLE-TASK-001/002\nERROR-001/GPS-ERROR-003]
    Prereq -->|Yes| CheckMac{mac_ble\nvalid format?}
    CheckMac -->|No| E2[❌ BLE-TASK-003\nINVALID_MAC]
    CheckMac -->|Yes| CheckConnected{Already\nconnected?}
    CheckConnected -->|Yes| Info[ℹ️ Log: already connected]
    CheckConnected -->|No| Connect[🔵 Open GATT connection]
    Connect --> Wait{Connected within\nconnect_duration_timeout?}
    Wait -->|Yes| Register[💾 Register GATT for mac_ble]
    Wait -->|No| Timeout[⚠️ Log timeout, no exception]

    Info --> Success([✅ VoidResult])
    Register --> Success
    Timeout --> Success
    E1 --> Error([❌ Exception])
    E2 --> Error

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style Connect fill:#fff9c4
    style Register fill:#c8e6c9

How it works:

  1. Prerequisite checks: Bluetooth enabled/supported, permissions granted, location enabled.
  2. Validate MAC: raises BLE-TASK-003 if mac_ble isn't a valid MAC address.
  3. Already connected?: if so, logs it and returns immediately.
  4. Connect: opens a new GATT connection and waits up to connect_duration_timeout.
  5. Result: on success, the connection is registered under mac_ble for later BLE tasks. On timeout, no exception is raised — the workflow continues but the device remains unconnected.

Input parameter details

1. Input parameter: mac_ble

The Bluetooth MAC address of the target device.

Example

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

Details

  • Must be a valid MAC address format.
  • Resolved at runtime — may reference a $variable (e.g. from a prior Ble_scanner result).

2. Input parameter: connect_duration_timeout

How long to wait for the GATT connection to establish, in milliseconds.

Example

"connect_duration_timeout": 15000

Details

  • Optional — defaults to 30000 (30 seconds) if omitted.

Complete JSON example

{
  "Ble_connect": [
    {
      "id": "1",
      "title": "Connect to sensor",
      "mac_ble": "AA:BB:CC:DD:EE:FF",
      "connect_duration_timeout": 15000
    }
  ]
}