Освой Android играючи

Сайт Александра Климова

Шкодим

/* Моя кошка замечательно разбирается в программировании. Стоит мне объяснить проблему ей - и все становится ясно. */
John Robbins, Debugging Applications, Microsoft Press, 2000

Bluetooth Low Energy

BluetoothManager

Bluetooth Low Energy (BLE) - это цифровой радио протокол передачи данных от одного устройства к другому. Принцип работы BLE описан уже в его названии: Low Energy. Протокол подразумевает передачу данных короткими пакетами по необходимости, затем – выключение передатчика. Низкое энергопотребление частично достигается применением именно этого принципа. Вместо классического тандема в обычном Bluetooth, устройства BLE связываются друг с другом лишь при необходимости отправки или получения информации.

Одно из устройств является центральным, а остальные периферийными. Центральное устройство может держать несколько соединений с периферией, но периферийное устройство может содержать только одно соединение. Например, смартфон выступает как центральное устройство, которое может соединиться с периферией: блютуз-колонкой, лампой, умными часами и фитнес-трекером. А все эти устройства могут соединиться только с телефоном. Смартфоны 5.0 и выше (API 21) могут выступать и как периферийные устройства.

У центрального устройства есть два режима: сканирование и соединение. Периферия имеет другие два режима: объявление и соединение.

Протокол BLE строго структурирован по принципу своей коммуникации с другими устройствами. Вначале девайсы изучают доступные сервисы для отправки/принятия данных; неотъемлемая часть этих сервисов – их характеристики (characteristics), определяющие тип данных для будущей передачи. Характеристики, из соображений наглядности, могут иметь в своём составе описания-дескрипторы (descriptors), которые помогают определить тип данных. К примеру, разберём сервис под названием «Heart Rate Monitor» (монитор частоты сердцебиения) – среди его характеристик присутствуют такие, как «измерение пульса».

Большинство API для Bluetooth LE позволяют искать локальные устройства и определять доступные в них сервисы, характеристики и дескрипторы.

Далее перевод статьи Bluetooth Low Energy | Android Developers подготовил Антон Акимов.

ОС Android 4.3 (API 18) представляет встроенную поддержку Bluetooth Low Energy и API, при помощи которого приложения могут использовать поиск устройств, запрос услуг и чтение/запись характеристик. В отличие от классического Bluetooth, BLE призван обеспечить существенно меньшее энергопотребление. Это позволяет приложениям для Android общаться с BLE-устройствами, которые имеют низкие требования к питанию, таких как датчики, мониторы сердечного ритма, фитнес-устройства и так далее.

Ключевые термины и понятия

Generic Attribute Profile (GATT) – профиль GATT является общей спецификацией для отправки и получения коротких фрагментов данных, известных как "атрибуты" через BLE-соединение. Все текущие LE-профили приложений основаны на GATT. Создатели BLE определили множество профилей для низкоэнергетических устройств. Профиль представляет собой определение того, как устройство работает в конкретном приложении. Обратите внимание, что устройство может реализовывать более одного профиля. Например, устройство может содержать профили пульсометра и датчика уровня заряда батареи.

Attribute Protocol (ATT) – GATT строится на основе протокола атрибутов АТТ. Это также относится к GATT/ATT. АТТ оптимизирован для работы на BLE-устройствах. Для этого он использует настолько мало байтов, насколько возможно. Каждый атрибут идентифицируется уникальным универсальным идентификатором (UUID), который представляет собой стандартизированный 128-битный строковый идентификатор используемый для однозначной идентификации информации. Атрибуты переносятся с помощью АТТ в виде характеристик и услуг.

Характеристика (Characteristic) – содержит одно значение, и от 0 до N дескрипторов, описывающих значение характеристики. Характеристика может рассматриваться как тип, аналог класса.

Дескриптор (Descriptor) может содержать удобочитаемое описание, приемлемый диапазон значений или единицу измерения, конкретные значения характеристики.

Услуга (Service) – это набор характеристик. Например, вы можете иметь услугу под названием "пульсометр", что включает в себя такую характеристику, как "Измерение пульса". Вы можете найти список существующих на основе GATT профилей и услуг на bluetooth.org.

Роли и обязанности при взаимодействии Android с BLE-устройством

Центральная/периферическая роль. Это относится к самому BLE-соединению. Устройство в центральной роли сканирует, ищет объявления, а устройства в периферийной роли создаёт объявления.

GATT-сервер/GATT-клиент. Это определяет, каким образом два устройства общаются друг с другом, когда они установили связь.

Чтобы понять разницу, представьте, что у вас Android-телефон и фитнес-трекер, который представляет собой BLE-устройство. Телефон поддерживает центральную роль; трекер активности поддерживает периферийную роль. Чтобы установить BLE-соединение, вам нужно по одному устройству, поддерживающему каждую из ролей; два периферийных устройства не смогут общаться друг с другом, также как и два центральных.

Как только телефон и трекер активности наладили связь, они начинают передачу метаданных GATT друг другу. В зависимости от того, какие данные они передают, тот или другой может выступать в качестве сервера. Например, если трекер хочет сообщить данные датчика телефону, трекеру имеет смысл работать в качестве сервера. Если трекер активности хочет получать обновления с телефона, то в качестве сервера имеет смысл использовать телефон.

В качестве примера в данном документе представлено Android-приложение, являющееся GATT-клиентом. Приложение получает данные от GATT-сервера на BLE-пульсометре. Но вы можете также спроектировать ваше приложение так, чтобы оно играло роль сервера.

BluetoothAdapter является обязательным для любых действий с Bluetooth. BluetoothAdapter представляет собственный Bluetooth-адаптер устройства (Bluetooth-приёмник). Есть один Bluetooth-адаптер для всей системы, и ваше приложение может взаимодействовать с ним, используя этот объект.

Подключение к GATT-серверу

Первым шагом во взаимодействии с BLE-устройством станет подключение к нему – точнее, подключение к GATT-серверу на устройстве. Для подключения к GATT-серверу на BLE-устройстве нужно использовать метод connectGatt(). Этот метод принимает три параметра: объект контекста, автосоединение (логическое значение, указывающее, следует ли автоматически подключиться к BLE-устройству, как только оно станет доступным), и ссылку на BluetoothGattCallback:


mBluetoothGatt = device.connectGatt(this, false, mGattCallback);

Оно подключается к GATT-серверу, находящемуся на BLE-устройстве, и возвращает экземпляр BluetoothGatt, который затем можно использовать для проведения клиентских операций GATT. Приложение для Android является GATT-клиентом. BluetoothGattCallback используется для получения результатов клиентом, таких как статус подключения, а также любые дополнительные клиентские операции GATT.

В этом примере BLE-приложение предоставляет активности (DeviceControlActivity) отображение данных о подключении, GATT-услугах и характеристиках, поддерживаемых устройством. На основе ввода пользователя, эта активность связывается со службой под названием BluetoothLeService, который взаимодействует с BLE-устройством через Android BLE API-интерфейс:


// Служба, которая взаимодействует с BLE-устройством через Android BLE API
public class BluetoothLeService extends Service {
    private final static String TAG = BluetoothLeService.class.getSimpleName();

    private BluetoothManager mBluetoothManager;
    private BluetoothAdapter mBluetoothAdapter;
    private String mBluetoothDeviceAddress;
    private BluetoothGatt mBluetoothGatt;
    private int mConnectionState = STATE_DISCONNECTED;

    private static final int STATE_DISCONNECTED = 0;
    private static final int STATE_CONNECTING = 1;
    private static final int STATE_CONNECTED = 2;

    public final static String ACTION_GATT_CONNECTED =
            "com.example.bluetooth.le.ACTION_GATT_CONNECTED";
    public final static String ACTION_GATT_DISCONNECTED =
            "com.example.bluetooth.le.ACTION_GATT_DISCONNECTED";
    public final static String ACTION_GATT_SERVICES_DISCOVERED =
            "com.example.bluetooth.le.ACTION_GATT_SERVICES_DISCOVERED";
    public final static String ACTION_DATA_AVAILABLE =
            "com.example.bluetooth.le.ACTION_DATA_AVAILABLE";
    public final static String EXTRA_DATA =
            "com.example.bluetooth.le.EXTRA_DATA";

    // Устанавливаем UUID, который используется для услуг измерения пульса
    public final static UUID UUID_HEART_RATE_MEASUREMENT =
            UUID.fromString(SampleGattAttributes.HEART_RATE_MEASUREMENT);

    // Различные методы обратного вызова, определённые в BLE API
    private final BluetoothGattCallback mGattCallback =
            new BluetoothGattCallback() {
        @Override
        public void onConnectionStateChange(BluetoothGatt gatt, int status,
                int newState) {
            String intentAction;
            if (newState == BluetoothProfile.STATE_CONNECTED) {
                intentAction = ACTION_GATT_CONNECTED;
                mConnectionState = STATE_CONNECTED;
                broadcastUpdate(intentAction);
                Log.i(TAG, "Connected to GATT server.");
                Log.i(TAG, "Attempting to start service discovery:" +
                        mBluetoothGatt.discoverServices());

            } else if (newState == BluetoothProfile.STATE_DISCONNECTED) {
                intentAction = ACTION_GATT_DISCONNECTED;
                mConnectionState = STATE_DISCONNECTED;
                Log.i(TAG, "Disconnected from GATT server.");
                broadcastUpdate(intentAction);
            }
        }

        @Override
        // При обнаружении нового сервиса
        public void onServicesDiscovered(BluetoothGatt gatt, int status) {
            if (status == BluetoothGatt.GATT_SUCCESS) {
                broadcastUpdate(ACTION_GATT_SERVICES_DISCOVERED);
            } else {
                Log.w(TAG, "onServicesDiscovered received: " + status);
            }
        }

        @Override
        // Результат чтения характеристики
        public void onCharacteristicRead(BluetoothGatt gatt,
                BluetoothGattCharacteristic characteristic,
                int status) {
            if (status == BluetoothGatt.GATT_SUCCESS) {
                broadcastUpdate(ACTION_DATA_AVAILABLE, characteristic);
}  } ... }; ... }

Когда срабатывает конкретный обратный вызов, он вызывает соответствующий вспомогательный метод broadcastUpdate() и передает ему действие. Обратите внимание, что извлечение данных в этот раздел выполняется в соответствии с профилем пульсометра.


private void broadcastUpdate(final String action) {
    final Intent intent = new Intent(action);
    sendBroadcast(intent);
}

private void broadcastUpdate(final String action,
                             final BluetoothGattCharacteristic characteristic) {
    final Intent intent = new Intent(action);

    // Это специальная обработка для пульсометра
    // Извлечение данных осуществляется согласно спецификации профиля
    if (UUID_HEART_RATE_MEASUREMENT.equals(characteristic.getUuid())) {
        int flag = characteristic.getProperties();
        int format = -1;
        if ((flag & 0x01) != 0) {
            format = BluetoothGattCharacteristic.FORMAT_UINT16;
            Log.d(TAG, "Heart rate format UINT16.");
        } else {
            format = BluetoothGattCharacteristic.FORMAT_UINT8;
            Log.d(TAG, "Heart rate format UINT8.");
        }
        final int heartRate = characteristic.getIntValue(format, 1);
        Log.d(TAG, String.format("Received heart rate: %d", heartRate));
        intent.putExtra(EXTRA_DATA, String.valueOf(heartRate));
    } else {
        // For all other profiles, writes the data formatted in HEX.
        final byte[] data = characteristic.getValue();
        if (data != null && data.length > 0) {
            final StringBuilder stringBuilder = new StringBuilder(data.length);
            for(byte byteChar : data)
                stringBuilder.append(String.format("%02X ", byteChar));
            intent.putExtra(EXTRA_DATA, new String(data) + "\n" +
                    stringBuilder.toString());
        }
    }
    sendBroadcast(intent);
}

Ещё в DeviceControlActivity, эти события обрабатываются в BroadcastReceiver:


// Обрабатывает различные события, запущенные службы
// ACTION_GATT_CONNECTED: подключение к серверу GATT 
// ACTION_GATT_DISCONNECTED: отключён от сервера GATT 
// ACTION_GATT_SERVICES_DISCOVERED: обнаружена услуга GATT 
// ACTION_DATA_AVAILABLE: получил данные от устройства. Это может быть
// результатом чтения или операцией уведомления
private final BroadcastReceiver mGattUpdateReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        final String action = intent.getAction();
        if (BluetoothLeService.ACTION_GATT_CONNECTED.equals(action)) {
            mConnected = true;
            updateConnectionState(R.string.connected);
            invalidateOptionsMenu();
        } else if (BluetoothLeService.ACTION_GATT_DISCONNECTED.equals(action)) {
            mConnected = false;
            updateConnectionState(R.string.disconnected);
            invalidateOptionsMenu();
            clearUI();
        } else if (BluetoothLeService.
                ACTION_GATT_SERVICES_DISCOVERED.equals(action)) {
            // Показать в UI все поддерживаемые услуги и характеристики
            displayGattServices(mBluetoothLeService.getSupportedGattServices());
        } else if (BluetoothLeService.ACTION_DATA_AVAILABLE.equals(action)) {
            displayData(intent.getStringExtra(BluetoothLeService.EXTRA_DATA));
}  }  };

Чтение BLE-атрибутов

Как только ваше Android-приложение подключается к GATT-серверу и обнаруживает услуги, оно может читать и писать атрибуты, где это поддерживается. Например, этот фрагмент перебирает услуги и характеристик сервера и отображает их в интерфейсе:


public class DeviceControlActivity extends Activity {
    ...
    // Демонстрирует, как перебрать поддерживаемые GATT-услуги/характеристики.
    // В этом примере мы заполняем структуру данных, которая привязана к ExpandableListView
    // в интерфейсе пользователя.
    private void displayGattServices(List<BluetoothGattService> gattServices) {
        if (gattServices == null) return;
        String uuid = null;
        String unknownServiceString = getResources().
                getString(R.string.unknown_service);
        String unknownCharaString = getResources().
                getString(R.string.unknown_characteristic);
        ArrayList<HashMap<String, String>> gattServiceData =
                new ArrayList<HashMap<String, String>>();
        ArrayList<ArrayList<HashMap<String, String>>> gattCharacteristicData
                = new ArrayList<ArrayList<HashMap<String, String>>>();
        mGattCharacteristics =
                new ArrayList<ArrayList<BluetoothGattCharacteristic>>();

        // Перебирает доступные GATT-услуги
        for (BluetoothGattService gattService : gattServices) {
            HashMap<String, String> currentServiceData =
                    new HashMap<String, String>();
            uuid = gattService.getUuid().toString();
            currentServiceData.put(
                    LIST_NAME, SampleGattAttributes.
                            lookup(uuid, unknownServiceString));
            currentServiceData.put(LIST_UUID, uuid);
            gattServiceData.add(currentServiceData);

            ArrayList<HashMap<String, String>> gattCharacteristicGroupData =
                    new ArrayList<HashMap<String, String>>();
            List<BluetoothGattCharacteristic> gattCharacteristics =
                    gattService.getCharacteristics();
            ArrayList<BluetoothGattCharacteristic> charas =
                    new ArrayList<BluetoothGattCharacteristic>();

           // Перебирает доступные GATT-характеристики
            for (BluetoothGattCharacteristic gattCharacteristic :
                    gattCharacteristics) {
                charas.add(gattCharacteristic);
                HashMap<String, String> currentCharaData =
                        new HashMap<String, String>();
                uuid = gattCharacteristic.getUuid().toString();
                currentCharaData.put(
                        LIST_NAME, SampleGattAttributes.lookup(uuid,
                                unknownCharaString));
                currentCharaData.put(LIST_UUID, uuid);
                gattCharacteristicGroupData.add(currentCharaData);
            }
            mGattCharacteristics.add(charas);
            gattCharacteristicData.add(gattCharacteristicGroupData);
}    ...    }...}

Получение GATT-уведомлений

Это общие для BLE-приложений запросы для получения уведомлений об изменении отдельных характеристик на устройстве. Этот фрагмент показывает, как настроить уведомление для какой-либо характеристики с помощью метода setCharacteristicNotification():


private BluetoothGatt mBluetoothGatt;
BluetoothGattCharacteristic characteristic;
boolean enabled;
...
mBluetoothGatt.setCharacteristicNotification(characteristic, enabled);
...
BluetoothGattDescriptor descriptor = characteristic.getDescriptor(
        UUID.fromString(SampleGattAttributes.CLIENT_CHARACTERISTIC_CONFIG));
descriptor.setValue(BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE);
mBluetoothGatt.writeDescriptor(descriptor);

Когда уведомления включены для характеристики, вызов onCharacteristicChanged() срабатывает, если характеристика была изменена на удаленном устройстве:

@Override
// Описание характеристики
public void onCharacteristicChanged(BluetoothGatt gatt,
        BluetoothGattCharacteristic characteristic) {
    broadcastUpdate(ACTION_DATA_AVAILABLE, characteristic);
}

Закрытие клиента приложения

Когда приложение завершено с помощью BLE-устройства, оно должно вызывать close(), чтобы система могла должным образом освобождать ресурсы:


public void close() {
    if (mBluetoothGatt == null) {
        return;
    }
    mBluetoothGatt.close();
    mBluetoothGatt = null;
}

BluetoothManager

Менеджер высокого уровня, используемый для получения экземпляра BluetoothAdapter и общего управления Bluetooth. Используйте getSystemService(java.lang.String) с BLUETOOTH_SERVICE чтобы создать BluetoothManager; после этого вызывайте getAdapter() для получения экземпляра BluetoothAdapter. Кроме того, можно просто вызвать BluetoothAdapter.getDefaultAdapter().

Общедоступные методы

BluetoothAdapter getAdapter() [Добавлено в API 18]
Получить стандартный Bluetooth-адаптер данного устройства. Возвращает: Стандартный Bluetooth-адаптер данного устройства.
List<BluetoothDevice> getConnectedDevices (int profile)
[Добавлено в API 18] Получить подключённые устройства указанного профиля. Возвращает набор устройств, которые находятся в состоянии STATE_CONNECTED. Это не относится к любой конфигурации приложения, но отображает состояние Bluetooth-подключения данного профиля. Это может использоваться в приложениях как строка состояния, которая просто хотела бы знать состояние Bluetooth. Требуется разрешение BLUETOOTH. Параметры: GATT или GATT_SERVER Возвращает: Список устройств. При ошибке список будет пуст.
int getConnectionState (BluetoothDevice device, int profile)
[Добавлено в API 18] Получить текущее состояние подключения профиля к удаленному устройству. Это не относится к любой конфигурации приложения, но отображает состояние Bluetooth-подключения данного профиля. Это может использоваться в приложениях как строка состояния, которая просто хотела бы знать состояние Bluetooth. Требуется разрешение BLUETOOTH. Параметры: Удалённое Bluetooth-устройство; GATT или GATT_SERVER. Возвращает: Состояние соединения профиля, одно из: STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING.
List<BluetoothDevice> getDevicesMatchingConnectionStates (int profile, int[] states)
[Добавлено в API 18] Получить список устройств, которые соответствуют любому из указанных состояний соединения. Если ни одно из устройств не соответствует ни одному из указанных состояний, будет возвращён пустой список. Это не относится к любой конфигурации приложения, но представляет состояние подключения локального адаптера Bluetooth для этого профиля. Это может использоваться в приложениях, как в строке состояния, который просто хотел бы знать состояние локального адаптера. Требуется разрешение BLUETOOTH. Параметры: GATT или GATT_SERVER; массив состояний: STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED или STATE_DISCONNECTING. Возвращает: Список устройств. При ошибке список будет пуст.
BluetoothGattServer openGattServer (Context context, BluetoothGattServerCallback callback)
[Добавлено в API 18] Открывает GATT-сервер. Обратный вызов используется для получения результатов, такие как состояние подключения, а также результаты любых других серверных операций в рамках GATT. Метод возвращает экземпляр BluetoothGattServer. Вы можете использовать BluetoothGattServer для проведения операций на сервере в рамках GATT. Параметры: Контекст; обработчика обратных вызовов GATT-сервера, который будет получать асинхронные обратные вызовы. Возвращает: Экземпляр GATT-сервера.

BluetoothGatt

Открытый API для Bluetooth-профидля GATT.

Этот класс обеспечивает функциональность Bluetooth GATT для взаимодействия со смарт-устройствами.

Чтобы подключиться к удалённому периферийному устройству, создайте BluetoothGattCallback и вызовите метод connectGatt(Context, boolean, BluetoothGattCallback), чтобы получить экземпляр этого класса. Устройства, поддерживающие GATT, могут быть найдены с помощью обычного обнаружения Bluetooth-устройств или с помощью сканирования BLE.

Константы

int CONNECTION_PRIORITY_BALANCED (приоритет соединения: сбалансированный)
[Добавлено в API 21]
Обновление параметра соединения: использовать параметры подключения, рекомендованные Bluetooth SIG. Это параметр по-умолчанию, если обновление параметров соединения не требуется. Значение константы: 0 (0x00000000)

int CONNECTION_PRIORITY_HIGH (приоритет соединения: высокий)
[Добавлено в API 21]
Обновление параметра соединения: запрос высокого приоритета, низкой задержки подключения. Приложение должно запрашивать высокий приоритет соединения только для передачи больших объемов данных через BLE. Когда передача будет завершена, приложение должно запросить параметр CONNECTION_PRIORITY_BALANCED для снижения энергопотребления. Значение константы: 1 (0x00000001)

int CONNECTION_PRIORITY_LOW_POWER (приоритет соединения: низкая энергия) [Добавлено в API 21]
Обновление параметра соединения: запрос низкой мощности, снижения скорости передачи данных.
Значение константы: 2 (0x00000002)

int GATT_CONNECTION_CONGESTED
[Добавлено в API 21]
Соединение с удалённым устройством перегружено.
Значение константы: 143 (0x0000008f)

int GATT_FAILURE
[Добавлено в API 18]
Операция с GATT не удалась. Произошла неизвестная ошибка, отличная от указанных выше.
Значение константы: 257 (0x00000101)

int GATT_INSUFFICIENT_AUTHENTICATION
[Добавлено в API 18]
Неподходящая аутентификация для данной операции. Значение константы: 5 (0x00000005)

int GATT_INSUFFICIENT_ENCRYPTION
[Добавлено в API 18]
Неподходящее шифрование для данной операции.
Значение константы: 15 (0x0000000f)

int GATT_INVALID_ATTRIBUTE_LENGTH
[Добавлено в API 18]
Операция записи превышает максимальную длину атрибута.
Значение константы: 13 (0x0000000d)

int GATT_INVALID_OFFSET
[Добавлено в API 18]
Для операции чтения или записи было запрошено недопустимое смещение.
Значение константы: 7 (0x00000007)

int GATT_READ_NOT_PERMITTED
[Добавлено в API 18]
Операция чтения не разрешена.
Значение константы: 2 (0x00000002)

int GATT_REQUEST_NOT_SUPPORTED
[Добавлено в API 18]
Данный запрос не поддерживается.
Значение константы: 6 (0x00000006)

int GATT_SUCCESS
[Добавлено в API 18]
Операция успешно выполнена.
Значение константы: 0 (0x00000000)

int GATT_WRITE_NOT_PERMITTED
[Добавлено в API 18]
Операция записи не разрешена.
Значение константы: 3 (0x00000003)

Общедоступные методы

void abortReliableWrite (BluetoothDevice mDevice) [Добавлено в API 18] Внимание: Этот метод является устаревшим для API уровня 19. Используйте метод abortReliableWrite().

void abortReliableWrite () [Добавлено в API 19] Отменяет надежную транзакцию записи для данного устройства. Вызов этой функции приведет к отклонению всех находящихся в очереди операций записи характеристик для данного удалённого устройства. Требуется разрешение BLUETOOTH.

boolean beginReliableWrite () [Добавлено в API 18] Инициирует надежную транзакцию записи для данного удалённого устройства. После того, как надёжная транзакция записи была начата, все вызовы writeCharacteristic(BluetoothGattCharacteristic) отправляются на удалённое устройство для проверки и выстраиваются в очередь на исполнение. Приложение получает результат в обратном вызове onCharacteristicWrite(BluetoothGatt, BluetoothGattCharacteristic, int) в ответ на каждый вызов writeCharacteristic(BluetoothGattCharacteristic). В этом обратном вызове производится проверка, было ли значение передано точно. После того, как все характеристики в очереди были проверены, executeReliableWrite() выполнит их запись. Если характеристика была записана неправильно, вызов abortReliableWrite() отменит текущую транзакцию без изменения каких-либо значений на удалённом устройстве. Требуется разрешение BLUETOOTH. Возвращает: true, если надёжная транзакция записи была начата.

void close () [Добавлено в API 18] Закрыть Bluetooth GATT-клиент. Приложение должно вызвать этот метод как можно раньше после того, как это делается с текущим GATT-клиентом.

boolean connect () [Добавлено в API 18] Этот метод используется, чтобы повторно подключиться к удалённому устройству после того, как соединение было разорвано. Если устройство не находится в доступном диапазоне, повторное подключение будет произведено, как только устройство окажется доступно. Возвращает: true, если попытка подключения была успешно инициирована.

void disconnect () [Добавлено в API 18] Разрывает установленное соединение или отменяет попытку подключения, происходящую в настоящее время. Требуется разрешение BLUETOOTH.

boolean discoverServices () [Добавлено в API 18] Обнаруживает услуги на удалённом устройстве, а также их характеристики и дескрипторы. Это асинхронная операция. После завершения обнаружения услуг, срабатывает обратный вызов onServicesDiscovered(BluetoothGatt, int). Если обнаружение прошло успешно, удалённые услуги можно получить с помощью функции getServices(). Требуется разрешение BLUETOOTH. Возвращает: true, если обнаружение удалённых услуг было начато.

boolean executeReliableWrite () [Добавлено в API 18] Выполняет надежные транзакции записи для данного удалённого устройства. Эта функция позволяет фиксировать все характеристики, находящиеся в очереди операций записи для указанного удалённого устройства. Обратный вызов onReliableWriteCompleted(BluetoothGatt, int) срабатывает чтобы определить, правильно ли была выполнена операция. Требуется разрешение BLUETOOTH. Возвращает: true, если запрос на выполнение операции был отправлен.

List<BluetoothDevice> getConnectedDevices () [Добавлено в API 18] Не поддерживается. Пожалуйста, используйте BluetoothManager.getConnectedDevices(int) с BluetoothProfile.GATT в качестве аргумента. Возвращает: Список устройств. Список будет пустым при ошибке. Исключения: UnsupportedOperationException

int getConnectionState (BluetoothDevice device) [Добавлено в API 18] Не поддерживается. Пожалуйста, используйте BluetoothManager.getConnectionState (BluetoothDevice device, int profile). Параметры: Удалённое Bluetooth-устройство Возвращает: Состояние соединеня; одно из: STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING Исключения: UnsupportedOperationException

BluetoothDevice getDevice () [Добавлено в API 18] Возвращает удалённое устройство целевого GATT-склиента.

List<BluetoothDevice> getDevicesMatchingConnectionStates (int[] states) [Добавлено в API 18] Не поддерживается. Пожалуйста, используйте BluetoothManager.getDevicesMatchingConnectionStates (int profile, int[] states) с BluetoothProfile.GATT в качестве первого аргумента. Параметры: Массив состояний; одно из: STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING. Возвращает: Список устройств. Список будет пустым при ошибке. Исключения: UnsupportedOperationException

BluetoothGattService getService (UUID uuid) [Добавлено в API 18] Возвращает BluetoothGattService, если запрашиваемый идентификатор uuid поддерживается на удалённом устройстве. Эта функция требует, чтобы обнаружение услуг было выполнено для данного устройства. Если существует несколько экземпляров одной услуги (с таким же UUID), возвращается первый экземпляр службы. Требуется разрешение BLUETOOTH. Параметры: UUID запрашиваемой услуги. Возвращает: BluetoothGattService, если поддерживается, или NULL, если запрашиваемая услуга не предоставляется удаленным устройством.

List<BluetoothGattService> getServices () [Добавлено в API 18] Возвращает список GATT-услуг, предлагаемых удаленным устройством. Эта функция требует, чтобы обнаружение услуг было выполнено для данного устройства. Требуется разрешение BLUETOOTH. Возвращает: Список услуг удалённого устройства. Пустой список, если обнаружение услуг ещё не было выполнено.

boolean readCharacteristic (BluetoothGattCharacteristic characteristic) [Добавлено в API 18] Запрос на чтение характеристики с удалённого устройства. Это асинхронная операция. Результат операции чтения получает обратный вызов onCharacteristicRead(BluetoothGatt, BluetoothGattCharacteristic, int). Требуется разрешение BLUETOOTH. Параметры: Характеристика для чтения с удалённого устройства. Возвращает: true, если операция чтения была начата успешно.

boolean readDescriptor (BluetoothGattDescriptor descriptor) [Добавлено в API 18] Считывает значение дескриптора удалённого устройства. Как только операция чтения завершена, срабатывает обратный вызов onDescriptorRead(BluetoothGatt, BluetoothGattDescriptor, int), сигнализируя о результате операции. Требуется разрешение BLUETOOTH. Параметры: Дескриптор для чтения с удалённого устройства. Возвращает: true, если операция чтения была начата успешно.

boolean readRemoteRssi () [Добавлено в API 18] Считать RSSI подключённого удалённого устройства. (RSSI – это показатель уровня принимаемого сигнала). Обратный вызов onReadRemoteRssi(BluetoothGatt, int, int) срабатывает, когда значение RSSI было прочитано. Требуется разрешение BLUETOOTH. Возвращает: true, если операция чтения была начата успешно.

boolean requestConnectionPriority (int connectionPriority) [Добавлено в API 21] Запросить обновление параметра соединения. Эта функция отправит запрос на обновление параметра подключения к удалённому устройству. Параметры: Запрашиваемый статус соединения, один из: CONNECTION_PRIORITY_BALANCED, CONNECTION_PRIORITY_HIGH, CONNECTION_PRIORITY_LOW_POWER. Исключения: IllegalArgumentException, если параметры находятся за пределами указанного диапазона.

boolean requestMtu (int mtu) [Добавлено в API 21] Запросить размер MTU, используемого для данного подключения. (MTU – это размер одного неделимого блока данных, передаваемого в текущей сети за одну итерацию). При выполнении запроса на запись (запись без ответа), отправленные данные будут усечены до размера MTU. Эта функция может использоваться, чтобы запросить больший размер MTU, чтобы иметь возможность отправлять больше данных одновременно. Обратный вызов onMtuChanged(BluetoothGatt, int, int) будет указывать, прошла ли эта операция успешно. Требуется разрешение BLUETOOTH. Возвращает: true, если новое значение MTU было запрошено успешно.

boolean setCharacteristicNotification (BluetoothGattCharacteristic characteristic, boolean enable) [Добавлено в API 18] Включить или отключить уведомления/индикацию для данной характеристики. После включения уведомлений для характеристики, обратный вызов onCharacteristicChanged(BluetoothGatt, BluetoothGattCharacteristic) будет срабатывать, если удалённое устройство сообщит, что характеристика изменилась. Требуется разрешение BLUETOOTH. Параметры: Характеристика, для которой необходимо включить уведомления; true, если нужно включить уведомления. Возвращает: true, если запрашиваемое уведомление о был установлен успешно.

boolean writeCharacteristic (BluetoothGattCharacteristic characteristic) [Добавлено в API 18] Записывает указанную характеристику и её значение на удалённое связанное устройство. После того, как операция записи будет завершена, сработает обратный вызов onCharacteristicWrite(BluetoothGatt, BluetoothGattCharacteristic, int) с результатом операции. Требуется разрешение BLUETOOTH. Параметры: Характеристика для записи на удалённом устройстве. Возвращает: true, если операция записи была начата успешно.

boolean writeDescriptor (BluetoothGattDescriptor descriptor) [Добавлено в API 18] Записывает значение дескриптора на соединённое устройство. Обратный вызов onDescriptorWrite(BluetoothGatt, BluetoothGattDescriptor, int) срабатывает чтобы сообщить о результате операции. Требуется разрешение BLUETOOTH. Параметры: Дескрипотр для записи на удалённом устройстве. Возвращает: true, если операция записи была начата успешно.

BluetoothGattCallback

void onCharacteristicChanged (BluetoothGatt gatt, BluetoothGattCharacteristic characteristic) [Добавлено в API 18] Обратный вызов инициируется в результате получения уведомления от удалённой характеристики. Параметры: GATT-клиент; характеристика, обновлённая в результате удалённого уведомления.

void onCharacteristicRead (BluetoothGatt gatt, BluetoothGattCharacteristic characteristic, int status) [Добавлено в API 18] Обратный вызов, сообщающий результат чтения удалённой характеристики. Параметры: GATT-клиент, вызвавший readCharacteristic; характеристика, чьё значение было прочитано; статус: GATT_SUCCESS, если операция чтения была успено завершена.

void onCharacteristicWrite (BluetoothGatt gatt, BluetoothGattCharacteristic characteristic, int status) [Добавлено в API 18] Обратный вызов с указанием результата операции записи характеристики. Если этот обратный вызов срабатывает в то время, как надёжная транзакция записи находится в процессе, то значение характеристики представляет собой значение, указанное удалённым устройством. Прикладная программа должна сравнить эту величину с требуемым значением для записи. Если значения не совпадают, то приложение должно прервать транзакцию надежной записи. Параметры: GATT-клиент, вызвавший writeCharacheristic; записываемая характеристика; статус: GATT_SUCCESS, если операция записи была проведена успешно.

void onConnectionStateChange (BluetoothGatt gatt, int status, int newState) [Добавлено в API 18] Обратный вызов, срабатывающий при подключении к удалённому GATT-серверу или отключении от него. Параметры: GATT-клиент, вызвавший подключение/отключение; статус: GATT_SUCCESS, если операция подключения/отключения прошла успешно; новое состояние соединения: STATE_CONNECTED или STATE_DICONNECTED.

void onDescriptorRead (BluetoothGatt gatt, BluetoothGattDescriptor descriptor, int status) [Добавлено в API 18] Обратный вызов, сообщающий о результате операции прочтения дескриптора. Параметры: GATT-клиент, вызвавший readDescriptor; дескриптор, прочитанный на удалённом устройстве; статус: GATT_SUCCESS, если операция записи была проведена успешно.

void onDescriptorWrite (BluetoothGatt gatt, BluetoothGattDescriptor descriptor, int status) [Добавлено в API 18] Обратный вызов, сообщающий о результате операции записи дескриптора.

Параметры: GATT-клиент, вызвавший readDescriptor; дескриптор, прочитанный на удалённом устройстве; статус: GATT_SUCCESS, если операция записи была проведена успешно.

void onMtuChanged (BluetoothGatt gatt, int mtu, int status) [Добавлено в API 21] Обратный вызов, сообщающий об изменении MTU для данного соединения. Этот обратный вызов срабатывает в ответ на функцию requestMtu(int) или в ответ на событие соединения. Параметры: GATT-клиент, вызвавший requestMtu; новый размер MTU; статус: GATT_SUCCESS, если операция записи была проведена успешно.

void onReadRemoteRssi (BluetoothGatt gatt, int rssi, int status) [Добавлено в API 18] Обратный вызов, сообщающий RSSI для данного соединения. Этот обратный вызов срабатывает при вызове readRemoteRssi(). Параметры: GATT-клиент, вызвавший readRemoteRssi(); значение RSSI удалённого устройства; статус: GATT_SUCCESS, если операция записи была проведена успешно.

void onReliableWriteCompleted (BluetoothGatt gatt, int status) [Добавлено в API 18] Обратный вызов, срабатывающий при завершении транзакции надёжной записи. Параметры: GATT-клиент, вызвавший executeReliableWrite(); статус: GATT_SUCCESS, если операция записи была проведена успешно.

void onServicesDiscovered (BluetoothGatt gatt, int status) [Добавлено в API 18] Обратный вызов, срабатывающий когда список удалённых услуг, характеристик и дескрипторов удалённого устройства был обновлён, т.е. были обнаружены новые услуги. Параметры: GATT-клиент, вызвавший discoverServices(); статус: GATT_SUCCESS, если операция записи была проведена успешно.

Реклама