D-Bus интерфейс Adapter

Интерфейс позволяет управлять подключением устройств.


Шина:	системная
Служба:	`org.bluez`
Объект:	`[variable prefix]/{hci0,hci1,...}`
Интерфейс:	`org.bluez.Adapter1`

Свойства

Address : string [только для чтения]
AddressType : string [только для чтения]
Alias : string
Class : uint32 [только для чтения]
Discoverable : boolean
DiscoverableTimeout : uint32
Discovering : boolean [только для чтения]
experimentalFeatures : array{string} [только для чтения, опционально]
Modalias : string [только для чтения, опционально]
Name : string [только для чтения]
Pairable : boolean
PairableTimeout : uint32
Powered : boolean [только для чтения]
Roles : array{string} [только для чтения]
UUIDs : array{string} [только для чтения]

Методы

object ConnectDevice(dict properties) [экспериментально]
array{string} GetDiscoveryFilters()
RemoveDevice(object device)
SetDiscoveryFilter(dict filter)
StartDiscovery()
StopDiscovery()

Подробное описание

Интерфейс содержит методы для поиска, подключения и отключения устройств, а также свойства, предоставляющие информацию о локальном устройстве.

Описание свойств

Address : string [только для чтения]

Адрес Bluetooth-устройства.

AddressType : string [только для чтения]

Тип адреса Bluetooth. Для адаптера с двумя режимами и адаптера, поддерживающего только BR/EDR по умолчанию используется значение public. Адаптеры LE с одним режимом могут иметь любое значение. При включённом конфиденциальном режиме он содержит тип идентификационного адреса, а не тип адреса, используемого для подключения.

Возможные значения:

public — публичный адрес;
random — случайный адрес.

Alias : string

Псевдоним для Bluetooth-соединения. Это значение можно изменить.

Если псевдоним не установлен, будет возвращено предоставленное системой имя. Установка пустой строки в качестве псевдонима преобразует её обратно в имя, предоставленное системой.

В хорошо сконфигурированной системе это свойство никогда не нужно изменять, так как по умолчанию оно эквивалентно имени системы и предоставляет красивое имя хоста. Это свойство следует использовать, только если локальное имя должно отличаться от красивого имени хоста.

Class : uint32 [только для чтения]

Класс Bluetooth-устройства.

Это свойство представляет значение, которое либо автоматически настраивается информацией DMI/ACPI, либо предоставляется как статическая конфигурация.

Discoverable : boolean

Можно переключить адаптер на обнаруживаемый или необнаруживаемый, чтобы сделать его видимым или скрыть. Это глобальная настройка, и её следует использовать только в приложении настроек.

Если для свойства DiscoverableTimeout задано ненулевое значение, система установит Discoverable обратно на false после истечения времени таймера.

Если адаптер выключен, установить свойство не удастся.

При изменении свойства Powered новое состояние этого свойства будет обновляться с помощью сигнала PropertiesChanged.

Для любого нового адаптера свойство по умолчанию имеет значение false.

DiscoverableTimeout : uint32

Тайм-аут поиска в секундах. Нулевое значение означает, что тайм-аут отключён, и адаптер навсегда останется в режиме обнаружения/ограничения.

Значение по умолчанию для времени ожидания обнаружения устройств должно составлять 180 секунд (3 минуты).

Discovering : boolean [только для чтения]

Указывает, что процедура обнаружения устройств активна.

experimentalFeatures : array{string} [только для чтения, опционально]

Список 128-битных UUID, представляющих включённые экспериментальные функции.

Modalias : string [только для чтения, опционально]

Информация об идентификаторе локального устройства в формате modalias, используемом ядром и udev.

Name : string [только для чтения]

Имя Bluetooth-системы (красивое имя хоста).

Это свойство является либо статическим системным значением по умолчанию, либо управляется внешним демоном, обеспечивающим доступ к конфигурации красивого имени хоста.

Pairable : boolean

Переключает адаптер на парный или непарный. Это глобальная настройка, и её следует использовать только в приложении настроек.

Следует обратить внимание, что это свойство влияет только на входящие запросы на сопряжение.

Для любого нового адаптера свойство по умолчанию имеет значение true.

PairableTimeout : uint32

Время ожидания сопряжённого устройства в секундах. Нулевое значение означает, что тайм-аут отключён, и адаптер навсегда останется в режиме сопряжения.

Значение по умолчанию для парного тайм-аута должно быть отключено (значение 0).

Powered : boolean [только для чтения]

Включает или выключает адаптер. Свойство также установит соответствующее состояние подключения контроллера.

Значение свойства не является постоянным. После перезагрузки или отключения адаптера оно снова сбрасывается на false.

Roles : array{string} [только для чтения]

Список поддерживаемых ролей. Возможные значения:

central — поддерживает центральную роль;
peripheral — поддерживает периферийную роль;
central-peripheral — поддерживает обе роли одновременно.

UUIDs : array{string} [только для чтения]

Список 128-битных UUID, представляющих доступные локальные службы.

Описание методов

object ConnectDevice(dict properties) [экспериментально]

Подключается к устройству без необходимости выполнения общего поиска. Механизм соединения аналогичен методу Connect() из интерфейса Device1, за исключением того, что этот метод успешно возвращает объект при установлении физического соединения. После возврата этого метода обнаружение служб продолжится, и будет подключён любой поддерживаемый профиль.

После вызова данного метода нет необходимости вызывать Connect() на Device1. Если соединение было успешным, метод возвращает путь к созданному объекту устройства.

Объект фильтра представляет собой словарь, который может включать следующие параметры:

string Address: Адрес Bluetooth-устройства. Этот параметр является обязательным.
string AddressType: Тип адреса Bluetooth-устройства, который следует использовать для первоначального подключения. Если этот параметр отсутствует, создаётся устройство BR/EDR. Возможные значения:

public — публичный адрес;
random — случайный адрес.

Возможные ошибки:

org.bluez.Error.InvalidArguments,
org.bluez.Error.AlreadyExists,
org.bluez.Error.NotSupported,
org.bluez.Error.NotReady,
org.bluez.Error.Failed.

array{string} GetDiscoveryFilters()

Возвращает доступные фильтры, которые можно передать SetDiscoveryFilter().

Возможные ошибки отсутствуют.

RemoveDevice(object device)

Удаляет объект устройства по заданному пути. Метод также удалит информацию о сопряжении.

Возможные ошибки:

org.bluez.Error.InvalidArguments,
org.bluez.Error.Failed.

SetDiscoveryFilter(dict filter)

Устанавливает фильтр обнаружения устройств. Когда этот метод вызывается без аргументов, фильтр удаляется.

Объект фильтра представляет собой словарь, который может включать следующие параметры:

array{string} UUIDs: Фильтровать по сервисным UUID, пустое значение означает соответствие любому UUID.

Когда будет найдено устройство, которое имеет какой-либо UUID из данного списка, оно пройдёт фильтр, если:

Pathloss и RSSI пусты.
Установлен только параметр Pathloss, устройство объявляет мощность TX, а вычисленные убытки меньше, чем параметр Pathloss.
Установлен только параметр RSSI, и полученный RSSI выше, чем RSSI, указанный в фильтре.

int16 RSSI: Пороговое значение RSSI.

Сигналы PropertiesChanged будут испускаться для уже существующих объектов Device с обновлённым значением RSSI. Если установлены один или несколько фильтров обнаружения, дельта-порог RSSI, налагаемый StartDiscovery() по умолчанию, применяться не будет.

uint16 Pathloss: Пороговое значение убытков. Сигналы PropertiesChanged будут испускаться для уже существующих объектов Device с обновлённым значением Pathloss.
string Transport (по умолчанию "auto"): Тип сканирования. Возможные значения:

auto — сканирование с чередованием;
bredr — запрос BR/EDR;
le — только сканирование LE.

Если запрошен тип le или bredr, а контроллер его не поддерживает, будет возвращена ошибка org.bluez.Error.Failed. Если запрашивается тип auto, сканирование будет использовать LE, BREDR или оба варианта, в зависимости от того, что в данный момент включено на контроллере.

bool DuplicateData (по умолчанию: true): Отключить обнаружение дубликатов данных. Когда параметр включён, сигналы PropertiesChanged будут генерироваться либо для ManufacturerData, либо для ServiceData каждый раз при их обнаружении.
bool Discoverable (по умолчанию: false): Сделать адаптер доступным для обнаружения во время поиска. Если адаптер уже доступен для обнаружения, этот фильтр ничего не сделает.
string Pattern (по умолчанию: none): Искать устройства, для которых шаблон соответствует либо префиксу адреса, либо имени устройства. Это удобный способ ограничить количество объектов устройств, созданных во время обнаружения. При установке игнорирует флаги обнаружения устройств.

Примечание. Сопоставление шаблона игнорируется, если есть другой клиент, который не устанавливает шаблон, поскольку он работает как логическое ИЛИ. Установка шаблона пустой строки "" будет соответствовать любому найденному устройству.

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

Когда несколько клиентов вызывают SetDiscoveryFilter(), их фильтры внутренне объединяются, а уведомления о новых устройствах отправляются всем клиентам. Поэтому каждый клиент должен проверять, действительно ли параметры устройства соответствуют его фильтру.

Когда SetDiscoveryFilter() вызывается одним и тем же клиентом несколько раз, для данного клиента будет активен последний переданный фильтр.

SetDiscoveryFilter() можно вызвать перед StartDiscovery(). Это полезно, когда клиент будет создавать первый сеанс поиска, чтобы убедиться, что корректное сканирование будет запущено сразу после вызова StartDiscovery().

Возможные ошибки:

org.bluez.Error.NotReady,
org.bluez.Error.NotSupported,
org.bluez.Error.Failed.

StartDiscovery()

Запускает сеанс обнаружения устройств. Сеанс включает в себя процедуру запроса и получения имени удалённого устройства. Следует использовать StopDiscovery(), чтобы завершить проведённые сеансы.

Этот процесс начнёт создавать объекты устройств по мере обнаружения новых устройств.

При обнаружении устройств применяется дельта-порог RSSI.

Каждый клиент может запросить один сеанс обнаружения устройств для каждого адаптера.

Возможные ошибки:

org.bluez.Error.NotReady,
org.bluez.Error.Failed,
org.bluez.Error.InProgress.

StopDiscovery()

Отменяет любую предыдущую транзакцию StartDiscovery().

Следует обратить внимание, что процедура обнаружения является общей для всех сеансов обнаружения, поэтому вызов метода освобождает только один сеанс. Обнаружение прекратится, когда все сеансы от всех клиентов будут завершены.

Возможные ошибки:

org.bluez.Error.NotReady,
org.bluez.Error.Failed,
org.bluez.Error.NotAuthorized.