# Bluetooth GATT read

A decision block that reads a characteristic value from a Bluetooth GATT service hosted on a remote device.

If the proceed option is set to Immediately, then the fiber will proceed when the characteristic value has been read. If set to When changed then the characteristic must support either

- both “read” and “notification” where the fiber will pause until the value has changed; or
- only “indication” or “notification” where the fiber will pause until a new value has been indicated/notified, but it may not actually differ.

The OK path is followed if the value was successfully read/received. The NO path is followed if the remote device, service or characteristic was not found.

The address of a device may be randomized at regular intervals unless devices has been paired, and the name may not always be available.

The listed services and characteristic are far from complete, for further documentation visit Specifications and Test Documents List. Use an app like nRF Connect to inspect what services and characteristics a device support, the Advertisements output variable of the Bluetooth device scan block may include `"services"` property listing its services.

Access to a characteristic may not be permitted or supported, e.g. an “read not permitted” failure could mean that the characteristic is only be accessible as “notify”, i.e. try using proceed When changed instead.

The Android Bluetooth stack is slow, buggy, unreliable and lack proper error reporting. Expect connection establishment and detection of loss to take minutes. Expect generic “error 133” at any time, for any reason, common failure causes include:

- the remote device is out of range;
- the remote device is not discoverable nor advertising;
- the remote device only accept authenticated/paired connections;
- the remote device rejects the connection;
- another Bluetooth operation is already in progress;
- Bluetooth operations are issued too rapidly; or
- the connection or operation timed out

Use the Failure catch block to handle a failure.

### Examples

- Read remaining device battery percentage — Battery service, Battery level characteristic, value format uint8 at 0 bit offset

Note! This feature requires Android 4.3+.

## Options

- Proceed — when the fiber should proceed.

## Input arguments

- Device address — address of device, default is first paired device found.
- Device name — name of device, default is first paired device found.
- Service UUID — if a number then used as UUID32, otherwise the UUID of service to read characteristic from.
- Service instance ID — unique id of service when multiple are available, default is lowest id present.
- Characteristic UUID — if a number then used as UUID32, otherwise the UUID of characteristic to read.
- Characteristic instance ID — unique id of characteristic when multiple are available, default is lowest id present.
- Value format — format of value to read, default is read from “characteristic presentation format” descriptor if present, which is rare.
- Value offset — offset of value to read, used when containing multiple fields, in bits, default 0.

## Output variables

- Characteristic value — variable to assign the read value.