Skip to content

BLE Write Characteristic

Summary

  • Internal name: Ble_writeChar
  • Category: Bluetooth
  • Purpose: Encode a value and write it to a GATT characteristic on an already-connected BLE device.
  • 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 Write Characteristic task encodes value_to_write using the chosen decoder type and writes the resulting bytes to one GATT characteristic (identified by service UUID + characteristic UUID) on a BLE device that must already be connected via Ble_connect.

The target characteristic must support the WRITE or WRITE_NO_RESPONSE property, or the task fails immediately.

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 ""
value_to_write String Yes The value to encode and write — format depends on decoder 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 write acknowledgement Android 13 (API 33) → Android 16 (API 36) 1.1.0 → 1.1.0 5000

Decoder Types (used to ENCODE value_to_write into bytes)

Code Decoder Expected value_to_write format
1 AUTO Plain text, encoded as UTF-8
2 UTF8 Plain text
3 ASCII Plain text (ASCII only)
10 INT8 / 11 UINT8 / 31 BITMASK Decimal or 0x-prefixed integer string
12 INT16 / 13 UINT16 Decimal or 0x-prefixed integer string
14 INT32 / 15 UINT32 Decimal or 0x-prefixed integer string
20 FLOAT32 Decimal string, e.g. "3.14"
21 FLOAT64 Decimal string, e.g. "3.14159265"
30 BOOL "true" or "false"
40 HEX / 41 HEX_COMPACT Hex string, spaces optional, e.g. "AF 01 3C" or "AF013C"
42 BASE64 Base64-encoded string
43 BYTES Bracketed comma-separated bytes, e.g. "[12, -1, 3]"

Any code not listed above (or omitted) resolves to UNKNOWN, which this task treats as HEX. If encoding fails for any reason (bad format for the chosen decoder), an empty byte array is written rather than crashing the task.

Output parameters

The BLE Write Characteristic task produces no outputs.

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, or the characteristic doesn't support writing.
BLE-TASK-015 Cannot Write Characteristic The write call failed to start, or the GATT server returned a non-success status.
BLE-TASK-012 Read/Write Timeout No acknowledgement within read_timeout (during service discovery or the write itself).

Execution flowchart

flowchart TD
    Start([▶ Ble_writeChar]) --> 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 --> FindChar{Service + char found,\nwritable?}
    FindChar -->|No| E3[❌ BLE-TASK-008/009]
    FindChar -->|Yes| Encode[🔄 Encode value_to_write per decoder]
    Encode --> Write[✍️ writeCharacteristic]
    Write --> CheckStart{Write call\nstarted OK?}
    CheckStart -->|No| E4[❌ BLE-TASK-015\nCANNOT_WRITE]
    CheckStart -->|Yes| WaitAck{Ack within\nread_timeout?}
    WaitAck -->|No| E5[❌ BLE-TASK-012\nTIMEOUT]
    WaitAck -->|GATT_SUCCESS| Success1[✅ Written]
    WaitAck -->|Error status| E4

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

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

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 + locate: finds the service and characteristic; fails if not found or not writable.
  4. Encode: converts value_to_write into bytes per decoder (falls back to HEX if unset/unknown).
  5. Write: issues the GATT write and waits for the server's acknowledgement.
  6. Result: success on GATT_SUCCESS; otherwise BLE-TASK-015 or BLE-TASK-012 on timeout.

Input parameter details

1. Input parameter: mac_ble

The MAC address of the already-connected device to write to.

Example

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

2. Input parameter: service_uid / char_uid

The GATT service and characteristic UUIDs to write to.

Example

"service_uid": "0000ffe0-0000-1000-8000-00805f9b34fb",
"char_uid": "0000ffe1-0000-1000-8000-00805f9b34fb"

3. Input parameter: value_to_write

The value to encode and send — its expected format depends on the chosen decoder (see table above).

Example — text

"value_to_write": "ON",
"decoder": 2

Example — integer

"value_to_write": "1",
"decoder": 11

4. Input parameter: decoder

How to encode value_to_write into bytes before writing — see the Decoder Types table above.

Details

  • Optional — unset or unrecognized codes fall back to HEX.

5. Input parameter: read_timeout

Milliseconds to wait for both service discovery and the write acknowledgement.

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_writeChar": [
    {
      "id": "2",
      "title": "Turn on relay",
      "mac_ble": "AA:BB:CC:DD:EE:FF",
      "service_uid": "0000ffe0-0000-1000-8000-00805f9b34fb",
      "char_uid": "0000ffe1-0000-1000-8000-00805f9b34fb",
      "value_to_write": "1",
      "decoder": 11
    }
  ]
}