Bluetooth ble android studio

Bluetooth Low Energy

In this document

Key classes

Related samples

See Also

Video

DevBytes: Bluetooth Low Energy API

Android 4.3 (API Level 18) introduces built-in platform support for Bluetooth Low Energy in the central role and provides APIs that apps can use to discover devices, query for services, and read/write characteristics. In contrast to Classic Bluetooth, Bluetooth Low Energy (BLE) is designed to provide significantly lower power consumption. This allows Android apps to communicate with BLE devices that have low power requirements, such as proximity sensors, heart rate monitors, fitness devices, and so on.

Key Terms and Concepts

Here is a summary of key BLE terms and concepts:

• Generic Attribute Profile (GATT)—The GATT profile is a general specification for sending and receiving short pieces of data known as «attributes» over a BLE link. All current Low Energy application profiles are based on GATT.
  • The Bluetooth SIG defines many profiles for Low Energy devices. A profile is a specification for how a device works in a particular application. Note that a device can implement more than one profile. For example, a device could contain a heart rate monitor and a battery level detector.
• Attribute Protocol (ATT)—GATT is built on top of the Attribute Protocol (ATT). This is also referred to as GATT/ATT. ATT is optimized to run on BLE devices. To this end, it uses as few bytes as possible. Each attribute is uniquely identified by a Universally Unique Identifier (UUID), which is a standardized 128-bit format for a string ID used to uniquely identify information. The attributes transported by ATT are formatted as characteristics and services.
• Characteristic—A characteristic contains a single value and 0-n descriptors that describe the characteristic’s value. A characteristic can be thought of as a type, analogous to a class.
• Descriptor—Descriptors are defined attributes that describe a characteristic value. For example, a descriptor might specify a human-readable description, an acceptable range for a characteristic’s value, or a unit of measure that is specific to a characteristic’s value.
• Service—A service is a collection of characteristics. For example, you could have a service called «Heart Rate Monitor» that includes characteristics such as «heart rate measurement.» You can find a list of existing GATT-based profiles and services on bluetooth.org.

Roles and Responsibilities

Here are the roles and responsibilities that apply when an Android device interacts with a BLE device:

• Central vs. peripheral. This applies to the BLE connection itself. The device in the central role scans, looking for advertisement, and the device in the peripheral role makes the advertisement.
• GATT server vs. GATT client. This determines how two devices talk to each other once they’ve established the connection.

To understand the distinction, imagine that you have an Android phone and an activity tracker that is a BLE device. The phone supports the central role; the activity tracker supports the peripheral role (to establish a BLE connection you need one of each—two things that only support peripheral couldn’t talk to each other, nor could two things that only support central).

Once the phone and the activity tracker have established a connection, they start transferring GATT metadata to one another. Depending on the kind of data they transfer, one or the other might act as the server. For example, if the activity tracker wants to report sensor data to the phone, it might make sense for the activity tracker to act as the server. If the activity tracker wants to receive updates from the phone, then it might make sense for the phone to act as the server.

In the example used in this document, the Android app (running on an Android device) is the GATT client. The app gets data from the GATT server, which is a BLE heart rate monitor that supports the Heart Rate Profile. But you could alternatively design your Android app to play the GATT server role. See BluetoothGattServer for more information.

BLE Permissions

In order to use Bluetooth features in your application, you must declare the Bluetooth permission BLUETOOTH . You need this permission to perform any Bluetooth communication, such as requesting a connection, accepting a connection, and transferring data.

If you want your app to initiate device discovery or manipulate Bluetooth settings, you must also declare the BLUETOOTH_ADMIN permission. Note: If you use the BLUETOOTH_ADMIN permission, then you must also have the BLUETOOTH permission.

Declare the Bluetooth permission(s) in your application manifest file. For example:

If you want to declare that your app is available to BLE-capable devices only, include the following in your app’s manifest:

However, if you want to make your app available to devices that don’t support BLE, you should still include this element in your app’s manifest, but set required=»false» . Then at run-time you can determine BLE availability by using PackageManager.hasSystemFeature() :

Setting Up BLE

Before your application can communicate over BLE, you need to verify that BLE is supported on the device, and if so, ensure that it is enabled. Note that this check is only necessary if is set to false.

If BLE is not supported, then you should gracefully disable any BLE features. If BLE is supported, but disabled, then you can request that the user enable Bluetooth without leaving your application. This setup is accomplished in two steps, using the BluetoothAdapter .

The BluetoothAdapter is required for any and all Bluetooth activity. The BluetoothAdapter represents the device’s own Bluetooth adapter (the Bluetooth radio). There’s one Bluetooth adapter for the entire system, and your application can interact with it using this object. The snippet below shows how to get the adapter. Note that this approach uses )»>getSystemService() to return an instance of BluetoothManager , which is then used to get the adapter. Android 4.3 (API Level 18) introduces BluetoothManager :

Next, you need to ensure that Bluetooth is enabled. Call isEnabled() to check whether Bluetooth is currently enabled. If this method returns false, then Bluetooth is disabled. The following snippet checks whether Bluetooth is enabled. If it isn’t, the snippet displays an error prompting the user to go to Settings to enable Bluetooth:

If you want to scan for only specific types of peripherals, you can instead call startLeScan(UUID[], BluetoothAdapter.LeScanCallback) , providing an array of UUID objects that specify the GATT services your app supports.

Here is an implementation of the BluetoothAdapter.LeScanCallback , which is the interface used to deliver BLE scan results:

Note: You can only scan for Bluetooth LE devices or scan for Classic Bluetooth devices, as described in Bluetooth. You cannot scan for both Bluetooth LE and classic devices at the same time.

Connecting to a GATT Server

The first step in interacting with a BLE device is connecting to it— more specifically, connecting to the GATT server on the device. To connect to a GATT server on a BLE device, you use the connectGatt() method. This method takes three parameters: a Context object, autoConnect (boolean indicating whether to automatically connect to the BLE device as soon as it becomes available), and a reference to a BluetoothGattCallback :

This connects to the GATT server hosted by the BLE device, and returns a BluetoothGatt instance, which you can then use to conduct GATT client operations. The caller (the Android app) is the GATT client. The BluetoothGattCallback is used to deliver results to the client, such as connection status, as well as any further GATT client operations.

In this example, the BLE app provides an activity ( DeviceControlActivity ) to connect, display data, and display GATT services and characteristics supported by the device. Based on user input, this activity communicates with a Service called BluetoothLeService , which interacts with the BLE device via the Android BLE API:

When a particular callback is triggered, it calls the appropriate broadcastUpdate() helper method and passes it an action. Note that the data parsing in this section is performed in accordance with the Bluetooth Heart Rate Measurement profile specifications:

Back in DeviceControlActivity , these events are handled by a BroadcastReceiver :

Reading BLE Attributes

Once your Android app has connected to a GATT server and discovered services, it can read and write attributes, where supported. For example, this snippet iterates through the server’s services and characteristics and displays them in the UI:

Receiving GATT Notifications

It’s common for BLE apps to ask to be notified when a particular characteristic changes on the device. This snippet shows how to set a notification for a characteristic, using the setCharacteristicNotification() method:

Once notifications are enabled for a characteristic, an onCharacteristicChanged() callback is triggered if the characteristic changes on the remote device:

Closing the Client App

Once your app has finished using a BLE device, it should call close() so the system can release resources appropriately:

Источник

Bluetooth Low Energy

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

Протокол 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:

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

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

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

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

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

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

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

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

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

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

BluetoothManager

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

BluetoothAdapter getAdapter() [Добавлено в API 18] Получить стандартный Bluetooth-адаптер данного устройства. Возвращает: Стандартный Bluetooth-адаптер данного устройства. List 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 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 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 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 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, если операция записи была проведена успешно.

Источник