Skip to content

BLE Read Characteristic

Summary

  • Internal name: Ble_readChar
  • Category: Bluetooth
  • Purpose: Read a GATT characteristic's value from an already-connected BLE device and decode it into a workflow variable.
  • 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 Read Characteristic task reads the value of one GATT characteristic (identified by its service UUID + characteristic UUID) from a BLE device that must already be connected via Ble_connect. The raw bytes are decoded using the chosen decoder type and stored as a string in value_output.

Before reading, the task discovers the device's GATT services and locates the requested service/characteristic — both must exist on the device, or the task fails.

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 ""
service_uid String Yes A valid GATT service UUID Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 ""
char_uid String Yes A valid GATT characteristic UUID Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 ""
decoder Integer No See Decoder Types table below Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 -1 (UNKNOWN → falls back to HEX)
read_timeout Integer No Milliseconds to wait for the read response Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 5000

Decoder Types

Code Decoder Notes
1 AUTO UTF-8 if all bytes are printable, otherwise falls back to spaced hex
2 UTF8 Decode bytes as UTF-8 text
3 ASCII Decode bytes as ASCII text
10 INT8 Signed 8-bit integer
11 UINT8 Unsigned 8-bit integer
12 INT16 Signed 16-bit integer, little-endian
13 UINT16 Unsigned 16-bit integer, little-endian
14 INT32 Signed 32-bit integer, little-endian
15 UINT32 Unsigned 32-bit integer, little-endian
20 FLOAT32 IEEE-754 32-bit float, little-endian
21 FLOAT64 IEEE-754 64-bit float, little-endian
30 BOOL First byte: 0 = false, non-zero = true
31 BITMASK First byte as an unsigned integer bitmask
40 HEX Spaced uppercase hex, e.g. "AF 01 3C"
41 HEX_COMPACT Unspaced uppercase hex, e.g. "AF013C"
42 BASE64 Base64-encoded string
43 BYTES Java byte-array toString(), e.g. "[12, -1, 3]"

Any code not listed above (or omitted) resolves to UNKNOWN, which this task treats as HEX.

Output parameters

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

value_output

The characteristic's value, decoded per the decoder parameter (see table above).

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-007 Invalid UUID service_uid or char_uid is not a valid UUID format.
BLE-TASK-008 Service Not Found No GATT service matching service_uid on this device.
BLE-TASK-009 Characteristic Not Found No characteristic matching char_uid in the given service.
BLE-TASK-010 Cannot Read Characteristic The GATT server returned a non-success status for the read.
BLE-TASK-012 Read/Write Timeout No response within read_timeout (during service discovery or the read itself).

Execution flowchart

flowchart TD
    Start([▶ Ble_readChar]) --> Prereq{BLE enabled, connected,\nregistered, permissions OK?}
    Prereq -->|No| E1[❌ BLE-TASK-001/002/005/006/011\nERROR-001/GPS-ERROR-003]
    Prereq -->|Yes| CheckUuid{service_uid, char_uid\nvalid UUIDs?}
    CheckUuid -->|No| E2[❌ BLE-TASK-007\nINVALID_UUID]
    CheckUuid -->|Yes| Discover[🔍 discoverServices]
    Discover --> WaitDisc{Discovered within\nread_timeout?}
    WaitDisc -->|No| E3[❌ BLE-TASK-012\nTIMEOUT]
    WaitDisc -->|Yes| FindService{Service\nfound?}
    FindService -->|No| E4[❌ BLE-TASK-008\nSERVICE_NOT_FOUND]
    FindService -->|Yes| FindChar{Characteristic\nfound?}
    FindChar -->|No| E5[❌ BLE-TASK-009\nCHAR_NOT_FOUND]
    FindChar -->|Yes| Read[📖 readCharacteristic]
    Read --> WaitRead{Response within\nread_timeout?}
    WaitRead -->|No| E3
    WaitRead -->|GATT_SUCCESS| Decode[🔄 Decode bytes per decoder]
    WaitRead -->|Error status| E6[❌ BLE-TASK-010\nCANNOT_READ]
    Decode --> StoreResult[💾 Store value_output]
    StoreResult --> Success([✅ StrTaskResult])

    E1 --> Error([❌ Exception])
    E2 --> Error
    E3 --> Error
    E4 --> Error
    E5 --> Error
    E6 --> Error

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

How it works:

  1. Prerequisite + connection checks: Bluetooth ready, mac_ble connected and registered.
  2. Validate UUIDs: service_uid/char_uid must parse as UUIDs.
  3. Discover services: waits for the GATT service table (bounded by read_timeout).
  4. Locate service and characteristic: fails if either isn't found on the device.
  5. Read: issues the GATT read and waits for the server's response.
  6. Decode: converts the raw bytes using the decoder type (falls back to HEX if unset/unknown).
  7. Store: writes the decoded string into value_output.

Input parameter details

1. Input parameter: mac_ble

The MAC address of the already-connected device to read from.

Example

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

2. Input parameter: service_uid / char_uid

The GATT service and characteristic UUIDs to read.

Example

"service_uid": "0000180f-0000-1000-8000-00805f9b34fb",
"char_uid": "00002a19-0000-1000-8000-00805f9b34fb"

3. Input parameter: decoder

How to decode the raw bytes read from the characteristic — see the Decoder Types table above.

Example

"decoder": 11

Details

  • Optional — unset or unrecognized codes fall back to HEX (spaced hex string).

4. Input parameter: read_timeout

Milliseconds to wait for both service discovery and the read response.

Example

"read_timeout": 8000

Details

  • Optional — defaults to 5000 (5 seconds).

Complete JSON example

{
  "Ble_connect": [
    { "id": "1", "mac_ble": "AA:BB:CC:DD:EE:FF" }
  ],
  "Ble_readChar": [
    {
      "id": "2",
      "title": "Read battery level characteristic",
      "mac_ble": "AA:BB:CC:DD:EE:FF",
      "service_uid": "0000180f-0000-1000-8000-00805f9b34fb",
      "char_uid": "00002a19-0000-1000-8000-00805f9b34fb",
      "decoder": 11,
      "value_output": "$BLE_BATTERY_LEVEL"
    }
  ]
}