From patchwork Sat Oct 7 01:01:43 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 731117 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id E6B63E94139 for ; Sat, 7 Oct 2023 01:02:00 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233996AbjJGBB7 (ORCPT ); Fri, 6 Oct 2023 21:01:59 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58924 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233989AbjJGBB6 (ORCPT ); Fri, 6 Oct 2023 21:01:58 -0400 Received: from mail-pg1-x532.google.com (mail-pg1-x532.google.com [IPv6:2607:f8b0:4864:20::532]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 91393BD for ; Fri, 6 Oct 2023 18:01:54 -0700 (PDT) Received: by mail-pg1-x532.google.com with SMTP id 41be03b00d2f7-58916df84c8so1878693a12.3 for ; Fri, 06 Oct 2023 18:01:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696640513; x=1697245313; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:message-id:date:subject:to :from:from:to:cc:subject:date:message-id:reply-to; bh=r7RBPLmDzGivlZggMbmZBgWVPFOALRZSlggaK2gzrmQ=; b=ayU/mZNuiW0kr4uq+GwzTfBrpdOjhSRcd2AX5iiyG5cvs1ccd6qO5NfuLxzC0PWOo+ /iWcFeQVhvz3eSB7vCCWcFAtEQe/oczuw8S11sWhzaw4Vru+BnUnC33W1HF81N+dmX5A AA/BKMw63MZjPvEA6moiomwgwEljf1ImCyWsYukASKbfD58Bd9JUEqhHK9AHOQNLZD9c jahGYsT97JEzvOV3P8Qxoeo/odlrjkOM3HAOJnLA2Jj4DhhSycI3dPzfrWsP9sLycJ+e ydsDKFIM5Tjpb/MmXrcpbhQqOQXAF2fOy+s1pdqU/8sk5Xbgb4QaCGOm7MCTjjyRjtTx 4B2A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696640513; x=1697245313; h=content-transfer-encoding:mime-version:message-id:date:subject:to :from:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=r7RBPLmDzGivlZggMbmZBgWVPFOALRZSlggaK2gzrmQ=; b=Cy5HKAOkgszpeJKWaNPKPUbgnH+TeZFhjojMC6URonsn8mJ/+jx+mFORurRiwImFbO VA79HMEn9gI2fOD0uEcJX9X9zV2yY7YeBqP+nyO7rxuLnTAQfbeLhSdZJo8PLqCpOosY v3vK/pmkUNe22qpzL0nmXr3Lyzpbaho09zAFb+rBDU6Sql8ks2xIplEXUGI83hgsCA0L GezxY3pnyDFgZM3T8PrMqRZl73BKEX9O/lkzKkMnIXCqEokaR6/OZGxQfj/rhs6xhtE6 fHbut57plrySBxaNmjbYJ7jpTYtvWuiZ6IEvpCZJuoeNEX3Jnn3tT4L0eurSQsb4FduF hwBw== X-Gm-Message-State: AOJu0YyxSqB6MbFi2U9CW6x4Q2K9mys2n0JzsgHxjYZC2y+oHvh4Gn+O kK6ZhuMx1QQ2LDUDxPobO03rdl4KYAhoN8hg X-Google-Smtp-Source: AGHT+IG3j2U8nrrxTO6KiS7vQzE7s39x1HfWjV3RUWTplVCyWxvx2s4VqAcrY/hyzOVQjFFXSLCxIw== X-Received: by 2002:a17:90b:38d2:b0:26d:fcd:89b3 with SMTP id nn18-20020a17090b38d200b0026d0fcd89b3mr9856952pjb.8.1696640512332; Fri, 06 Oct 2023 18:01:52 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id co11-20020a17090afe8b00b00279060a0fccsm4098360pjb.9.2023.10.06.18.01.51 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 06 Oct 2023 18:01:51 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH BlueZ 1/8] doc/adapter-api: Rename to org.bluez.Adapter.rst Date: Fri, 6 Oct 2023 18:01:43 -0700 Message-ID: <20231007010150.4103452-1-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames adapter-api.txt to org.bluez.Adapter.rst and generate a manpage org.bluez.Adapter.5. --- Makefile.am | 8 +- doc/adapter-api.txt | 373 ---------------------------------- doc/org.bluez.Adapter.rst | 412 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 416 insertions(+), 377 deletions(-) delete mode 100644 doc/adapter-api.txt create mode 100644 doc/org.bluez.Adapter.rst diff --git a/Makefile.am b/Makefile.am index 8d35dbb55e69..5eb94985a1b7 100644 --- a/Makefile.am +++ b/Makefile.am @@ -357,14 +357,14 @@ CLEANFILES += $(builtin_files) src/bluetooth.service if MANPAGES man_MANS += src/bluetoothd.8 -man_MANS += doc/org.bluez.DeviceSet.5 +man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.DeviceSet.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ doc/org.bluez.MediaTransport.5 endif manual_pages += src/bluetoothd.8 -manual_pages += doc/org.bluez.DeviceSet.5 +manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.DeviceSet.5 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -405,12 +405,12 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \ doc/settings-storage.txt EXTRA_DIST += doc/mgmt-api.txt \ - doc/adapter-api.txt doc/device-api.txt \ + doc/device-api.txt \ doc/agent-api.txt doc/profile-api.txt \ doc/network-api.txt doc/health-api.txt \ doc/sap-api.txt doc/input-api.txt -EXTRA_DIST += doc/org.bluez.DeviceSet.rst +EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.DeviceSet.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/adapter-api.txt b/doc/adapter-api.txt deleted file mode 100644 index 10c290c62fe2..000000000000 --- a/doc/adapter-api.txt +++ /dev/null @@ -1,373 +0,0 @@ -BlueZ D-Bus Adapter API description -*********************************** - - -Adapter hierarchy -================= - -Service org.bluez -Interface org.bluez.Adapter1 -Object path [variable prefix]/{hci0,hci1,...} - -Methods void StartDiscovery() - - This method starts the device discovery session. This - includes an inquiry procedure and remote device name - resolving. Use StopDiscovery to release the sessions - acquired. - - This process will start creating Device objects as - new devices are discovered. - - During discovery RSSI delta-threshold is imposed. - - Each client can request a single device discovery session - per adapter. - - Possible errors: org.bluez.Error.NotReady - org.bluez.Error.Failed - org.bluez.Error.InProgress - - void StopDiscovery() - - This method will cancel any previous StartDiscovery - transaction. - - Note that a discovery procedure is shared between all - discovery sessions thus calling StopDiscovery will only - release a single session and discovery will stop when - all sessions from all clients have finished. - - Possible errors: org.bluez.Error.NotReady - org.bluez.Error.Failed - org.bluez.Error.NotAuthorized - - void RemoveDevice(object device) - - This removes the remote device object at the given - path. It will remove also the pairing information. - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.Failed - - void SetDiscoveryFilter(dict filter) - - This method sets the device discovery filter for the - caller. When this method is called with no filter - parameter, filter is removed. - - Parameters that may be set in the filter dictionary - include the following: - - array{string} UUIDs - - Filter by service UUIDs, empty means match - _any_ UUID. - - When a remote device is found that advertises - any UUID from UUIDs, it will be reported if: - - Pathloss and RSSI are both empty. - - only Pathloss param is set, device advertise - TX pwer, and computed pathloss is less than - Pathloss param. - - only RSSI param is set, and received RSSI is - higher than RSSI param. - - int16 RSSI - - RSSI threshold value. - - PropertiesChanged signals will be emitted - for already existing Device objects, with - updated RSSI value. If one or more discovery - filters have been set, the RSSI delta-threshold, - that is imposed by StartDiscovery by default, - will not be applied. - - uint16 Pathloss - - Pathloss threshold value. - - PropertiesChanged signals will be emitted - for already existing Device objects, with - updated Pathloss value. - - string Transport (Default "auto") - - Transport parameter determines the type of - scan. - - Possible values: - "auto" - interleaved scan - "bredr" - BR/EDR inquiry - "le" - LE scan only - - If "le" or "bredr" Transport is requested, - and the controller doesn't support it, - org.bluez.Error.Failed error will be returned. - If "auto" transport is requested, scan will use - LE, BREDR, or both, depending on what's - currently enabled on the controller. - - bool DuplicateData (Default: true) - - Disables duplicate detection of advertisement - data. - - When enabled PropertiesChanged signals will be - generated for either ManufacturerData and - ServiceData everytime they are discovered. - - bool Discoverable (Default: false) - - Make adapter discoverable while discovering, - if the adapter is already discoverable setting - this filter won't do anything. - - string Pattern (Default: none) - - Discover devices where the pattern matches - either the prefix of the address or - device name which is convenient way to limited - the number of device objects created during a - discovery. - - When set disregards device discoverable flags. - - Note: The pattern matching is ignored if there - are other client that don't set any pattern as - it work as a logical OR, also setting empty - string "" pattern will match any device found. - - When discovery filter is set, Device objects will be - created as new devices with matching criteria are - discovered regardless of they are connectable or - discoverable which enables listening to - non-connectable and non-discoverable devices. - - When multiple clients call SetDiscoveryFilter, their - filters are internally merged, and notifications about - new devices are sent to all clients. Therefore, each - client must check that device updates actually match - its filter. - - When SetDiscoveryFilter is called multiple times by the - same client, last filter passed will be active for - given client. - - SetDiscoveryFilter can be called before StartDiscovery. - It is useful when client will create first discovery - session, to ensure that proper scan will be started - right after call to StartDiscovery. - - Possible errors: org.bluez.Error.NotReady - org.bluez.Error.NotSupported - org.bluez.Error.Failed - - array{string} GetDiscoveryFilters() - - Return available filters that can be given to - SetDiscoveryFilter. - - Possible errors: None - - object ConnectDevice(dict properties) [experimental] - - This method connects to device without need of - performing General Discovery. Connection mechanism is - similar to Connect method from Device1 interface with - exception that this method returns success when physical - connection is established and you can specify bearer to - connect with parameter. After this method returns, - services discovery will continue and any supported - profile will be connected. There is no need for calling - Connect on Device1 after this call. If connection was - successful this method returns object path to created - device object or device that already exist. - - Parameters that may be set in the filter dictionary - include the following: - - string Address - - The Bluetooth device address of the remote - device. This parameter is mandatory. - - string AddressType - - The Bluetooth device Address Type. This is - address type that should be used for initial - connection. If this parameter is not present - BR/EDR device is created. - - Possible values: - "public" - Public address - "random" - Random address - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.AlreadyExists - org.bluez.Error.NotSupported - org.bluez.Error.NotReady - org.bluez.Error.Failed - -Properties string Address [readonly] - - The Bluetooth device address. - - string AddressType [readonly] - - The Bluetooth Address Type. For dual-mode and BR/EDR - only adapter this defaults to "public". Single mode LE - adapters may have either value. With privacy enabled - this contains type of Identity Address and not type of - address used for connection. - - Possible values: - "public" - Public address - "random" - Random address - - string Name [readonly] - - The Bluetooth system name (pretty hostname). - - This property is either a static system default - or controlled by an external daemon providing - access to the pretty hostname configuration. - - string Alias [readwrite] - - The Bluetooth friendly name. This value can be - changed. - - In case no alias is set, it will return the system - provided name. Setting an empty string as alias will - convert it back to the system provided name. - - When resetting the alias with an empty string, the - property will default back to system name. - - On a well configured system, this property never - needs to be changed since it defaults to the system - name and provides the pretty hostname. Only if the - local name needs to be different from the pretty - hostname, this property should be used as last - resort. - - uint32 Class [readonly] - - The Bluetooth class of device. - - This property represents the value that is either - automatically configured by DMI/ACPI information - or provided as static configuration. - - boolean Powered [readwrite] - - Switch an adapter on or off. This will also set the - appropriate connectable state of the controller. - - The value of this property is not persistent. After - restart or unplugging of the adapter it will reset - back to false. - - string PowerState [readonly, experimental] - - The power state of an adapter. - - The power state will show whether the adapter is - turning off, or turning on, as well as being on - or off. - - Possible values: - "on" - powered on - "off" - powered off - "off-enabling" - transitioning from "off" to "on" - "on-disabling" - transitioning from "on" to "off" - "off-blocked" - blocked by rfkill - - boolean Discoverable [readwrite] - - Switch an adapter to discoverable or non-discoverable - to either make it visible or hide it. This is a global - setting and should only be used by the settings - application. - - If the DiscoverableTimeout is set to a non-zero - value then the system will set this value back to - false after the timer expired. - - In case the adapter is switched off, setting this - value will fail. - - When changing the Powered property the new state of - this property will be updated via a PropertiesChanged - signal. - - For any new adapter this settings defaults to false. - - boolean Pairable [readwrite] - - Switch an adapter to pairable or non-pairable. This is - a global setting and should only be used by the - settings application. - - Note that this property only affects incoming pairing - requests. - - For any new adapter this settings defaults to true. - - uint32 PairableTimeout [readwrite] - - The pairable timeout in seconds. A value of zero - means that the timeout is disabled and it will stay in - pairable mode forever. - - The default value for pairable timeout should be - disabled (value 0). - - uint32 DiscoverableTimeout [readwrite] - - The discoverable timeout in seconds. A value of zero - means that the timeout is disabled and it will stay in - discoverable/limited mode forever. - - The default value for the discoverable timeout should - be 180 seconds (3 minutes). - - boolean Discovering [readonly] - - Indicates that a device discovery procedure is active. - - array{string} UUIDs [readonly] - - List of 128-bit UUIDs that represents the available - local services. - - string Modalias [readonly, optional] - - Local Device ID information in modalias format - used by the kernel and udev. - - array{string} Roles [readonly] - - List of supported roles. Possible values: - "central": Supports the central role. - "peripheral": Supports the peripheral role. - "central-peripheral": Supports both roles - concurrently. - - array{string} ExperimentalFeatures [readonly, optional] - - List of 128-bit UUIDs that represents the experimental - features currently enabled. - - uint16 Manufacturer [readonly] - - The manufacturer of the device, as a uint16 company - identifier defined by the Core Bluetooth Specification. - - byte Version [readonly] - - The Bluetooth version supported by the device, as a - core version code defined by the Core Bluetooth - Specification. diff --git a/doc/org.bluez.Adapter.rst b/doc/org.bluez.Adapter.rst new file mode 100644 index 000000000000..f537281238e4 --- /dev/null +++ b/doc/org.bluez.Adapter.rst @@ -0,0 +1,412 @@ +================= +org.bluez.Adapter +================= + +------------------------------------- +BlueZ D-Bus Adapter API documentation +------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.Adapter1 +:Object path: [variable prefix]/{hci0,hci1,...} + +Methods +------- + +void StartDiscovery() +````````````````````` + + Starts device discovery session which may include starting an inquiry + and/or scanning procedures and remote device name resolving. + + Use **StopDiscovery** to release the sessions acquired. + + This process will start creating Device objects as new devices are + discovered. + + During discovery RSSI delta-threshold is imposed. + + Each client can request a single device discovery session per adapter. + + Possible errors: + + :org.bluez.Error.NotReady: + :org.bluez.Error.Failed: + :org.bluez.Error.InProgress: + +void StopDiscovery() +```````````````````` + + Stops device discovery session started by **StartDiscovery**. + + Note that a discovery procedure is shared between all discovery sessions + thus calling StopDiscovery will only release a single session and + discovery will stop when all sessions from all clients have finished. + + Possible errors: + + :org.bluez.Error.NotReady: + :org.bluez.Error.Failed: + :org.bluez.Error.NotAuthorized: + +void RemoveDevice(object device) +```````````````````````````````` + + Removes the remote device object at the given path including cahed + information such as bonding information. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.Failed: + +void SetDiscoveryFilter(dict filter) +```````````````````````````````````` + + Sets the device discovery filter for the caller. When this method is + called with no filter parameter, filter is removed. + + Possible filter values: + + :array{string} UUIDs: + + Filter by service UUIDs, empty means match *any* UUID. + + When a remote device is found that advertises any UUID from + UUIDs, it will be reported if: + + - **Pathloss** and **RSSI** are both empty. + - only **Pathloss** param is set, device advertise TX power, and + computed pathloss is less than Pathloss param. + - only **RSSI** param is set, and received RSSI is higher + than RSSI param. + + :int16 RSSI: + + RSSI threshold value. + + PropertiesChanged signals will be emitted for already existing + Device objects, with updated RSSI value. If one or more + discovery filters have been set, the RSSI delta-threshold, that + is imposed by StartDiscovery by default, will not be applied. + + :uint16 Pathloss: + + Pathloss threshold value. + + PropertiesChanged signals will be emitted for already existing + Device objects, with updated Pathloss value. + + :string Transport (Default "auto"): + + Transport parameter determines the type of scan. + + Possible values: + + :"auto": + + Interleaved scan, use LE, BREDR, or both, depending on + what's currently enabled. + + :"bredr": + + BR/EDR inquiry only. + + :"le": + + LE scan only. + + + :bool DuplicateData (Default true): + + Disables duplicate detection of advertisement data. + + When enabled PropertiesChanged signals will be generated for + either ManufacturerData and ServiceData everytime they are + discovered. + + :bool Discoverable (Default false): + + Make adapter discoverable while discovering, if the adapter is + already discoverable setting this filter won't do anything. + + :string Pattern (Default none): + + Discover devices where the pattern matches either the prefix of + the address or device name which is convenient way to limited + the number of device objects created during a discovery. + + When set disregards device discoverable flags. + + Note: The pattern matching is ignored if there are other client + that don't set any pattern as it work as a logical OR, also + setting empty string "" pattern will match any device found. + + When discovery filter is set, Device objects will be created as + new devices with matching criteria are discovered regardless of + they are connectable or discoverable which enables listening to + non-connectable and non-discoverable devices. + + When multiple clients call SetDiscoveryFilter, their filters are + internally merged, and notifications about new devices are sent + to all clients. Therefore, each client must check that device + updates actually match its filter. + + When SetDiscoveryFilter is called multiple times by the same + client, last filter passed will be active for given client. + + SetDiscoveryFilter can be called before StartDiscovery. + It is useful when client will create first discovery session, + to ensure that proper scan will be started right after call to + StartDiscovery. + + Possible errors: + + :org.bluez.Error.NotReady: + :org.bluez.Error.NotSupported: + :org.bluez.Error.Failed: + +array{string} GetDiscoveryFilters() +``````````````````````````````````` + + Returns available filters that can be given to **SetDiscoveryFilter**. + + Possible errors: None + +object ConnectDevice(dict properties) [experimental] +```````````````````````````````````````````````````` + + connects to device without need of performing General Discovery. + Connection mechanism is similar to Connect method on + **org.bluez.Device1(5)** interface with exception that this method + returns success when physical connection is established and you can + specify bearer to connect with parameter. After this method returns, + services discovery will continue and any supported profile will be + connected. There is no need for calling Connect on Device1 after this + call. If connection was successful this method returns object path to + created device object or device that already exist. + + Possible properties values: + + :string Address (Mandatory): + + The Bluetooth device address of the remote device. + + :string AddressType (Default "BR/EDR"): + + The Bluetooth device Address Type. This is address type that + should be used for initial connection. + + Possible values: + + :"public": + + Public address + + :"random": + + Random address + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.AlreadyExists: + :org.bluez.Error.NotSupported: + :org.bluez.Error.NotReady: + :org.bluez.Error.Failed: + +Properties +---------- + +string Address [readonly] +````````````````````````` + + The Bluetooth device address. + +string AddressType [readonly] +````````````````````````````` + + The Bluetooth Address Type. For dual-mode and BR/EDR only adapter this + defaults to "public". Single mode LE adapters may have either value. + With privacy enabled this contains type of Identity Address and not + type of address used for connection. + + Possible values: + + :"public": + + Public address. + + + :"random: + + Random address. + +string Name [readonly] +`````````````````````` + + The Bluetooth system name (pretty hostname). + + This property is either a static system default or controlled by an + external daemon providing access to the pretty hostname configuration. + +string Alias [readwrite] +```````````````````````` + + The Bluetooth friendly name. This value can be changed. + + In case no alias is set, it will return the system provided name. + Setting an empty string as alias will convert it back to the system + provided name. + + When resetting the alias with an empty string, the property will default + back to system name. + + On a well configured system, this property never needs to be changed + since it defaults to the system name and provides the pretty hostname. + Only if the local name needs to be different from the pretty hostname, + this property should be used as last resort. + +uint32 Class [readonly] +``````````````````````` + + The Bluetooth class of device. + + This property represents the value that is either automatically + configured by DMI/ACPI information or provided as static configuration. + +boolean Powered [readwrite] +``````````````````````````` + + Switch an adapter on or off. This will also set the appropriate + connectable state of the controller. + + The value of this property is not persistent. After restart or + unplugging of the adapter it will reset back to false. + +string PowerState [readonly, experimental] +`````````````````````````````````````````` + + The power state of an adapter. + + The power state will show whether the adapter is turning off, or turning + on, as well as being on or off. + + Possible values: + + :"on": + + Powered on. + + :"off": + + Powered off + + :"off-enabling": + + Transitioning from "off" to "on". + + :"on-disabling": + + Transitioning from "on" to "off". + + :"off-blocked": + + Blocked by rfkill. + +boolean Discoverable [readwrite] (Default: false) +````````````````````````````````````````````````` + + Switch an adapter to discoverable or non-discoverable to either make it + visible or hide it. This is a global setting and should only be used by + the settings application. + + If the DiscoverableTimeout is set to a non-zero value then the system + will set this value back to false after the timer expired. + + In case the adapter is switched off, setting this value will fail. + + When changing the Powered property the new state of this property will + be updated via a PropertiesChanged signal. + +boolean Pairable [readwrite] (Default: true) +```````````````````````````````````````````` + + Switch an adapter to pairable or non-pairable. This is a global setting + and should only be used by the settings application. + + Note that this property only affects incoming pairing requests. + +uint32 PairableTimeout [readwrite] (Default: 0) +``````````````````````````````````````````````` + + The pairable timeout in seconds. A value of zero means that the timeout + is disabled and it will stay in pairable mode forever. + +uint32 DiscoverableTimeout [readwrite] (Default: 180) +````````````````````````````````````````````````````` + + The discoverable timeout in seconds. A value of zero means that the + timeout is disabled and it will stay in discoverable/limited mode + forever. + +boolean Discovering [readonly] +`````````````````````````````` + + Indicates that a device discovery procedure is active. + +array{string} UUIDs [readonly] +`````````````````````````````` + + List of 128-bit UUIDs that represents the available local services. + +string Modalias [readonly, optional] +```````````````````````````````````` + + Local Device ID information in modalias format used by the kernel and + udev. + +array{string} Roles [readonly] +`````````````````````````````` + + List of supported roles. + + Possible values: + + :"central": + + Supports the central role. + + :"peripheral": + + Supports the peripheral role. + + :"central-peripheral": + + Supports both roles concurrently. + +array{string} ExperimentalFeatures [readonly, optional] +``````````````````````````````````````````````````````` + + List of 128-bit UUIDs that represents the experimental features + currently enabled. + +uint16 Manufacturer [readonly] +`````````````````````````````` + + The manufacturer of the device, as a uint16 company identifier defined + by the Core Bluetooth Specification. + +byte Version [readonly] +``````````````````````` + + The Bluetooth version supported by the device, as a core version code + defined by the Core Bluetooth Specification. From patchwork Sat Oct 7 01:01:44 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 730526 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id A02CEE9413D for ; Sat, 7 Oct 2023 01:02:01 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234005AbjJGBCB (ORCPT ); Fri, 6 Oct 2023 21:02:01 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58944 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233999AbjJGBB7 (ORCPT ); Fri, 6 Oct 2023 21:01:59 -0400 Received: from mail-pg1-x532.google.com (mail-pg1-x532.google.com [IPv6:2607:f8b0:4864:20::532]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id F2CC4B6 for ; Fri, 6 Oct 2023 18:01:55 -0700 (PDT) Received: by mail-pg1-x532.google.com with SMTP id 41be03b00d2f7-584a761b301so2015202a12.3 for ; Fri, 06 Oct 2023 18:01:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696640514; x=1697245314; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=CqKUg053lyYsj/ooEOZyT990Wlr0Y5kgkhv8tFgOXzE=; b=W+tv2/kBEOUl3ghbYP0FMq08SKmTKssjCwlVAdZVgEAyJCf5SGhin2RldVQWHg6QFT 6UIHLNsGUFB7QHQYd/UkauB1+//40lHbKR/wfhXwkleVxHiRPA8/KegX8iyiLM/tlsyP 4i8BKlgpJ0ge5sJ/UB9bzLK3vp/74RSoe9MjikAVHI97xgtRgaBqMBTJFVhEgyba6uvJ Xm5y3h7N+Lauic2oBMv7wZUtNLuLwteNijwy76Jfu+dq8NN6FE47LkmwEUJGBVnfFw1d XK9Zn34swNrtkumxoRVwHDsczQhXppX5K6QZbWXz5NuCIiZbWa13rXUBq7jQBdkX/9cV kFTQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696640514; x=1697245314; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=CqKUg053lyYsj/ooEOZyT990Wlr0Y5kgkhv8tFgOXzE=; b=MEyIjP8IzXdIXvBLlCbHX0t7DcUYLaTc35sfYcxUP20KxGrLgbziwxIOud2ccyVWUx dfeDRhCMklCIVuOCT1dx8768XOrz9PIxk9jHuHCjXAa5TwHZxQHFvkJqLYoyZfmWUphZ 56NUTn9bhm+ozKNSCRjPRWqc4ijVpr4cgjg/Kq3cKQzXTx/ina9DpEX+TnAyJu7Hyokq 4Y6i7quqW0kWB7ch8yJzW0K7rcC+wFZheas1B0IRTJ1/MMMA3uZagTzYMoStlL+W1Ary f3noE4W0RSrPqj6o6irhelzkLjkYyaLSY60hVIpaxzgbXqbbbNlSWLRXQzsASAvDvtBB UWlw== X-Gm-Message-State: AOJu0YzX3Cmhtx3e1Y/yq4vWvUsINi6p+QU+a92r9cBxdG0u4VgpIKli +2mW3nMILcSW/U5qkL1Lv/6YSmVaQI/pnQcw X-Google-Smtp-Source: AGHT+IFA8/HYb1VzJ1AN09414Bb5Xz7frls0pm1l0Cly4NNuGf3yVXRHlGoTqA4uXOfbqTtKvcsbQQ== X-Received: by 2002:a05:6a20:f3af:b0:134:30a8:9df5 with SMTP id qr47-20020a056a20f3af00b0013430a89df5mr9155858pzb.43.1696640513766; Fri, 06 Oct 2023 18:01:53 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id co11-20020a17090afe8b00b00279060a0fccsm4098360pjb.9.2023.10.06.18.01.52 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 06 Oct 2023 18:01:53 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH BlueZ 2/8] doc/device-api: Rename to org.bluez.Device.rst Date: Fri, 6 Oct 2023 18:01:44 -0700 Message-ID: <20231007010150.4103452-2-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231007010150.4103452-1-luiz.dentz@gmail.com> References: <20231007010150.4103452-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames device-api.txt to org.bluez.Device.rst and generate a manpage org.bluez.Device.5. --- Makefile.am | 10 +- doc/device-api.txt | 293 ---------------------------------- doc/org.bluez.Device.rst | 329 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 335 insertions(+), 297 deletions(-) delete mode 100644 doc/device-api.txt create mode 100644 doc/org.bluez.Device.rst diff --git a/Makefile.am b/Makefile.am index 5eb94985a1b7..9e74f4f0fc76 100644 --- a/Makefile.am +++ b/Makefile.am @@ -357,14 +357,16 @@ CLEANFILES += $(builtin_files) src/bluetooth.service if MANPAGES man_MANS += src/bluetoothd.8 -man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.DeviceSet.5 +man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ + doc/org.bluez.DeviceSet.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ doc/org.bluez.MediaTransport.5 endif manual_pages += src/bluetoothd.8 -manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.DeviceSet.5 +manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ + doc/org.bluez.DeviceSet.5 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -405,12 +407,12 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \ doc/settings-storage.txt EXTRA_DIST += doc/mgmt-api.txt \ - doc/device-api.txt \ doc/agent-api.txt doc/profile-api.txt \ doc/network-api.txt doc/health-api.txt \ doc/sap-api.txt doc/input-api.txt -EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.DeviceSet.rst +EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \ + doc/org.bluez.DeviceSet.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/device-api.txt b/doc/device-api.txt deleted file mode 100644 index e4a8d3c5af33..000000000000 --- a/doc/device-api.txt +++ /dev/null @@ -1,293 +0,0 @@ -BlueZ D-Bus Device API description -********************************** - - -Device hierarchy -================ - -Service org.bluez -Interface org.bluez.Device1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX - -Methods void Connect() - - This is a generic method to connect any profiles - the remote device supports that can be connected - to and have been flagged as auto-connectable on - our side. If only subset of profiles is already - connected it will try to connect currently disconnected - ones. - - If at least one profile was connected successfully this - method will indicate success. - - For dual-mode devices only one bearer is connected at - time, the conditions are in the following order: - - 1. Connect the disconnected bearer if already - connected. - - 2. Connect first the bonded bearer. If no - bearers are bonded or both are skip and check - latest seen bearer. - - 3. Connect last seen bearer, in case the - timestamps are the same BR/EDR takes - precedence. - - Possible errors: org.bluez.Error.NotReady - org.bluez.Error.Failed - org.bluez.Error.InProgress - org.bluez.Error.AlreadyConnected - - void Disconnect() - - This method gracefully disconnects all connected - profiles and then terminates low-level ACL connection. - - ACL connection will be terminated even if some profiles - were not disconnected properly e.g. due to misbehaving - device. - - This method can be also used to cancel a preceding - Connect call before a reply to it has been received. - - For non-trusted devices connected over LE bearer calling - this method will disable incoming connections until - Connect method is called again. - - Possible errors: org.bluez.Error.NotConnected - - void ConnectProfile(string uuid) - - This method connects a specific profile of this - device. The UUID provided is the remote service - UUID for the profile. - - Possible errors: org.bluez.Error.Failed - org.bluez.Error.InProgress - org.bluez.Error.InvalidArguments - org.bluez.Error.NotAvailable - org.bluez.Error.NotReady - - void DisconnectProfile(string uuid) - - This method disconnects a specific profile of - this device. The profile needs to be registered - client profile. - - There is no connection tracking for a profile, so - as long as the profile is registered this will always - succeed. - - Possible errors: org.bluez.Error.Failed - org.bluez.Error.InProgress - org.bluez.Error.InvalidArguments - org.bluez.Error.NotSupported - - void Pair() - - This method will connect to the remote device, - initiate pairing and then retrieve all SDP records - (or GATT primary services). - - If the application has registered its own agent, - then that specific agent will be used. Otherwise - it will use the default agent. - - Only for applications like a pairing wizard it - would make sense to have its own agent. In almost - all other cases the default agent will handle - this just fine. - - In case there is no application agent and also - no default agent present, this method will fail. - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.Failed - org.bluez.Error.AlreadyExists - org.bluez.Error.AuthenticationCanceled - org.bluez.Error.AuthenticationFailed - org.bluez.Error.AuthenticationRejected - org.bluez.Error.AuthenticationTimeout - org.bluez.Error.ConnectionAttemptFailed - - void CancelPairing() - - This method can be used to cancel a pairing - operation initiated by the Pair method. - - Possible errors: org.bluez.Error.DoesNotExist - org.bluez.Error.Failed - -Properties string Address [readonly] - - The Bluetooth device address of the remote device. - - string AddressType [readonly] - - The Bluetooth device Address Type. For dual-mode and - BR/EDR only devices this defaults to "public". Single - mode LE devices may have either value. If remote device - uses privacy than before pairing this represents address - type used for connection and Identity Address after - pairing. - - Possible values: - "public" - Public address - "random" - Random address - - string Name [readonly, optional] - - The Bluetooth remote name. This value can not be - changed. Use the Alias property instead. - - This value is only present for completeness. It is - better to always use the Alias property when - displaying the devices name. - - If the Alias property is unset, it will reflect - this value which makes it more convenient. - - string Icon [readonly, optional] - - Proposed icon name according to the freedesktop.org - icon naming specification. - - uint32 Class [readonly, optional] - - The Bluetooth class of device of the remote device. - - uint16 Appearance [readonly, optional] - - External appearance of device, as found on GAP service. - - array{string} UUIDs [readonly, optional] - - List of 128-bit UUIDs that represents the available - remote services. - - boolean Paired [readonly] - - Indicates if the remote device is paired. Paired means - the pairing process where devices exchange the - information to establish an encrypted connection has - been completed. - - boolean Bonded [readonly] - - Indicates if the remote device is bonded. Bonded means - the information exchanged on pairing process has been - stored and will be persisted. - - boolean Connected [readonly] - - Indicates if the remote device is currently connected. - A PropertiesChanged signal indicate changes to this - status. - - boolean Trusted [readwrite] - - Indicates if the remote is seen as trusted. This - setting can be changed by the application. - - boolean Blocked [readwrite] - - If set to true any incoming connections from the - device will be immediately rejected. Any device - drivers will also be removed and no new ones will - be probed as long as the device is blocked. - - boolean WakeAllowed [readwrite] - - If set to true this device will be allowed to wake the - host from system suspend. - - string Alias [readwrite] - - The name alias for the remote device. The alias can - be used to have a different friendly name for the - remote device. - - In case no alias is set, it will return the remote - device name. Setting an empty string as alias will - convert it back to the remote device name. - - When resetting the alias with an empty string, the - property will default back to the remote name. - - object Adapter [readonly] - - The object path of the adapter the device belongs to. - - boolean LegacyPairing [readonly] - - Set to true if the device only supports the pre-2.1 - pairing mechanism. This property is useful during - device discovery to anticipate whether legacy or - simple pairing will occur if pairing is initiated. - - Note that this property can exhibit false-positives - in the case of Bluetooth 2.1 (or newer) devices that - have disabled Extended Inquiry Response support. - - string Modalias [readonly, optional] - - Remote Device ID information in modalias format - used by the kernel and udev. - - int16 RSSI [readonly, optional] - - Received Signal Strength Indicator of the remote - device (inquiry or advertising). - - int16 TxPower [readonly, optional] - - Advertised transmitted power level (inquiry or - advertising). - - dict ManufacturerData [readonly, optional] - - Manufacturer specific advertisement data. Keys are - 16 bits Manufacturer ID followed by its byte array - value. - - dict ServiceData [readonly, optional] - - Service advertisement data. Keys are the UUIDs in - string format followed by its byte array value. - - bool ServicesResolved [readonly] - - Indicate whether or not service discovery has been - resolved. - - array{byte} AdvertisingFlags [readonly, experimental] - - The Advertising Data Flags of the remote device. - - dict AdvertisingData [readonly, experimental] - - The Advertising Data of the remote device. Keys are - are 8 bits AD Type followed by data as byte array. - - Note: Only types considered safe to be handled by - application are exposed. - - Possible values: - - ... - - Example: - - 0x26 0x01 0x01... - - array{object, dict} Sets [readonly, experimental] - - The object paths of the sets the device belongs to - followed by a dictionary which can contain the - following: - - byte Rank: - - Rank of the device in the Set. diff --git a/doc/org.bluez.Device.rst b/doc/org.bluez.Device.rst new file mode 100644 index 000000000000..4fdb31b0acbe --- /dev/null +++ b/doc/org.bluez.Device.rst @@ -0,0 +1,329 @@ +================ +org.bluez.Device +================ + +------------------------------------ +BlueZ D-Bus Device API documentation +------------------------------------ + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.Device1 +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Methods +------- + +void Connect() +`````````````` + + Connects all profiles the remote device supports that can be connected + to and have been flagged as auto-connectable. If only subset of profiles + is already connected it will try to connect currently disconnected ones. + + If at least one profile was connected successfully this method will + indicate success. + + For dual-mode devices only one bearer is connected at time, the + conditions are in the following order: + + 1. Connect the disconnected bearer if already connected. + + 2. Connect first the bonded bearer. If no bearers are bonded or both + are skip and check latest seen bearer. + + 3. Connect last seen bearer, in case the timestamps are the same BR/EDR + takes precedence. + + Possible errors: + + :org.bluez.Error.NotReady: + :org.bluez.Error.Failed: + :org.bluez.Error.InProgress: + :org.bluez.Error.AlreadyConnected: + +void Disconnect() +````````````````` + + Disconnects all connected profiles and then terminates low-level ACL + connection. + + ACL connection will be terminated even if some profiles were not + disconnected properly e.g. due to misbehaving device. + + This method can be also used to cancel a preceding Connect call before + a reply to it has been received. + + For non-trusted devices connected over LE bearer calling this method + will disable incoming connections until Connect method is called again. + + Possible errors: + + :org.bluez.Error.NotConnected: + +void ConnectProfile(string uuid) +```````````````````````````````` + + Connects a specific profile of this device. The UUID provided is the + remote service UUID for the profile. + + Possible errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.InProgress: + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.NotAvailable: + :org.bluez.Error.NotReady: + +void DisconnectProfile(string uuid) +``````````````````````````````````` + + Disconnects a specific profile of this device. The profile needs to be + registered client profile. + + There is no connection tracking for a profile, so as long as the + profile is registered this will always succeed. + + Possible errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.InProgress: + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.NotSupported: + +void Pair() +``````````` + + Connects to the remote device and initiate pairing procedure then + proceed with service discovery. + + If the application has registered its own agent, then that specific + agent will be used. Otherwise it will use the default agent. + + Only for applications like a pairing wizard it would make sense to have + its own agent. In almost all other cases the default agent will handle + this just fine. + + In case there is no application agent and also no default agent present, + this method will fail. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.Failed: + :org.bluez.Error.AlreadyExists: + :org.bluez.Error.AuthenticationCanceled: + :org.bluez.Error.AuthenticationFailed: + :org.bluez.Error.AuthenticationRejected: + :org.bluez.Error.AuthenticationTimeout: + :org.bluez.Error.ConnectionAttemptFailed: + +void CancelPairing() +```````````````````` + + Cancels a pairing operation initiated by the **Pair** method. + + Possible errors: + + :org.bluez.Error.DoesNotExist: + :org.bluez.Error.Failed: + +Properties +---------- + +string Address [readonly] +````````````````````````` + + The Bluetooth device address of the remote device. + +string AddressType [readonly] +````````````````````````````` + + The Bluetooth device Address Type. For dual-mode and BR/EDR only devices + this defaults to "public". Single mode LE devices may have either value. + If remote device uses privacy than before pairing this represents + address type used for connection and Identity Address after pairing. + + Possible values: + + :"public": + + Public address + + :"random": + + Random address + +string Name [readonly, optional] +```````````````````````````````` + + The Bluetooth remote name. + + This value is only present for completeness. It is better to always use + the **Alias** property when displaying the devices name. + + If the **Alias** property is unset, it will reflect this value which + makes it more convenient. + +string Icon [readonly, optional] +```````````````````````````````` + + Proposed icon name according to the freedesktop.org icon naming + specification. + +uint32 Class [readonly, optional] +````````````````````````````````` + + The Bluetooth class of device of the remote device. + +uint16 Appearance [readonly, optional] +`````````````````````````````````````` + + External appearance of device, as found on GAP service. + +array{string} UUIDs [readonly, optional] +```````````````````````````````````````` + + List of 128-bit UUIDs that represents the available remote services. + +boolean Paired [readonly] +````````````````````````` + + Indicates if the remote device is paired. Paired means the pairing + process where devices exchange the information to establish an + encrypted connection has been completed. + +boolean Bonded [readonly] +````````````````````````` + + Indicates if the remote device is bonded. Bonded means the information + exchanged on pairing process has been stored and will be persisted. + +boolean Connected [readonly] +```````````````````````````` + + Indicates if the remote device is currently connected. + A PropertiesChanged signal indicate changes to this status. + +boolean Trusted [readwrite] +``````````````````````````` + + Indicates if the remote is seen as trusted. This setting can be changed + by the application. + +boolean Blocked [readwrite] +``````````````````````````` + + If set to true any incoming connections from the device will be + immediately rejected. Any device drivers will also be removed and + no new ones will be probed as long as the device is blocked. + +boolean WakeAllowed [readwrite] +``````````````````````````````` + + If set to true this device will be allowed to wake the host from + system suspend. + +string Alias [readwrite] +```````````````````````` + + The name alias for the remote device. The alias can be used to have a + different friendly name for the remote device. + + In case no alias is set, it will return the remote device name. Setting + an empty string as alias will convert it back to the remote device name. + + When resetting the alias with an empty string, the property will default + back to the remote name. + +object Adapter [readonly] +````````````````````````` + + The object path of the adapter the device belongs to. + +boolean LegacyPairing [readonly] +```````````````````````````````` + + Set to true if the device only supports the pre-2.1 pairing mechanism. + This property is useful during device discovery to anticipate whether + legacy or simple pairing will occur if pairing is initiated. + + Note that this property can exhibit false-positives in the case of + Bluetooth 2.1 (or newer) devices that have disabled Extended Inquiry + Response support. + +string Modalias [readonly, optional] +```````````````````````````````````` + + Remote Device ID information in modalias format used by the kernel and + udev. + +int16 RSSI [readonly, optional] +``````````````````````````````` + + Received Signal Strength Indicator of the remote device (inquiry or + advertising). + +int16 TxPower [readonly, optional] +`````````````````````````````````` + + Advertised transmitted power level (inquiry or advertising). + +dict ManufacturerData [readonly, optional] +`````````````````````````````````````````` + + Manufacturer specific advertisement data. Keys are 16 bits Manufacturer + ID followed by its byte array value. + +dict ServiceData [readonly, optional] +````````````````````````````````````` + + Service advertisement data. Keys are the UUIDs in string format followed + by its byte array value. + +bool ServicesResolved [readonly] +```````````````````````````````` + + Indicate whether or not service discovery has been resolved. + +array{byte} AdvertisingFlags [readonly, experimental] +````````````````````````````````````````````````````` + + The Advertising Data Flags of the remote device. + +dict AdvertisingData [readonly, experimental] +````````````````````````````````````````````` + + The Advertising Data of the remote device. Keys are 1 byte AD Type + followed by data as byte array. + + Note: Only types considered safe to be handled by application are + exposed. + + Possible values: + + :: + + + + Example: + + + 0x26 0x01 0x01... + +array{object, dict} Sets [readonly, experimental] +````````````````````````````````````````````````` + + The object paths of the sets the device belongs to followed by a + dictionary which can contain the following: + + :byte Rank: + + Rank of the device in the Set. From patchwork Sat Oct 7 01:01:45 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 731115 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id CE8FEE9413F for ; Sat, 7 Oct 2023 01:02:02 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234004AbjJGBCC (ORCPT ); Fri, 6 Oct 2023 21:02:02 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58946 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234000AbjJGBB7 (ORCPT ); Fri, 6 Oct 2023 21:01:59 -0400 Received: from mail-oo1-xc2f.google.com (mail-oo1-xc2f.google.com [IPv6:2607:f8b0:4864:20::c2f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 15172D8 for ; Fri, 6 Oct 2023 18:01:57 -0700 (PDT) Received: by mail-oo1-xc2f.google.com with SMTP id 006d021491bc7-57b5f0d658dso1520702eaf.0 for ; Fri, 06 Oct 2023 18:01:57 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696640516; x=1697245316; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=TkfOqC4rFp3I8rUQYFc12cHuq4/iMM2zLlkaD94aPZU=; b=KHr+Ajsb6Rlgf5Ts6+6WbjzqHE3X9kXBdJemepocqs+63FR+vN8xApcnsIcY3xy4ru 1v89BsyBdPKbFwLTqBD9hyXKNsopZX77xOOe1XMWNJBTYPugBbpMcjD11RE5MJuVEzro V0wzmNOTL/bsYwKNjMH734l/HTeBnNiblkrwqwZ9e0aPAH7d4f/q8s9qabOpHHEV2sfI aHn0tKf4sCFn2BVhBzAKgZI557UU31I2jbNga1jBzvzgRsLfqg4lWnx7f4EEg8MuzCaG oTXUKFOg6waSWVDoQtqdmjM882A5VJh13NqPUWFfKS2AjLwXEQHGM0gCODr/3Cq7Az74 15ow== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696640516; x=1697245316; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=TkfOqC4rFp3I8rUQYFc12cHuq4/iMM2zLlkaD94aPZU=; b=efLQtaF4dZ+vQlEnjmV8+LFSXG/jMzQGWjCvt35mE5UdNSbXblgNlbiZOVdEoJPzss bEv8OQudXEZOzVerMgqX72XPg6NtllEFaURAPWOqmpoGh4MwsH2VlQOkr451Y9b2h6dK P9QFeNF6Uf0cSFYwwWei8sO3cLy9wO1D+6WHnSOBOwIvPqG/QN8WPayBGKQUkVKjohxx 6KbvrBJ/kQl0kKIhix5xBNt2Kt3+ejMkB9zXD1B/ab6L0u1hGf/m90L/peyBHpyjQY0F 8tktxZ7vS/Kg6/Rkb7Sy7EoOeRbnPZ99+4pKFl6V9HBG/gAG4XymlKJl4aAjd2lTz0Jm qG2A== X-Gm-Message-State: AOJu0YxoXsrFVc6MUjNKrp8ZerPaKL8+a3Iy4yA0HTgmuhEJbdSnXah8 fYZ6oQYmtL1KbYqgblUaPSHyn4vdXv+GxA3J X-Google-Smtp-Source: AGHT+IHS6A1ZBTRvb8elYmVjmi0vA94HgLQPt48NCFf3rjg4zx+eyC1ZZT4ZlduHVEEcJKGE+FQjHw== X-Received: by 2002:a05:6358:9485:b0:135:46d9:12f7 with SMTP id i5-20020a056358948500b0013546d912f7mr8606186rwb.26.1696640515223; Fri, 06 Oct 2023 18:01:55 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id co11-20020a17090afe8b00b00279060a0fccsm4098360pjb.9.2023.10.06.18.01.54 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 06 Oct 2023 18:01:54 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH BlueZ 3/8] doc/agent-api: Rename to org.bluez.Agent{Manager}.rst Date: Fri, 6 Oct 2023 18:01:45 -0700 Message-ID: <20231007010150.4103452-3-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231007010150.4103452-1-luiz.dentz@gmail.com> References: <20231007010150.4103452-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames agent-api.txt to org.bluez.Agent{Manager}.rst and generate manpages org.bluez.Agent{Manager}.5. --- Makefile.am | 11 +- doc/agent-api.txt | 185 --------------------------------- doc/org.bluez.Agent.rst | 149 ++++++++++++++++++++++++++ doc/org.bluez.AgentManager.rst | 83 +++++++++++++++ 4 files changed, 239 insertions(+), 189 deletions(-) delete mode 100644 doc/agent-api.txt create mode 100644 doc/org.bluez.Agent.rst create mode 100644 doc/org.bluez.AgentManager.rst diff --git a/Makefile.am b/Makefile.am index 9e74f4f0fc76..f355ac0c379c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -358,7 +358,8 @@ CLEANFILES += $(builtin_files) src/bluetooth.service if MANPAGES man_MANS += src/bluetoothd.8 man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ - doc/org.bluez.DeviceSet.5 + doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ + doc/org.bluez.Agent.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -366,7 +367,8 @@ man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ endif manual_pages += src/bluetoothd.8 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ - doc/org.bluez.DeviceSet.5 + doc/org.bluez.DeviceSet.5 doc/org.bluez.AagentManager.5 \ + doc/org.bluez.Agent.5 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -407,12 +409,13 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \ doc/settings-storage.txt EXTRA_DIST += doc/mgmt-api.txt \ - doc/agent-api.txt doc/profile-api.txt \ + doc/profile-api.txt \ doc/network-api.txt doc/health-api.txt \ doc/sap-api.txt doc/input-api.txt EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \ - doc/org.bluez.DeviceSet.rst + doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \ + doc/org.bluez.Agent.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/agent-api.txt b/doc/agent-api.txt deleted file mode 100644 index 0d9347cab390..000000000000 --- a/doc/agent-api.txt +++ /dev/null @@ -1,185 +0,0 @@ -BlueZ D-Bus Agent API description -********************************** - - -Agent Manager hierarchy -======================= - -Service org.bluez -Interface org.bluez.AgentManager1 -Object path /org/bluez - - void RegisterAgent(object agent, string capability) - - This registers an agent handler. - - The object path defines the path of the agent - that will be called when user input is needed. - - Every application can register its own agent and - for all actions triggered by that application its - agent is used. - - It is not required by an application to register - an agent. If an application does chooses to not - register an agent, the default agent is used. This - is on most cases a good idea. Only application - like a pairing wizard should register their own - agent. - - An application can only register one agent. Multiple - agents per application is not supported. - - The capability parameter can have the values - "DisplayOnly", "DisplayYesNo", "KeyboardOnly", - "NoInputNoOutput" and "KeyboardDisplay" which - reflects the input and output capabilities of the - agent. - - If an empty string is used it will fallback to - "KeyboardDisplay". - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.AlreadyExists - - void UnregisterAgent(object agent) - - This unregisters the agent that has been previously - registered. The object path parameter must match the - same value that has been used on registration. - - Possible errors: org.bluez.Error.DoesNotExist - - void RequestDefaultAgent(object agent) - - This requests is to make the application agent - the default agent. The application is required - to register an agent. - - Special permission might be required to become - the default agent. - - Possible errors: org.bluez.Error.DoesNotExist - - -Agent hierarchy -=============== - -Service unique name -Interface org.bluez.Agent1 -Object path freely definable - -Methods void Release() - - This method gets called when the service daemon - unregisters the agent. An agent can use it to do - cleanup tasks. There is no need to unregister the - agent, because when this method gets called it has - already been unregistered. - - string RequestPinCode(object device) - - This method gets called when the service daemon - needs to get the passkey for an authentication. - - The return value should be a string of 1-16 characters - length. The string can be alphanumeric. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - void DisplayPinCode(object device, string pincode) - - This method gets called when the service daemon - needs to display a pincode for an authentication. - - An empty reply should be returned. When the pincode - needs no longer to be displayed, the Cancel method - of the agent will be called. - - This is used during the pairing process of keyboards - that don't support Bluetooth 2.1 Secure Simple Pairing, - in contrast to DisplayPasskey which is used for those - that do. - - This method will only ever be called once since - older keyboards do not support typing notification. - - Note that the PIN will always be a 6-digit number, - zero-padded to 6 digits. This is for harmony with - the later specification. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - uint32 RequestPasskey(object device) - - This method gets called when the service daemon - needs to get the passkey for an authentication. - - The return value should be a numeric value - between 0-999999. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - void DisplayPasskey(object device, uint32 passkey, - uint16 entered) - - This method gets called when the service daemon - needs to display a passkey for an authentication. - - The entered parameter indicates the number of already - typed keys on the remote side. - - An empty reply should be returned. When the passkey - needs no longer to be displayed, the Cancel method - of the agent will be called. - - During the pairing process this method might be - called multiple times to update the entered value. - - Note that the passkey will always be a 6-digit number, - so the display should be zero-padded at the start if - the value contains less than 6 digits. - - void RequestConfirmation(object device, uint32 passkey) - - This method gets called when the service daemon - needs to confirm a passkey for an authentication. - - To confirm the value it should return an empty reply - or an error in case the passkey is invalid. - - Note that the passkey will always be a 6-digit number, - so the display should be zero-padded at the start if - the value contains less than 6 digits. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - void RequestAuthorization(object device) - - This method gets called to request the user to - authorize an incoming pairing attempt which - would in other circumstances trigger the just-works - model, or when the user plugged in a device that - implements cable pairing. In the latter case, the - device would not be connected to the adapter via - Bluetooth yet. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - void AuthorizeService(object device, string uuid) - - This method gets called when the service daemon - needs to authorize a connection/service request. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - void Cancel() - - This method gets called to indicate that the agent - request failed before a reply was returned. diff --git a/doc/org.bluez.Agent.rst b/doc/org.bluez.Agent.rst new file mode 100644 index 000000000000..11d09b94d228 --- /dev/null +++ b/doc/org.bluez.Agent.rst @@ -0,0 +1,149 @@ +=============== +org.bluez.Agent +=============== + +----------------------------------- +BlueZ D-Bus Agent API documentation +----------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: unique name +:Interface: org.bluez.Agent1 +:Object path: freely definable + +Methods +------- + +void Release() +`````````````` + + This method gets called when the service daemon unregisters the agent. + An agent can use it to do cleanup tasks. There is no need to unregister + the agent, because when this method gets called it has already been + unregistered. + +string RequestPinCode(object device) +```````````````````````````````````` + + This method gets called when the service daemon needs to get the passkey + for an authentication. + + The return value should be a string of 1-16 characters length. The + string can be alphanumeric. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: + +void DisplayPinCode(object device, string pincode) +`````````````````````````````````````````````````` + + This method gets called when the service daemon needs to display a + pincode for an authentication. + + An empty reply should be returned. When the pincode needs no longer to + be displayed, the Cancel method of the agent will be called. + + This is used during the pairing process of keyboards that don't support + Bluetooth 2.1 Secure Simple Pairing, in contrast to DisplayPasskey which + is used for those that do. + + This method will only ever be called once since older keyboards do not + support typing notification. + + Note that the PIN will always be a 6-digit number, zero-padded to 6 + digits. This is for harmony with the later specification. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: + +uint32 RequestPasskey(object device) +```````````````````````````````````` + + This method gets called when the service daemon needs to get the passkey + for an authentication. + + The return value should be a numeric value between 0-999999. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: + +void DisplayPasskey(object device, uint32 passkey, uint16 entered) +`````````````````````````````````````````````````````````````````` + + This method gets called when the service daemon needs to display a + passkey for an authentication. + + The entered parameter indicates the number of already typed keys on the + remote side. + + An empty reply should be returned. When the passkey needs no longer to + be displayed, the Cancel method of the agent will be called. + + During the pairing process this method might be called multiple times to + update the entered value. + + Note that the passkey will always be a 6-digit number, so the display + should be zero-padded at the start if the value contains less than 6 + digits. + +void RequestConfirmation(object device, uint32 passkey) +``````````````````````````````````````````````````````` + + This method gets called when the service daemon needs to confirm a + passkey for an authentication. + + To confirm the value it should return an empty reply or an error in case + the passkey is invalid. + + Note that the passkey will always be a 6-digit number, so the display + should be zero-padded at the start if the value contains less than 6 + digits. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: + +void RequestAuthorization(object device) +```````````````````````````````````````` + + This method gets called to request the user to authorize an incoming + pairing attempt which would in other circumstances trigger the + just-works model, or when the user plugged in a device that implements + cable pairing. In the latter case, the device would not be connected to + the adapter via Bluetooth yet. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: + +void AuthorizeService(object device, string uuid) +````````````````````````````````````````````````` + + This method gets called when the service daemon needs to authorize a + connection/service request. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: + +void Cancel() +````````````` + + This method gets called to indicate that the agent request failed before + a reply was returned. diff --git a/doc/org.bluez.AgentManager.rst b/doc/org.bluez.AgentManager.rst new file mode 100644 index 000000000000..dfc0297da8d2 --- /dev/null +++ b/doc/org.bluez.AgentManager.rst @@ -0,0 +1,83 @@ +====================== +org.bluez.AgentManager +====================== + +------------------------------------------ +BlueZ D-Bus AgentManager API documentation +------------------------------------------ + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.AgentManager1 +:Object path: /org/bluez + +Methods +------- + +void RegisterAgent(object agent, string capability) +``````````````````````````````````````````````````` + + Registers pairing agent. + + The object path defines the path of the agent that will be called when + user input is needed and must implement **org.bluez.Agent(5)** + interface. + + Every application can register its own agent and for all actions + triggered by that application its agent is used. + + It is not required by an application to register an agent. If an + application does chooses to not register an agent, the default agent is + used. This is on most cases a good idea. Only application like a pairing + wizard should register their own agent. + + An application can only register one agent. Multiple agents per + application is not supported. + + Possible capability values: + + :"": + + Fallback to "KeyboardDisplay". + + :"DisplayOnly": + :"DisplayYesNo": + :"KeyboardOnly": + :"NoInputNoOutput": + :"KeyboardDisplay": + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.AlreadyExists: + +void UnregisterAgent(object agent) +`````````````````````````````````` + + Unregisters an agent that has been previously registered using + **RegisterAgent**. The object path parameter must match the same value + that has been used on registration. + + Possible errors: + + :org.bluez.Error.DoesNotExist: + +void RequestDefaultAgent(object agent) +`````````````````````````````````````` + + Requests to make the application agent the default agent. The + application is required to register an agent. + + Special permission might be required to become the default agent. + + Possible errors: + + :org.bluez.Error.DoesNotExist: + From patchwork Sat Oct 7 01:01:46 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 730525 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id D1180E9413E for ; Sat, 7 Oct 2023 01:02:03 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234008AbjJGBCC (ORCPT ); Fri, 6 Oct 2023 21:02:02 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58980 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234003AbjJGBCB (ORCPT ); Fri, 6 Oct 2023 21:02:01 -0400 Received: from mail-oi1-x22c.google.com (mail-oi1-x22c.google.com [IPv6:2607:f8b0:4864:20::22c]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 240BDC5 for ; Fri, 6 Oct 2023 18:01:59 -0700 (PDT) Received: by mail-oi1-x22c.google.com with SMTP id 5614622812f47-3ae2896974bso1734737b6e.0 for ; Fri, 06 Oct 2023 18:01:59 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696640517; x=1697245317; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=Ud1q4yYXQKZT9lTKirqbZx/9B+bk1hmJri15/L6UuQ0=; b=Zp3nUx6n/8q3QytnPEDcF/wPMtVFA1r35Rn6xDyKbFA2L8lnqLMSI5vvlpfyc/3+Pc XXwLQ6A9+oYA39wuPPDi4NGbki50vlUM7oVIKZR/mi8O/xaCFlRnzcNTn6Uku1B04mbx zjbVTpJ5SBCsepVw0jhb65txz9WAeGiBpr73QYkhnTQll+Fe9dq+9r1IOUn5tGaOQXTE wH5frvd+LNpw4ov2Tv1md7kWJw623iRHD41V8inKzNvywnUcLeEFTI/jkFLAiJdybp9g eSTonFUHzNISDREMnQnRzuY2YNxEyevAYWOWHfPVRINeMoH0N1tRmiCz6pUbIDIcvVRf PiAA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696640517; x=1697245317; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=Ud1q4yYXQKZT9lTKirqbZx/9B+bk1hmJri15/L6UuQ0=; b=v4Rlmf642NAgsfZlbLdrczM5e6RR3h11fRQxfaQeFOH4YvLhQvF0r3c4D30u5DNXPE HmlUHNTUDI/AK0l60JqVkGf9/Bych+R/jwVMt3CU8NI4yC7ZgxcbtonbBg7euZ24x9DN z8a0G/rRrQIy+IS9gFG6ev3RuMS1vi51zeJHZ5k8hHolxV05Sv08HpD24uF6HoZ/Fp9k K0T/hxdU/BIQmNWynS+AF7nL/83v6xP2if9enINxhQ3nlrqyBGxqWkaH6FB8WI6nqriA iUMbtaF+gWVXF2zzZD3Nm6nXY9tABiK9oxg5DXgkxgpRsRB55KTYTp0v9r56CiaR0oga U+qQ== X-Gm-Message-State: AOJu0YzK3swZh4cLhGjXSeV/ljtNHnG2UfJIUOADcvTrVzBRUL6GDciy E2q6FGHpGDceWAGH91IyuriaUFK1V0n7mkm2 X-Google-Smtp-Source: AGHT+IFpraprSpxJbLTcmWsVmeMwRmtJjTvryrTf8S+7s+TphHY1CbRkpW8jMUDUZO61i9W5GK4bjw== X-Received: by 2002:a05:6358:7250:b0:134:d282:92e9 with SMTP id i16-20020a056358725000b00134d28292e9mr10712013rwa.29.1696640517390; Fri, 06 Oct 2023 18:01:57 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id co11-20020a17090afe8b00b00279060a0fccsm4098360pjb.9.2023.10.06.18.01.55 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 06 Oct 2023 18:01:55 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH BlueZ 4/8] doc/profile-api: Rename to org.bluez.Profile{Manager}.rst Date: Fri, 6 Oct 2023 18:01:46 -0700 Message-ID: <20231007010150.4103452-4-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231007010150.4103452-1-luiz.dentz@gmail.com> References: <20231007010150.4103452-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames profile-api.txt to org.bluez.Profile{Manager}.rst and generate manpages org.bluez.Profile{Manager}.5. --- Makefile.am | 10 +- doc/org.bluez.Profile.rst | 51 ++++++++++ doc/org.bluez.ProfileManager.rst | 141 +++++++++++++++++++++++++ doc/profile-api.txt | 170 ------------------------------- 4 files changed, 198 insertions(+), 174 deletions(-) create mode 100644 doc/org.bluez.Profile.rst create mode 100644 doc/org.bluez.ProfileManager.rst delete mode 100644 doc/profile-api.txt diff --git a/Makefile.am b/Makefile.am index f355ac0c379c..ab723a59f1ac 100644 --- a/Makefile.am +++ b/Makefile.am @@ -359,7 +359,8 @@ if MANPAGES man_MANS += src/bluetoothd.8 man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ - doc/org.bluez.Agent.5 + doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \ + doc/org.bluez.Profile.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -368,7 +369,8 @@ endif manual_pages += src/bluetoothd.8 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.DeviceSet.5 doc/org.bluez.AagentManager.5 \ - doc/org.bluez.Agent.5 + doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \ + doc/org.bluez.Profile.5 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -409,13 +411,13 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \ doc/settings-storage.txt EXTRA_DIST += doc/mgmt-api.txt \ - doc/profile-api.txt \ doc/network-api.txt doc/health-api.txt \ doc/sap-api.txt doc/input-api.txt EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \ doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \ - doc/org.bluez.Agent.rst + doc/org.bluez.Agent.rst doc/org.bluez.ProfileManager.rst \ + doc/org.bluez.Profile.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/org.bluez.Profile.rst b/doc/org.bluez.Profile.rst new file mode 100644 index 000000000000..d8ae669c7323 --- /dev/null +++ b/doc/org.bluez.Profile.rst @@ -0,0 +1,51 @@ +================= +org.bluez.Profile +================= + +------------------------------------- +BlueZ D-Bus Profile API documentation +------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: unique name +:Interface: org.bluez.Profile1 +:Object path: freely definable + +Methods +------- + +void Release() [noreply] +```````````````````````` + + This method gets called when the service daemon unregisters the profile. + A profile can use it to do cleanup tasks. There is no need to unregister + the profile, because when this method gets called it has already been + unregistered. + +void NewConnection(object device, fd, dict fd_properties) +````````````````````````````````````````````````````````` + + This method gets called when a new service level connection has been + made and authorized. + + Possible fd_properties values: + + :uint16 Version [optional]: + + Profile version. + + :uint16 Features [optional]: + + Profile features. + + Possible errors: + + :org.bluez.Error.Rejected: + :org.bluez.Error.Canceled: diff --git a/doc/org.bluez.ProfileManager.rst b/doc/org.bluez.ProfileManager.rst new file mode 100644 index 000000000000..ccd7a2673d77 --- /dev/null +++ b/doc/org.bluez.ProfileManager.rst @@ -0,0 +1,141 @@ +======================== +org.bluez.ProfileManager +======================== + +-------------------------------------------- +BlueZ D-Bus ProfileManager API documentation +-------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.ProfileManager1 +:Object path: /org/bluez + +Methods +------- + +void RegisterProfile(object profile, string uuid, dict options) +``````````````````````````````````````````````````````````````` + + Registers profile agent. + + The object path defines the path of the profile that will be called + when there is a connection and must implement **org.bluez.Profile(5)** + interface. + + If an application disconnects from the bus all its registered profiles + will be removed. + + Possible uuid values: + + :"0000111f-0000-1000-8000-00805f9b34fb": + + HFP AG, default profile Version is 1.7, profile Features is + 0b001001 and RFCOMM channel is 13. Authentication is required. + + :"0000111e-0000-1000-8000-00805f9b34fb": + + HFP HS, default profile Version is 1.7, profile Features is + 0b000000 and RFCOMM channel is 7. Authentication is required. + + :"00001112-0000-1000-8000-00805f9b34fb": + + HSP AG, default profile Version is 1.2, RFCOMM channel is 12 and + Authentication is required. Does not support any Features, + option is ignored. + + :"00001108-0000-1000-8000-00805f9b34fb": + + HSP HS, default profile Version is 1.2, profile Features is 0b0 + and RFCOMM channel is 6. Authentication is required. + Features is one bit value, specify capability of Remote Audio + Volume Control (by default turned off). + + :"": + + Vendor defined UUID, no defaults, must set options. + + Possible options values: + + :string Name: + + Human readable name for the profile + + :string Service: + + The primary service class UUID (if different from the actual + profile UUID). + + :string Role: + + For asymmetric profiles that do not have UUIDs available to + uniquely identify each side this parameter allows specifying the + precise local role. + + Possible values: + + :"client": + :"server": + + :uint16 Channel: + + RFCOMM channel number that is used for client and server UUIDs. + + If applicable it will be used in the SDP record as well. + + :uint16 PSM: + + PSM number that is used for client and server UUIDs. + + If applicable it will be used in the SDP record as well. + + :boolean RequireAuthentication: + + Pairing is required before connections will be established. + No devices will be connected if not paired. + + :boolean RequireAuthorization: + + Request authorization before any connection will be established. + + :boolean AutoConnect: + + In case of a client UUID this will force connection of the + RFCOMM or L2CAP channels when a remote device is connected. + + :string ServiceRecord: + + Provide a manual SDP record. + + :uint16 Version: + + Profile version (for SDP record) + + :uint16 Features: + + Profile features (for SDP record) + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.AlreadyExists: + +void UnregisterProfile(object profile) +`````````````````````````````````````` + + Unregisters profile object that has been previously registered using + **RegisterProfile**. + + The object path parameter must match the same value that has been used + on registration. + + Possible errors: + + :org.bluez.Error.DoesNotExist: diff --git a/doc/profile-api.txt b/doc/profile-api.txt deleted file mode 100644 index 183c6c11a7ba..000000000000 --- a/doc/profile-api.txt +++ /dev/null @@ -1,170 +0,0 @@ -BlueZ D-Bus Profile API description -*********************************** - - -Profile Manager hierarchy -========================= - -Service org.bluez -Interface org.bluez.ProfileManager1 -Object path /org/bluez - - void RegisterProfile(object profile, string uuid, dict options) - - This registers a profile implementation. - - If an application disconnects from the bus all - its registered profiles will be removed. - - Some predefined services: - - HFP AG UUID: 0000111f-0000-1000-8000-00805f9b34fb - - Default profile Version is 1.7, profile Features - is 0b001001 and RFCOMM channel is 13. - Authentication is required. - - HFP HS UUID: 0000111e-0000-1000-8000-00805f9b34fb - - Default profile Version is 1.7, profile Features - is 0b000000 and RFCOMM channel is 7. - Authentication is required. - - HSP AG UUID: 00001112-0000-1000-8000-00805f9b34fb - - Default profile Version is 1.2, RFCOMM channel - is 12 and Authentication is required. Does not - support any Features, option is ignored. - - HSP HS UUID: 00001108-0000-1000-8000-00805f9b34fb - - Default profile Version is 1.2, profile Features - is 0b0 and RFCOMM channel is 6. Authentication - is required. Features is one bit value, specify - capability of Remote Audio Volume Control - (by default turned off). - - Available options: - - string Name - - Human readable name for the profile - - string Service - - The primary service class UUID - (if different from the actual - profile UUID) - - string Role - - For asymmetric profiles that do not - have UUIDs available to uniquely - identify each side this - parameter allows specifying the - precise local role. - - Possible values: "client", "server" - - uint16 Channel - - RFCOMM channel number that is used - for client and server UUIDs. - - If applicable it will be used in the - SDP record as well. - - uint16 PSM - - PSM number that is used for client - and server UUIDs. - - If applicable it will be used in the - SDP record as well. - - boolean RequireAuthentication - - Pairing is required before connections - will be established. No devices will - be connected if not paired. - - boolean RequireAuthorization - - Request authorization before any - connection will be established. - - boolean AutoConnect - - In case of a client UUID this will - force connection of the RFCOMM or - L2CAP channels when a remote device - is connected. - - string ServiceRecord - - Provide a manual SDP record. - - uint16 Version - - Profile version (for SDP record) - - uint16 Features - - Profile features (for SDP record) - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.AlreadyExists - - void UnregisterProfile(object profile) - - This unregisters the profile that has been previously - registered. The object path parameter must match the - same value that has been used on registration. - - Possible errors: org.bluez.Error.DoesNotExist - - -Profile hierarchy -================= - -Service unique name -Interface org.bluez.Profile1 -Object path freely definable - -Methods void Release() [noreply] - - This method gets called when the service daemon - unregisters the profile. A profile can use it to do - cleanup tasks. There is no need to unregister the - profile, because when this method gets called it has - already been unregistered. - - void NewConnection(object device, fd, dict fd_properties) - - This method gets called when a new service level - connection has been made and authorized. - - Common fd_properties: - - uint16 Version Profile version (optional) - uint16 Features Profile features (optional) - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled - - void RequestDisconnection(object device) - - This method gets called when a profile gets - disconnected. - - The file descriptor is no longer owned by the service - daemon and the profile implementation needs to take - care of cleaning up all connections. - - If multiple file descriptors are indicated via - NewConnection, it is expected that all of them - are disconnected before returning from this - method call. - - Possible errors: org.bluez.Error.Rejected - org.bluez.Error.Canceled From patchwork Sat Oct 7 01:01:47 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 731116 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 720D0E784AF for ; Sat, 7 Oct 2023 01:02:04 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233999AbjJGBCE (ORCPT ); Fri, 6 Oct 2023 21:02:04 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59030 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234006AbjJGBCC (ORCPT ); Fri, 6 Oct 2023 21:02:02 -0400 Received: from mail-pj1-x102d.google.com (mail-pj1-x102d.google.com [IPv6:2607:f8b0:4864:20::102d]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id BA643D8 for ; Fri, 6 Oct 2023 18:02:00 -0700 (PDT) Received: by mail-pj1-x102d.google.com with SMTP id 98e67ed59e1d1-27734d76e1bso2014878a91.2 for ; Fri, 06 Oct 2023 18:02:00 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696640519; x=1697245319; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=kDgX8yDsywNAW28NWgcAVa6rB+XdkOH4ZNhvrScoT/Y=; b=Sa19HqzujWVdIYLTIDCIYvzN5kD0xcT8K/dX/hygW9QlhYMTUZMM7jHb1B/pp+YQUH U/hRUZmtunuurQySoUwjKHTOVGuddAzM3LCmRL8loc9VNakImDXBtM11VfpRTm+rMwcq Qj0qHKb+EV0URmTUizOENC7YYn4TKD1Z8jXxJQnGiipTip5SKDbbv16rEXBwKxH9Hf4B rCiUyFpp1ZnOfQ9VFlW8Q/k6Kc9ca7Ro7IiFHB6sth7DmehAMvPTKSjZw9VSGn13sHsL cA3T8JdAmKAhgAa9nWBSFXfORELaszUpcZ7L0r0+ZfnlQIiB6i07VM/rJAxc8eqYs/uw 7pEQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696640519; x=1697245319; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=kDgX8yDsywNAW28NWgcAVa6rB+XdkOH4ZNhvrScoT/Y=; b=KSo2k9ydLkw6fVJV2/5Tt0jShRKxfuQRTGyg2xYJ/3bMAjoY/RUSLuFlvfy2MoPqWU c8oOaX8qvPLDDL1nKH706qSzHD7wEZJ25LRSoyWjLawBk93Y3yXgpylAvntu+SJNd/MA 2xaw05ffWAaKabDSBBg/xbLokdq6Cg9HNvjxQtjEtsYa5l5qc/e9uVeFqm2Sx9BsekCz UjBG/obKY+DxoF+XWOMgI1W2cdJzJJfd0Fss+NGEfvW0sfc9plj+291JMAl531Fpa8q9 mxFt9ujtojgV6nlK06CuPYr3zvEJhQKSPlc3RxrNa/FSJtQjfVA7LnQT73c+WqawrG0K 5GCw== X-Gm-Message-State: AOJu0Ywwk5r9JcfIQSNMC2J63sEBx0hXMVfNyq/z32X4x79d/PU8amU0 HtozfYKclGmWHTWszeedeu4S+shXEMS2M2v6 X-Google-Smtp-Source: AGHT+IF5c/K5ZhVi8+TCivZ0jHwso/uO5w3mN7Ffjfce9DQgZ/t3pdzVomAK+rNTFd5yNLvmVTGpFA== X-Received: by 2002:a17:90a:ab87:b0:27b:258f:2843 with SMTP id n7-20020a17090aab8700b0027b258f2843mr5308131pjq.7.1696640519204; Fri, 06 Oct 2023 18:01:59 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id co11-20020a17090afe8b00b00279060a0fccsm4098360pjb.9.2023.10.06.18.01.57 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 06 Oct 2023 18:01:58 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH BlueZ 5/8] doc/network-api: Rename to org.bluez.Network{Server}.rst Date: Fri, 6 Oct 2023 18:01:47 -0700 Message-ID: <20231007010150.4103452-5-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231007010150.4103452-1-luiz.dentz@gmail.com> References: <20231007010150.4103452-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames network-api.txt to org.bluez.Network{Server}.rst and generate manpages org.bluez.Network{Server}.5. --- Makefile.am | 11 +++-- doc/network-api.txt | 76 ------------------------------ doc/org.bluez.Network.rst | 83 +++++++++++++++++++++++++++++++++ doc/org.bluez.NetworkServer.rst | 68 +++++++++++++++++++++++++++ 4 files changed, 158 insertions(+), 80 deletions(-) delete mode 100644 doc/network-api.txt create mode 100644 doc/org.bluez.Network.rst create mode 100644 doc/org.bluez.NetworkServer.rst diff --git a/Makefile.am b/Makefile.am index ab723a59f1ac..4507b72bbae7 100644 --- a/Makefile.am +++ b/Makefile.am @@ -360,7 +360,8 @@ man_MANS += src/bluetoothd.8 man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \ - doc/org.bluez.Profile.5 + doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \ + doc/org.bluez.Network.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -370,7 +371,8 @@ manual_pages += src/bluetoothd.8 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.DeviceSet.5 doc/org.bluez.AagentManager.5 \ doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \ - doc/org.bluez.Profile.5 + doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \ + doc/org.bluez.Network.5 manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -411,13 +413,14 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \ doc/settings-storage.txt EXTRA_DIST += doc/mgmt-api.txt \ - doc/network-api.txt doc/health-api.txt \ + doc/health-api.txt \ doc/sap-api.txt doc/input-api.txt EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \ doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \ doc/org.bluez.Agent.rst doc/org.bluez.ProfileManager.rst \ - doc/org.bluez.Profile.rst + doc/org.bluez.Profile.rst doc/org.bluez.NetworkServer.rst \ + doc/org.bluez.Network.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/network-api.txt b/doc/network-api.txt deleted file mode 100644 index 109da28bf10d..000000000000 --- a/doc/network-api.txt +++ /dev/null @@ -1,76 +0,0 @@ -BlueZ D-Bus Network API description -*********************************** - - -Network hierarchy -================= - -Service org.bluez -Interface org.bluez.Network1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX - -Methods string Connect(string uuid) - - Connect to the network device and return the network - interface name. Examples of the interface name are - bnep0, bnep1 etc. - - uuid can be either one of "gn", "panu" or "nap" (case - insensitive) or a traditional string representation of - UUID or a hexadecimal number. - - The connection will be closed and network device - released either upon calling Disconnect() or when - the client disappears from the message bus. - - Possible errors: org.bluez.Error.AlreadyConnected - org.bluez.Error.ConnectionAttemptFailed - - void Disconnect() - - Disconnect from the network device. - - To abort a connection attempt in case of errors or - timeouts in the client it is fine to call this method. - - Possible errors: org.bluez.Error.Failed - -Properties boolean Connected [readonly] - - Indicates if the device is connected. - - string Interface [readonly] - - Indicates the network interface name when available. - - string UUID [readonly] - - Indicates the connection role when available. - - -Network server hierarchy -======================== - -Service org.bluez -Interface org.bluez.NetworkServer1 -Object path /org/bluez/{hci0,hci1,...} - -Methods void Register(string uuid, string bridge) - - Register server for the provided UUID. Every new - connection to this server will be added the bridge - interface. - - Valid UUIDs are "gn", "panu" or "nap". - - Initially no network server SDP is provided. Only - after this method a SDP record will be available - and the BNEP server will be ready for incoming - connections. - - void Unregister(string uuid) - - Unregister the server for provided UUID. - - All servers will be automatically unregistered when - the calling application terminates. diff --git a/doc/org.bluez.Network.rst b/doc/org.bluez.Network.rst new file mode 100644 index 000000000000..d81a69d3c8af --- /dev/null +++ b/doc/org.bluez.Network.rst @@ -0,0 +1,83 @@ +================= +org.bluez.Network +================= + +------------------------------------- +BlueZ D-Bus Network API documentation +------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.Network1 +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Methods +------- + +string Connect(string uuid) +``````````````````````````` + + Connects to the network device and return the network interface name. + + Possible uuid values: + + :"panu", "00001115-0000-1000-8000-00805f9b34fb": + + Personal Network User role. + + :"nap", "00001116-0000-1000-8000-00805f9b34fb": + + Network Access Point role. + + :"gn", "00001117-0000-1000-8000-00805f9b34fb": + + Group Network role. + + The connection will be closed and network device released either upon + calling **Disconnect()** or when the client disappears from the + message bus. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.NotSupported: + :org.bluez.Error.InProgress: + :org.bluez.Error.Failed: + +void Disconnect() +````````````````` + + Disconnects from the network device. + + To abort a connection attempt in case of errors or timeouts in the + client it is fine to call this method. + + Possible errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.NotConnected: + +Properties +---------- + +boolean Connected [readonly] +```````````````````````````` + + Indicates if the device is connected. + +string Interface [readonly, optional] +````````````````````````````````````` + + Indicates the network interface name when available. + +string UUID [readonly, optional] +```````````````````````````````` + + Indicates the connection role when available. diff --git a/doc/org.bluez.NetworkServer.rst b/doc/org.bluez.NetworkServer.rst new file mode 100644 index 000000000000..d15d223c5eca --- /dev/null +++ b/doc/org.bluez.NetworkServer.rst @@ -0,0 +1,68 @@ +======================= +org.bluez.NetworkServer +======================= + +------------------------------------------- +BlueZ D-Bus NetworkServer API documentation +------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.NetworkServer1 +:Object path: /org/bluez/{hci0,hci1,...} + + +Methods +------- + +void Register(string uuid, string bridge) +````````````````````````````````````````` + + Registers server for the provided UUID. + + Every new connection to this server will be added the bridge interface. + + Possible uuid values: + + :"panu", "00001115-0000-1000-8000-00805f9b34fb": + + Personal Network User role. + + :"nap", "00001116-0000-1000-8000-00805f9b34fb": + + Network Access Point role. + + :"gn", "00001117-0000-1000-8000-00805f9b34fb": + + Group Network role. + + Initially no network server SDP is provided. Only after this method a + SDP record will be available and the BNEP server will be ready for + incoming connections. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.AlreadyExists: + :org.bluez.Error.Failed: + +void Unregister(string uuid) +```````````````````````````` + + Unregisters the server for provided UUID which was previously + registered with **Register()** method. + + All servers will be automatically unregistered when the calling + application terminates. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.Failed: From patchwork Sat Oct 7 01:01:48 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 730524 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id AF4D9E9413D for ; Sat, 7 Oct 2023 01:02:06 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234011AbjJGBCF (ORCPT ); Fri, 6 Oct 2023 21:02:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:59054 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233990AbjJGBCE (ORCPT ); Fri, 6 Oct 2023 21:02:04 -0400 Received: from mail-pg1-x533.google.com (mail-pg1-x533.google.com [IPv6:2607:f8b0:4864:20::533]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8ECB8C2 for ; Fri, 6 Oct 2023 18:02:02 -0700 (PDT) Received: by mail-pg1-x533.google.com with SMTP id 41be03b00d2f7-565e395e7a6so1635031a12.0 for ; Fri, 06 Oct 2023 18:02:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696640521; x=1697245321; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=9ZEtrbzXngvXdJZfe4mzW0EEeYxGk5KHatJ0uG5DkXU=; b=PSwuWSDpX47x8MixbY29zES7ejS8dr1BD9y8tTluJjwTQPnCt855ia2x7DqitsR7bd UatvOwQPty3WCmL76/mz4iuwcDegTsXQT5xA5K08g4+63+CBo5EkzfbtBa8t4uzhNwOP MX+Ds3L1U1LLe6S666+GR9KFgYevV4bdy2o7lkhw4TLGbBYgr7+MHlQt2xOu2R/S2twB XdZ99TGRJZliBtrNp1ZUIzZt4NYu1j4FNST/zKSGuLiWh6SgkBrrd1dclO2F9tbgkKzE bPZd6CboqDDckiMo9ikoDw7qQ30yXz7fbwnt7OcN4zqUwbDbaVqkTukMQkm8MpycA4OY NMaA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696640521; x=1697245321; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=9ZEtrbzXngvXdJZfe4mzW0EEeYxGk5KHatJ0uG5DkXU=; b=htXpee/yGO/QOMXsKb2akLHU5l3Q83OP4sM8Yw8S+i6gwqXxMr6fwVKsAFVRizq+Rz hgJQnulJV0qVqZbj2Sitpvc09PBESSZf/K94ciVsnmIAk4kTasIR96OIvjUUfXKCgsIO lnIyESbpQWBFZnq2QukRirDYLRE9WR137I0IpL/Kou1ForK50shlHKYvNGxUIfonDS7q SAGf19s/KJJwpcteQn2h5r4SmfDxMVJXJbBksTzFSm4Bren9lqQhnJFnQcDrqdMXL1Ea gbMI/lHrd9oqxhVDL9CM7BWlmM97PB5dP7YK2uWBK6ah+A48ptJGQcJemIsKsOTMdqvc wSFg== X-Gm-Message-State: AOJu0YyuA8/crF+QVKb7DmDyUfbC0MiXyW6oqg4PpRt03odS8jxpCW+4 6tHnyQqwAFPHwUtwliLPJ1by0Wh0vAywU9cg X-Google-Smtp-Source: AGHT+IFlspJlsG3DD5b+QKXO6XhcQrlk6bIIZnuv5nPcqxvH8IFQH79Jh2VbbXl3YR0IX6wco8e/vw== X-Received: by 2002:a17:90a:6c47:b0:267:f9ab:15bb with SMTP id x65-20020a17090a6c4700b00267f9ab15bbmr8816835pjj.14.1696640520914; Fri, 06 Oct 2023 18:02:00 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id co11-20020a17090afe8b00b00279060a0fccsm4098360pjb.9.2023.10.06.18.01.59 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 06 Oct 2023 18:01:59 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH BlueZ 6/8] doc/input-api: Rename to org.bluez.Input.rst Date: Fri, 6 Oct 2023 18:01:48 -0700 Message-ID: <20231007010150.4103452-6-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231007010150.4103452-1-luiz.dentz@gmail.com> References: <20231007010150.4103452-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames input-api.txt to org.bluez.Input.rst and generate manpages org.bluez.Input.5. --- Makefile.am | 6 ++--- doc/input-api.txt | 32 -------------------------- doc/org.bluez.Input.rst | 51 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 54 insertions(+), 35 deletions(-) delete mode 100644 doc/input-api.txt create mode 100644 doc/org.bluez.Input.rst diff --git a/Makefile.am b/Makefile.am index 4507b72bbae7..38074c773b4f 100644 --- a/Makefile.am +++ b/Makefile.am @@ -361,7 +361,7 @@ man_MANS += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ doc/org.bluez.DeviceSet.5 doc/org.bluez.AgentManager.5 \ doc/org.bluez.Agent.5 doc/org.bluez.ProfileManager.5 \ doc/org.bluez.Profile.5 doc/org.bluez.NetworkServer.5 \ - doc/org.bluez.Network.5 + doc/org.bluez.Network.5 doc/org.bluez.Input.5 man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ @@ -414,13 +414,13 @@ EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \ EXTRA_DIST += doc/mgmt-api.txt \ doc/health-api.txt \ - doc/sap-api.txt doc/input-api.txt + doc/sap-api.txt EXTRA_DIST += doc/org.bluez.Adapter.rst doc/org.bluez.Device.rst \ doc/org.bluez.DeviceSet.rst doc/org.bluez.AgentManager.rst \ doc/org.bluez.Agent.rst doc/org.bluez.ProfileManager.rst \ doc/org.bluez.Profile.rst doc/org.bluez.NetworkServer.rst \ - doc/org.bluez.Network.rst + doc/org.bluez.Network.rst doc/org.bluez.Input.rst EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaPlayer.rst doc/org.bluez.MediaFolder.rst \ diff --git a/doc/input-api.txt b/doc/input-api.txt deleted file mode 100644 index 67da08b102c9..000000000000 --- a/doc/input-api.txt +++ /dev/null @@ -1,32 +0,0 @@ -BlueZ D-Bus Input API description -********************************* - -Input hierarchy -=============== - -Service org.bluez -Interface org.bluez.Input1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX - -Properties string ReconnectMode [readonly] - - Determines the Connectability mode of the HID device as - defined by the HID Profile specification, Section 5.4.2. - - This mode is based in the two properties - HIDReconnectInitiate (see Section 5.3.4.6) and - HIDNormallyConnectable (see Section 5.3.4.14) which - define the following four possible values: - - "none" Device and host are not required to - automatically restore the connection. - - "host" Bluetooth HID host restores connection. - - "device" Bluetooth HID device restores - connection. - - "any" Bluetooth HID device shall attempt to - restore the lost connection, but - Bluetooth HID Host may also restore the - connection. diff --git a/doc/org.bluez.Input.rst b/doc/org.bluez.Input.rst new file mode 100644 index 000000000000..c3c223c913d8 --- /dev/null +++ b/doc/org.bluez.Input.rst @@ -0,0 +1,51 @@ +=============== +org.bluez.Input +=============== + +----------------------------------- +BlueZ D-Bus Input API documentation +----------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.Input1 +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Properties +---------- + +string ReconnectMode [readonly] +``````````````````````````````` + + Indicates the Connectability mode of the HID device as defined by the + HID Profile specification, Section 5.4.2. + + This mode is based in the two properties HIDReconnectInitiate (see + Section 5.3.4.6) and HIDNormallyConnectable (see Section 5.3.4.14) which + define the following four possible values: + + :"none": + + Device and host are not required to automatically restore the + connection. + + :"host": + + Bluetooth HID host restores connection. + + :"device": + + Bluetooth HID device restores connection. + + :"any": + + Bluetooth HID device shall attempt to restore the lost + connection, but Bluetooth HID Host may also restore the + connection. From patchwork Sat Oct 7 01:01:49 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 731114 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9757EE94139 for ; Sat, 7 Oct 2023 01:02:09 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S233985AbjJGBCJ (ORCPT ); Fri, 6 Oct 2023 21:02:09 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49438 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233984AbjJGBCH (ORCPT ); Fri, 6 Oct 2023 21:02:07 -0400 Received: from mail-oi1-x236.google.com (mail-oi1-x236.google.com [IPv6:2607:f8b0:4864:20::236]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 60AF9BD for ; Fri, 6 Oct 2023 18:02:04 -0700 (PDT) Received: by mail-oi1-x236.google.com with SMTP id 5614622812f47-3af65455e7cso1796369b6e.1 for ; Fri, 06 Oct 2023 18:02:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696640523; x=1697245323; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=8zSSh2OLmHJPWCsoIzOBiFXvCbYCi1LbC5M2JuOLtPE=; b=Ek+aClDLaWqoYVuh4X7bTweMaU48h4nTZsjxF0JkTYDVaE//EsZRM+UihmkaQOqAOH t3Or2Zp1j4UfAUBR4exX8rCnp2qmidhVmLgbUsv4mmmQqL3C9qbwyaFrfpMeb/U7GiIs tbjy2CxrsJMZqbOueQw1qqsYjfman3B3mTfE+eNbQvnkYTUcaXa/EjCwanQFpoPvFQjI T7D8QlH75CuKnsogykoqw90UzVSL0cYAAGOsyIsT9Vf25fu7MvwrxS1TEI64C1mrUjR9 T2j8zkMpqBei9LCW+o17L+IOrk81N3htXBSbUuDixc7BCCo/76gpb37DG7Ae4D+WpXqn qv7A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696640523; x=1697245323; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=8zSSh2OLmHJPWCsoIzOBiFXvCbYCi1LbC5M2JuOLtPE=; b=D74jTz2eDBVY46J092ZxijxXhRfneSB6BPwnkqtFGkeNlKZiLBBKsM+cRBfLNM0WOe +bOyajU+YnxMDkWZrgx0WEIaC79WuJ6OYd0NFgqzXA5iUhpAjP+h7jTntoHWa8e4Ma6+ d2VnFr+bEvUpesQmZz8jH+VkNCLFDbyotJ3L2IvPw/xTcZ8Ev9J/HesqeIJIl/BdPyQ4 OUYjwuy33v5reZS4MitoKKZIyDUh8DcIpD1TDM0BoTVph9746SO7oZIYWr1R+RuBZsF5 PAgf8hEcwuK4yYl7J7xtxTdMqOB9M9z29Rsy6mdK+PSN/GfKLO7HOKujZIBMwKTMTTDX aG4g== X-Gm-Message-State: AOJu0YxFDi2e4RH9GMteNpIhSv4+Qq8cyqFBZ7t7yveoqkj0CRE1F/LS QQS2CR+uwJVUjexTM9akKBqqhlBLVENVvmVO X-Google-Smtp-Source: AGHT+IGzsuDBpiFy6gE7RheDV6uF4ZJBLrpgjhbLs1Q8d0yQFc2pXRAzyPFtlxXbgvJGE/yi+wb7lw== X-Received: by 2002:a05:6358:3407:b0:134:e3d2:1e50 with SMTP id h7-20020a056358340700b00134e3d21e50mr8745754rwd.18.1696640522575; Fri, 06 Oct 2023 18:02:02 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id co11-20020a17090afe8b00b00279060a0fccsm4098360pjb.9.2023.10.06.18.02.01 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 06 Oct 2023 18:02:01 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH BlueZ 7/8] doc/advertising-api: Rename to org.bluez.LEAdvertis*.rst Date: Fri, 6 Oct 2023 18:01:49 -0700 Message-ID: <20231007010150.4103452-7-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231007010150.4103452-1-luiz.dentz@gmail.com> References: <20231007010150.4103452-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames advertising-api.txt to org.bluez.LEAdvertis*.rst and generate manpages org.bluez.LEAdvertis*.5. --- Makefile.am | 7 +- doc/advertising-api.txt | 278 ------------------------- doc/org.bluez.LEAdvertisement.rst | 195 +++++++++++++++++ doc/org.bluez.LEAdvertisingManager.rst | 144 +++++++++++++ 4 files changed, 345 insertions(+), 279 deletions(-) delete mode 100644 doc/advertising-api.txt create mode 100644 doc/org.bluez.LEAdvertisement.rst create mode 100644 doc/org.bluez.LEAdvertisingManager.rst diff --git a/Makefile.am b/Makefile.am index 38074c773b4f..892965261bef 100644 --- a/Makefile.am +++ b/Makefile.am @@ -366,6 +366,8 @@ man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ doc/org.bluez.MediaTransport.5 +man_MANS += doc/org.bluez.LEAdvertisingManager.5 \ + doc/org.bluez.LEAdvertisement.5 endif manual_pages += src/bluetoothd.8 manual_pages += doc/org.bluez.Adapter.5 doc/org.bluez.Device.5 \ @@ -377,6 +379,8 @@ manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ doc/org.bluez.MediaTransport.5 +manual_pages += doc/org.bluez.LEAdvertisingManager.5 \ + doc/org.bluez.LEAdvertisement.5 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \ src/main.conf profiles/network/network.conf \ @@ -427,7 +431,8 @@ EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaItem.rst doc/org.bluez.MediaEndpoint.rst \ doc/org.bluez.MediaTransport.rst -EXTRA_DIST += doc/gatt-api.txt doc/advertising-api.txt +EXTRA_DIST += doc/gatt-api.txt doc/org.bluez.LEAdvertisingManager.rst \ + doc/org.bluez.LEAdvertisement.rst EXTRA_DIST += doc/obex-api.txt doc/obex-agent-api.txt diff --git a/doc/advertising-api.txt b/doc/advertising-api.txt deleted file mode 100644 index a0077843defd..000000000000 --- a/doc/advertising-api.txt +++ /dev/null @@ -1,278 +0,0 @@ -BlueZ D-Bus LE Advertising API Description -****************************************** - -Advertising packets are structured data which is broadcast on the LE Advertising -channels and available for all devices in range. Because of the limited space -available in LE Advertising packets (31 bytes), each packet's contents must be -carefully controlled. - -BlueZ acts as a store for the Advertisement Data which is meant to be sent. -It constructs the correct Advertisement Data from the structured -data and configured the kernel to send the correct advertisement. - -Advertisement Data objects are registered freely and then referenced by BlueZ -when constructing the data sent to the kernel. - -LE Advertisement Data hierarchy -=============================== - -Specifies the Advertisement Data to be broadcast and some advertising -parameters. Properties which are not present will not be included in the -data. Required advertisement data types will always be included. -All UUIDs are 128-bit versions in the API, and 16 or 32-bit -versions of the same UUID will be used in the advertising data as appropriate. - -Service org.bluez -Interface org.bluez.LEAdvertisement1 -Object path freely definable - -Methods void Release() [noreply] - - This method gets called when the service daemon - removes the Advertisement. A client can use it to do - cleanup tasks. There is no need to call - UnregisterAdvertisement because when this method gets - called it has already been unregistered. - -Properties string Type - - Determines the type of advertising packet requested. - - Possible values: "broadcast" or "peripheral" - - array{string} ServiceUUIDs - - List of UUIDs to include in the "Service UUID" field of - the Advertising Data. - - dict ManufacturerData - - Manufactuer Data fields to include in - the Advertising Data. Keys are the Manufacturer ID - to associate with the data. - - array{string} SolicitUUIDs - - Array of UUIDs to include in "Service Solicitation" - Advertisement Data. - - dict ServiceData - - Service Data elements to include. The keys are the - UUID to associate with the data. - - dict Data [Experimental] - - Advertising Type to include in the Advertising - Data. Key is the advertising type and value is the - data as byte array. - - Note: Types already handled by other properties shall - not be used. - - Possible values: - - ... - - Example: - - 0x26 0x01 0x01... - - bool Discoverable [Experimental] - - Advertise as general discoverable. When present this - will override adapter Discoverable property. - - Note: This property shall not be set when Type is set - to broadcast. - - uint16 DiscoverableTimeout [Experimental] - - The discoverable timeout in seconds. A value of zero - means that the timeout is disabled and it will stay in - discoverable/limited mode forever. - - Note: This property shall not be set when Type is set - to broadcast. - - array{string} Includes - - List of features to be included in the advertising - packet. - - Possible values: as found on - LEAdvertisingManager.SupportedIncludes - - string LocalName - - Local name to be used in the advertising report. If the - string is too big to fit into the packet it will be - truncated. - - If this property is available 'local-name' cannot be - present in the Includes. - - uint16 Appearance - - Appearance to be used in the advertising report. - - Possible values: as found on GAP Service. - - uint16_t Duration - - Rotation duration of the advertisement in seconds. If - there are other applications advertising no duration is - set the default is 2 seconds. - - uint16_t Timeout - - Timeout of the advertisement in seconds. This defines - the lifetime of the advertisement. - - string SecondaryChannel [Experimental] - - Secondary channel to be used. Primary channel is - always set to "1M" except when "Coded" is set. - - Possible value: "1M" (default) - "2M" - "Coded" - - uint32 MinInterval [Experimental] - - Minimum advertising interval to be used by the - advertising set, in milliseconds. Acceptable values - are in the range [20ms, 10,485s]. If the provided - MinInterval is larger than the provided MaxInterval, - the registration will return failure. - - uint32 MaxInterval [Experimental] - - Maximum advertising interval to be used by the - advertising set, in milliseconds. Acceptable values - are in the range [20ms, 10,485s]. If the provided - MinInterval is larger than the provided MaxInterval, - the registration will return failure. - - int16 TxPower [Experimental] - - Requested transmission power of this advertising set. - The provided value is used only if the "CanSetTxPower" - feature is enabled on the Advertising Manager. The - provided value must be in range [-127 to +20], where - units are in dBm. - - -LE Advertising Manager hierarchy -================================ - -The Advertising Manager allows external applications to register Advertisement -Data which should be broadcast to devices. Advertisement Data elements must -follow the API for LE Advertisement Data described above. - -Service org.bluez -Interface org.bluez.LEAdvertisingManager1 -Object path /org/bluez/{hci0,hci1,...} - -Methods RegisterAdvertisement(object advertisement, dict options) - - Registers an advertisement object to be sent over the LE - Advertising channel. The service must be exported - under interface LEAdvertisement1. - - InvalidArguments error indicates that the object has - invalid or conflicting properties. - - InvalidLength error indicates that the data - provided generates a data packet which is too long. - - The properties of this object are parsed when it is - registered, and any changes are ignored. - - If the same object is registered twice it will result in - an AlreadyExists error. - - If the maximum number of advertisement instances is - reached it will result in NotPermitted error. - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.AlreadyExists - org.bluez.Error.InvalidLength - org.bluez.Error.NotPermitted - - UnregisterAdvertisement(object advertisement) - - This unregisters an advertisement that has been - previously registered. The object path parameter must - match the same value that has been used on registration. - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.DoesNotExist - -Properties byte ActiveInstances - - Number of active advertising instances. - - byte SupportedInstances - - Number of available advertising instances. - - array{string} SupportedIncludes - - List of supported system includes. - - Possible values: "tx-power" - "appearance" - "local-name" - "rsi" - - array{string} SupportedSecondaryChannels [Experimental] - - List of supported Secondary channels. Secondary - channels can be used to advertise with the - corresponding PHY. - - Possible values: "1M" - "2M" - "Coded" - - dict SupportedCapabilities [Experimental] - - Enumerates Advertising-related controller capabilities - useful to the client. - - Possible Values: - - byte MaxAdvLen - - Max advertising data length - - byte MaxScnRspLen - - Max advertising scan response length - - int16 MinTxPower - - Min advertising tx power (dBm) - - int16 MaxTxPower - - Max advertising tx power (dBm) - - array{string} SupportedFeatures [readonly,optional,Experimental] - - List of supported platform features. If no features - are available on the platform, the SupportedFeatures - array will be empty. - - Possible values: "CanSetTxPower" - - Indicates whether platform can - specify tx power on each - advertising instance. - - "HardwareOffload" - - Indicates whether multiple - advertising will be offloaded - to the controller. diff --git a/doc/org.bluez.LEAdvertisement.rst b/doc/org.bluez.LEAdvertisement.rst new file mode 100644 index 000000000000..4609bde74a5e --- /dev/null +++ b/doc/org.bluez.LEAdvertisement.rst @@ -0,0 +1,195 @@ +========================= +org.bluez.LEAdvertisement +========================= + +--------------------------------------------- +BlueZ D-Bus LEAdvertisement API documentation +--------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +Advertising packets are structured data which is broadcast on the LE Advertising +channels and available for all devices in range. Because of the limited space +available in LE Advertising packets, each packet's contents must be carefully +controlled. + +The service daemon acts as a store for the Advertisement Data which is meant to +be sent. It constructs the correct Advertisement Data from the structured +data and configured the kernel to send the correct advertisement. + +Interface +========= + +Specifies the Advertisement Data to be broadcast and some advertising +parameters. Properties which are not present will not be included in the +data. Required advertisement data types will always be included. +All UUIDs are 128-bit versions in the API, and 16 or 32-bit +versions of the same UUID will be used in the advertising data as appropriate. + +:Service: org.bluez +:Interface: org.bluez.LEAdvertisement1 +:Object path: freely definable + +Methods +------- + +void Release() [noreply] +```````````````````````` + + This method gets called when the service daemon removes the + Advertisement. A client can use it to do cleanup tasks. There is no + need to call **UnregisterAdvertisement()** because when this method + gets called it has already been unregistered. + +Properties +---------- + +string Type [readonly] +`````````````````````` + + Determines the type of advertising packet requested. + + Possible values: + + :"broadcast": + :"peripheral": + +array{string} ServiceUUIDs +`````````````````````````` + + List of UUIDs to include in the "Service UUID" field of the Advertising + Data. + +dict ManufacturerData +````````````````````` + + Manufacturer Data fields to include in the Advertising Data. Keys are + the Manufacturer ID to associate with the data. + +array{string} SolicitUUIDs +`````````````````````````` + + Array of UUIDs to include in "Service Solicitation" Advertisement Data. + +dict ServiceData +```````````````` + + Service Data elements to include. The keys are the UUID to associate + with the data. + +dict Data [Experimental] +```````````````````````` + + Advertising Data to include. Key is the advertising type and value is + the data as byte array. + + Note: Types already handled by other properties shall not be used. + + Possible values: + + :: + + + + Example: + + 0x26 0x01 0x01... + +bool Discoverable [Experimental] +```````````````````````````````` + + Advertise as general discoverable. When present this will override + adapter Discoverable property. + + Note: This property shall not be set when **Type** is set to + "broadcast". + +uint16 DiscoverableTimeout [Experimental] +````````````````````````````````````````` + + The discoverable timeout in seconds. A value of zero means that the + timeout is disabled and it will stay in discoverable/limited mode + forever. + + Note: This property shall not be set when **Type** is set to + "broadcast". + +array{string} Includes +`````````````````````` + + List of features to be included in the advertising packet. + + Possible values: + + See **org.bluez.LEAdvertisingManager(5)** **SupportedIncludes** + property. + +string LocalName +```````````````` + + Local name to be used in the advertising report. If the string is too + big to fit into the packet it will be truncated. + + If this property is available 'local-name' cannot be present in the + **Includes**. + +uint16 Appearance +````````````````` + + Appearance to be used in the advertising report. + + Possible values: as found on GAP Service. + +uint16_t Duration +````````````````` + + Rotation duration of the advertisement in seconds. If there are other + applications advertising no duration is set the default is 2 seconds. + +uint16_t Timeout +```````````````` + + Timeout of the advertisement in seconds. This defines the lifetime of + the advertisement. + +string SecondaryChannel [Experimental] +`````````````````````````````````````` + + Secondary channel to be used. Primary channel is always set to "1M" + except when "Coded" is set. + + Possible value: + + :"1M" (default): + :"2M": + :"Coded": + +uint32 MinInterval [Experimental] +````````````````````````````````` + + Minimum advertising interval to be used by the advertising set, in + milliseconds. Acceptable values are in the range [20ms, 10,485s]. + If the provided MinInterval is larger than the provided MaxInterval, + the registration will return failure. + +uint32 MaxInterval [Experimental] +````````````````````````````````` + + Maximum advertising interval to be used by the advertising set, in + milliseconds. Acceptable values are in the range [20ms, 10,485s]. If the + provided MinInterval is larger than the provided MaxInterval, the + registration will return failure. + +int16 TxPower [Experimental] +```````````````````````````` + + Requested transmission power of this advertising set. The provided value + is used only if the "CanSetTxPower" feature is enabled on the + **org.bluez.LEAdvertisingManager(5)**. The provided value must be in + range [-127 to +20], where units are in dBm. diff --git a/doc/org.bluez.LEAdvertisingManager.rst b/doc/org.bluez.LEAdvertisingManager.rst new file mode 100644 index 000000000000..b9d5cafc6ff3 --- /dev/null +++ b/doc/org.bluez.LEAdvertisingManager.rst @@ -0,0 +1,144 @@ +============================== +org.bluez.LEAdvertisingManager +============================== + +------------------------------------------------- +BlueZ D-Bus LEAvertisingManager API documentation +------------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Interface +========= + +The Advertising Manager allows external applications to register Advertisement +Data which should be broadcast to devices. Advertisement Data elements must +follow the API for LE Advertisement Data described above. + +:Service: org.bluez +:Interface: org.bluez.LEAdvertisingManager1 +:Object path: /org/bluez/{hci0,hci1,...} + +Methods +------- + +void RegisterAdvertisement(object advertisement, dict options) +`````````````````````````````````````````````````````````````` + + Registers an advertisement object to be sent over the LE Advertising + channel. The service must implement **org.bluez.LEAdvertisement(5)** + interface. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + + Indicates that the object has invalid or conflicting properties. + + :org.bluez.Error.AlreadyExists: + + Indicates the object is already registered. + + :org.bluez.Error.InvalidLength: + + Indicates that the data provided generates a data packet which + is too long + + :org.bluez.Error.NotPermitted: + + Indicates the maximum number of advertisement instances has + been reached. + +void UnregisterAdvertisement(object advertisement) +`````````````````````````````````````````````````` + + Unregisters an advertisement that has been previously registered using + **RegisterAdvertisement()**. The object path parameter must match the + same value that has been used on registration. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.DoesNotExist: + +Properties +---------- + +byte ActiveInstances [readonly] +``````````````````````````````` + + Number of active advertising instances. + +byte SupportedInstances [readonly] +`````````````````````````````````` + + Number of available advertising instances. + +array{string} SupportedIncludes [readonly] +`````````````````````````````````````````` + + List of supported system includes. + + Possible values: + + :"tx-power": + :"appearance": + :"local-name": + :"rsi": + +array{string} SupportedSecondaryChannels [readonly, Experimental] +````````````````````````````````````````````````````````````````` + + List of supported Secondary channels. Secondary channels can be used to + advertise with the corresponding PHY. + + Possible values: + + :"1M": + :"2M": + :"Coded": + +dict SupportedCapabilities [readonly, Experimental] +``````````````````````````````````````````````````` + + Enumerates Advertising-related controller capabilities useful to the + client. + + Possible Values: + + :byte MaxAdvLen: + + Max advertising data length + + :byte MaxScnRspLen: + + Max advertising scan response length + + ;int16 MinTxPower: + + Min advertising tx power (dBm) + + :int16 MaxTxPower: + + Max advertising tx power (dBm) + +array{string} SupportedFeatures [readonly,optional,Experimental] +```````````````````````````````````````````````````````````````` + + List of supported platform features. If no features are available on + the platform, the SupportedFeatures array will be empty. + + Possible values: + + :"CanSetTxPower": + + Indicates whether platform can specify tx power on each + advertising instance. + + :"HardwareOffload": + + Indicates whether multiple advertising will be offloaded to the + controller. From patchwork Sat Oct 7 01:01:50 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luiz Augusto von Dentz X-Patchwork-Id: 730523 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id F0100E94139 for ; Sat, 7 Oct 2023 01:02:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234010AbjJGBCN (ORCPT ); Fri, 6 Oct 2023 21:02:13 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:49536 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S233984AbjJGBCM (ORCPT ); Fri, 6 Oct 2023 21:02:12 -0400 Received: from mail-pg1-x533.google.com (mail-pg1-x533.google.com [IPv6:2607:f8b0:4864:20::533]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id DE883CA for ; Fri, 6 Oct 2023 18:02:06 -0700 (PDT) Received: by mail-pg1-x533.google.com with SMTP id 41be03b00d2f7-564b6276941so1988629a12.3 for ; Fri, 06 Oct 2023 18:02:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1696640525; x=1697245325; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=a86wI1ZNAlgU2PnlOjRPjzbEAtoUse4LSuKIerJSG+Q=; b=EstbBsZDZWWGYzlnSgjA+hkQOynZs+GpB2ABQfCHVS3lG4Svtzbg8b8/exvjIJdKxi Xk6JwlYODZ7LnnFKhFmoSkUph0OinezK9oNJK5skEGouQJqFCzKFe88tf4VYjuTYjelX FPhK1AW90MtR59oWV3NJpVYfFgIEHsEymnj573HeYN7P6372C8ph/VIjomzKaWlv8uTm MOr/1a5fnsoNd8F9G6vVkX6K7zmZ3g+XqHhRiK3BIhsYiII4ikO9yxsAUo6tZ6ADOMaZ HXoRtUTZRfK9I+QICh2xHDuSQSL8KYLgI9Zmt7ZHzaE+xoh/JuEgZlGgckGoWOrmxpqh AmJw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1696640525; x=1697245325; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=a86wI1ZNAlgU2PnlOjRPjzbEAtoUse4LSuKIerJSG+Q=; b=g3itXts65JUDY1CCPXhHOyjHaUkegdHLS2C2iRcIFXjiuycAKbXDu3Qfpe1ICw3Web TVXOuu7Ha32nQIBuwX41/9Hj+qxrgZriy+8QP/kSEc+4TxY5zgXmRKnSTeoaV0MWef6q Hp2hTrDTUDna2p+v0DXZCHvsuvHMBJN7Ndi5mPrTf7iUn+z8bByAbqv4QwNfUhHZlBjt Wtx9CdkBp/o2NmS/PyF5iaP63EWAnIkjEq9U9WdLt1uC8XbJ2KCrCPk73zV2FtUxlLRB /xOWctlM61YEpKe0BJqo2UINkPeuwieLaikxe0sih1HW81vcMniyscIy3lOXBfivyWLq kTGw== X-Gm-Message-State: AOJu0Yy6anwTpWLBU/L437p/fg68I/0raabh6P0b/ep0jD1Ye05moHge owvfaQ9gOSPYpKPLHJe00qZzXu2T+zIACYbU X-Google-Smtp-Source: AGHT+IFwlJHloscmpTbd8se7jROgw+h4NikQ3kjvSn5x/5hh5bW8gyw7iIFOZkBhP0vgO3+6uNAcEg== X-Received: by 2002:a17:90a:8004:b0:274:6a79:17c1 with SMTP id b4-20020a17090a800400b002746a7917c1mr9721009pjn.15.1696640524687; Fri, 06 Oct 2023 18:02:04 -0700 (PDT) Received: from lvondent-mobl4.. (c-98-232-221-87.hsd1.or.comcast.net. [98.232.221.87]) by smtp.gmail.com with ESMTPSA id co11-20020a17090afe8b00b00279060a0fccsm4098360pjb.9.2023.10.06.18.02.02 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 06 Oct 2023 18:02:03 -0700 (PDT) From: Luiz Augusto von Dentz To: linux-bluetooth@vger.kernel.org Subject: [PATCH BlueZ 8/8] doc/gatt-api: Rename to org.bluez.Gatt*.rst Date: Fri, 6 Oct 2023 18:01:50 -0700 Message-ID: <20231007010150.4103452-8-luiz.dentz@gmail.com> X-Mailer: git-send-email 2.41.0 In-Reply-To: <20231007010150.4103452-1-luiz.dentz@gmail.com> References: <20231007010150.4103452-1-luiz.dentz@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-bluetooth@vger.kernel.org From: Luiz Augusto von Dentz This renames gatt-api.txt to org.bluez.Gatt*.rst and generate manpages org.bluez.Gatt*.5. --- Makefile.am | 18 +- doc/gatt-api.txt | 512 --------------------------- doc/org.bluez.GattCharacteristic.rst | 375 ++++++++++++++++++++ doc/org.bluez.GattDescriptor.rst | 167 +++++++++ doc/org.bluez.GattManager.rst | 114 ++++++ doc/org.bluez.GattProfile.rst | 46 +++ doc/org.bluez.GattService.rst | 79 +++++ 7 files changed, 796 insertions(+), 515 deletions(-) delete mode 100644 doc/gatt-api.txt create mode 100644 doc/org.bluez.GattCharacteristic.rst create mode 100644 doc/org.bluez.GattDescriptor.rst create mode 100644 doc/org.bluez.GattManager.rst create mode 100644 doc/org.bluez.GattProfile.rst create mode 100644 doc/org.bluez.GattService.rst diff --git a/Makefile.am b/Makefile.am index 892965261bef..d658dc27500a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -366,7 +366,11 @@ man_MANS += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ doc/org.bluez.MediaTransport.5 -man_MANS += doc/org.bluez.LEAdvertisingManager.5 \ +man_MANS += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \ + doc/org.bluez.GattService.5 \ + doc/org.bluez.GattCharacteristic.5 \ + doc/org.bluez.GattDescriptor.5 \ + doc/org.bluez.LEAdvertisingManager.5 \ doc/org.bluez.LEAdvertisement.5 endif manual_pages += src/bluetoothd.8 @@ -379,7 +383,11 @@ manual_pages += doc/org.bluez.Media.5 doc/org.bluez.MediaControl.5 \ doc/org.bluez.MediaPlayer.5 doc/org.bluez.MediaFolder.5 \ doc/org.bluez.MediaItem.5 doc/org.bluez.MediaEndpoint.5 \ doc/org.bluez.MediaTransport.5 -manual_pages += doc/org.bluez.LEAdvertisingManager.5 \ +manual_pages += doc/org.bluez.GattManager.5 doc/org.bluez.GattProfile.5 \ + doc/org.bluez.GattService.5 \ + doc/org.bluez.GattCharacteristic.5 \ + doc/org.bluez.GattDescriptor.5 \ + doc/org.bluez.LEAdvertisingManager.5 \ doc/org.bluez.LEAdvertisement.5 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \ @@ -431,7 +439,11 @@ EXTRA_DIST += doc/org.bluez.Media.rst doc/org.bluez.MediaControl.rst \ doc/org.bluez.MediaItem.rst doc/org.bluez.MediaEndpoint.rst \ doc/org.bluez.MediaTransport.rst -EXTRA_DIST += doc/gatt-api.txt doc/org.bluez.LEAdvertisingManager.rst \ +EXTRA_DIST += doc/org.bluez.GattManager.rst doc/org.bluez.GattProfile.rst\ + doc/org.bluez.GattService.rst \ + doc/org.bluez.GattCharacteristic.rst \ + doc/org.bluez.GattDescriptor.rst \ + doc/org.bluez.LEAdvertisingManager.rst \ doc/org.bluez.LEAdvertisement.rst EXTRA_DIST += doc/obex-api.txt doc/obex-agent-api.txt diff --git a/doc/gatt-api.txt b/doc/gatt-api.txt deleted file mode 100644 index f29308aec843..000000000000 --- a/doc/gatt-api.txt +++ /dev/null @@ -1,512 +0,0 @@ -BlueZ D-Bus GATT API description -******************************** - -GATT local and remote services share the same high-level D-Bus API. Local -refers to GATT based service exported by a BlueZ plugin or an external -application. Remote refers to GATT services exported by the peer. - -BlueZ acts as a proxy, translating ATT operations to D-Bus method calls and -Properties (or the opposite). Support for D-Bus Object Manager is mandatory for -external services to allow seamless GATT declarations (Service, Characteristic -and Descriptors) discovery. Each GATT service tree is required to export a D-Bus -Object Manager at its root that is solely responsible for the objects that -belong to that service. - -Releasing a registered GATT service is not defined yet. Any API extension -should avoid breaking the defined API, and if possible keep an unified GATT -remote and local services representation. - -Service hierarchy -================= - -GATT remote and local service representation. Object path for local services -is freely definable. - -External applications implementing local services must register the services -using GattManager1 registration method and must implement the methods and -properties defined in GattService1 interface. - -Service org.bluez -Interface org.bluez.GattService1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX - -Properties string UUID [read-only] - - 128-bit service UUID. - - boolean Primary [read-only] - - Indicates whether or not this GATT service is a - primary service. If false, the service is secondary. - - object Device [read-only, optional] - - Object path of the Bluetooth device the service - belongs to. Only present on services from remote - devices. - - array{object} Includes [read-only, optional] - - Array of object paths representing the included - services of this service. - - uint16 Handle [read-write, optional] (Server Only) - [read-only] (Client Only) - - Service handle. When available in the server it - would attempt to use to allocate into the database - which may fail, to auto allocate the value 0x0000 - shall be used which will cause the allocated handle to - be set once registered. - - -Characteristic hierarchy -======================== - -For local GATT defined services, the object paths need to follow the service -path hierarchy and are freely definable. - -Service org.bluez -Interface org.bluez.GattCharacteristic1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY - -Methods array{byte} ReadValue(dict options) - - Issues a request to read the value of the - characteristic and returns the value if the - operation was successful. - - Possible options: "offset": uint16 offset - "mtu": Exchanged MTU (Server only) - "device": Object Device (Server only) - - Possible Errors: org.bluez.Error.Failed(string ecode) - org.bluez.Error.InProgress - org.bluez.Error.NotPermitted - org.bluez.Error.NotAuthorized - org.bluez.Error.InvalidOffset - org.bluez.Error.NotSupported - - Possible Error Code: string 0x80 - 0x9f - - void WriteValue(array{byte} value, dict options) - - Issues a request to write the value of the - characteristic. - - Possible options: "offset": Start offset - "type": string - Possible values: - "command": Write without - response - "request": Write with response - "reliable": Reliable Write - "mtu": Exchanged MTU (Server only) - "device": Device path (Server only) - "link": Link type (Server only) - "prepare-authorize": True if prepare - authorization - request - - Possible Errors: org.bluez.Error.Failed(string ecode) - org.bluez.Error.InProgress - org.bluez.Error.NotPermitted - org.bluez.Error.InvalidValueLength - org.bluez.Error.NotAuthorized - org.bluez.Error.NotSupported - - Possible Error Code: string 0x80 - 0x9f - - fd, uint16 AcquireWrite(dict options) [optional] - - Acquire file descriptor and MTU for writing. Only - sockets are supported. Usage of WriteValue will be - locked causing it to return NotPermitted error. - - For server the MTU returned shall be equal or smaller - than the negotiated MTU. - - For client it only works with characteristic that has - WriteAcquired property which relies on - write-without-response Flag. - - To release the lock the client shall close the file - descriptor, a HUP is generated in case the device - is disconnected. - - Note: the MTU can only be negotiated once and is - symmetric therefore this method may be delayed in - order to have the exchange MTU completed, because of - that the file descriptor is closed during - reconnections as the MTU has to be renegotiated. - - Possible options: "device": Object Device (Server only) - "mtu": Exchanged MTU (Server only) - "link": Link type (Server only) - - Possible Errors: org.bluez.Error.Failed - org.bluez.Error.NotSupported - - fd, uint16 AcquireNotify(dict options) [optional] - - Acquire file descriptor and MTU for notify. Only - sockets are support. Usage of StartNotify will be locked - causing it to return NotPermitted error. - - For server the MTU returned shall be equal or smaller - than the negotiated MTU. - - Only works with characteristic that has NotifyAcquired - which relies on notify Flag and no other client have - called StartNotify. - - Notification are enabled during this procedure so - StartNotify shall not be called, any notification - will be dispatched via file descriptor therefore the - Value property is not affected during the time where - notify has been acquired. - - To release the lock the client shall close the file - descriptor, a HUP is generated in case the device - is disconnected. - - Note: the MTU can only be negotiated once and is - symmetric therefore this method may be delayed in - order to have the exchange MTU completed, because of - that the file descriptor is closed during - reconnections as the MTU has to be renegotiated. - - Possible options: "device": Object Device (Server only) - "mtu": Exchanged MTU (Server only) - "link": Link type (Server only) - - Possible Errors: org.bluez.Error.Failed - org.bluez.Error.NotSupported - - void StartNotify() - - Starts a notification session from this characteristic - if it supports value notifications or indications. - - Possible Errors: org.bluez.Error.Failed - org.bluez.Error.NotPermitted - org.bluez.Error.InProgress - org.bluez.Error.NotConnected - org.bluez.Error.NotSupported - - void StopNotify() - - This method will cancel any previous StartNotify - transaction. Note that notifications from a - characteristic are shared between sessions thus - calling StopNotify will release a single session. - - Possible Errors: org.bluez.Error.Failed - - void Confirm() [optional] (Server only) - - This method doesn't expect a reply so it is just a - confirmation that value was received. - - Possible Errors: org.bluez.Error.Failed - -Properties string UUID [read-only] - - 128-bit characteristic UUID. - - object Service [read-only] - - Object path of the GATT service the characteristic - belongs to. - - array{byte} Value [read-only, optional] - - The cached value of the characteristic. This property - gets updated only after a successful read request and - when a notification or indication is received, upon - which a PropertiesChanged signal will be emitted. - - boolean WriteAcquired [read-only, optional] - - True, if this characteristic has been acquired by any - client using AcquireWrite. - - For client properties is ommited in case - 'write-without-response' flag is not set. - - For server the presence of this property indicates - that AcquireWrite is supported. - - boolean NotifyAcquired [read-only, optional] - - True, if this characteristic has been acquired by any - client using AcquireNotify. - - For client this properties is ommited in case 'notify' - flag is not set. - - For server the presence of this property indicates - that AcquireNotify is supported. - - boolean Notifying [read-only, optional] - - True, if notifications or indications on this - characteristic are currently enabled. - - array{string} Flags [read-only] - - Defines how the characteristic value can be used. See - Core spec "Table 3.5: Characteristic Properties bit - field", and "Table 3.8: Characteristic Extended - Properties bit field". - - The "x-notify" and "x-indicate" flags restrict access - to notifications and indications by imposing write - restrictions on a characteristic's client - characteristic configuration descriptor. - - Allowed values: - - "broadcast" - "read" - "write-without-response" - "write" - "notify" - "indicate" - "authenticated-signed-writes" - "extended-properties" - "reliable-write" - "writable-auxiliaries" - "encrypt-read" - "encrypt-write" - "encrypt-notify" (Server only) - "encrypt-indicate" (Server only) - "encrypt-authenticated-read" - "encrypt-authenticated-write" - "encrypt-authenticated-notify" (Server only) - "encrypt-authenticated-indicate" (Server only) - "secure-read" (Server only) - "secure-write" (Server only) - "secure-notify" (Server only) - "secure-indicate" (Server only) - "authorize" - - uint16 Handle [read-write, optional] (Server Only) - [read-only] (Client Only) - - Characteristic handle. When available in the server it - would attempt to use to allocate into the database - which may fail, to auto allocate the value 0x0000 - shall be used which will cause the allocated handle to - be set once registered. - - uint16 MTU [read-only] - - Characteristic MTU, this is valid both for ReadValue - and WriteValue but either method can use long - procedures when supported. - -Characteristic Descriptors hierarchy -==================================== - -Local or remote GATT characteristic descriptors hierarchy. - -Service org.bluez -Interface org.bluez.GattDescriptor1 -Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ - -Methods array{byte} ReadValue(dict flags) - - Issues a request to read the value of the - characteristic and returns the value if the - operation was successful. - - Possible options: "offset": Start offset - "device": Device path (Server only) - "link": Link type (Server only) - - Possible Errors: org.bluez.Error.Failed - org.bluez.Error.InProgress - org.bluez.Error.NotPermitted - org.bluez.Error.NotAuthorized - org.bluez.Error.NotSupported - - void WriteValue(array{byte} value, dict flags) - - Issues a request to write the value of the - characteristic. - - Possible options: "offset": Start offset - "device": Device path (Server only) - "link": Link type (Server only) - "prepare-authorize": boolean Is prepare - authorization - request - - Possible Errors: org.bluez.Error.Failed - org.bluez.Error.InProgress - org.bluez.Error.NotPermitted - org.bluez.Error.InvalidValueLength - org.bluez.Error.NotAuthorized - org.bluez.Error.NotSupported - -Properties string UUID [read-only] - - 128-bit descriptor UUID. - - object Characteristic [read-only] - - Object path of the GATT characteristic the descriptor - belongs to. - - array{byte} Value [read-only, optional] - - The cached value of the descriptor. This property - gets updated only after a successful read request, upon - which a PropertiesChanged signal will be emitted. - - array{string} Flags [read-only] - - Defines how the descriptor value can be used. - - Possible values: - - "read" - "write" - "encrypt-read" - "encrypt-write" - "encrypt-authenticated-read" - "encrypt-authenticated-write" - "secure-read" (Server Only) - "secure-write" (Server Only) - "authorize" - - uint16 Handle [read-write, optional] (Server Only) - [read-only] (Client Only) - - Characteristic handle. When available in the server it - would attempt to use to allocate into the database - which may fail, to auto allocate the value 0x0000 - shall be used which will cause the allocated handle to - be set once registered. - -GATT Profile hierarchy -===================== - -Local profile (GATT client) instance. By registering this type of object -an application effectively indicates support for a specific GATT profile -and requests automatic connections to be established to devices -supporting it. - -Service -Interface org.bluez.GattProfile1 -Object path - -Methods void Release() - - This method gets called when the service daemon - unregisters the profile. The profile can use it to - do cleanup tasks. There is no need to unregister the - profile, because when this method gets called it has - already been unregistered. - -Properties array{string} UUIDs [read-only] - - 128-bit GATT service UUIDs to auto connect. - - -GATT Manager hierarchy -====================== - -GATT Manager allows external applications to register GATT services and -profiles. - -Registering a profile allows applications to subscribe to *remote* services. -These must implement the GattProfile1 interface defined above. - -Registering a service allows applications to publish a *local* GATT service, -which then becomes available to remote devices. A GATT service is represented by -a D-Bus object hierarchy where the root node corresponds to a service and the -child nodes represent characteristics and descriptors that belong to that -service. Each node must implement one of GattService1, GattCharacteristic1, -or GattDescriptor1 interfaces described above, based on the attribute it -represents. Each node must also implement the standard D-Bus Properties -interface to expose their properties. These objects collectively represent a -GATT service definition. - -To make service registration simple, BlueZ requires that all objects that belong -to a GATT service be grouped under a D-Bus Object Manager that solely manages -the objects of that service. Hence, the standard DBus.ObjectManager interface -must be available on the root service path. An example application hierarchy -containing two separate GATT services may look like this: - --> /com/example - | - org.freedesktop.DBus.ObjectManager - | - -> /com/example/service0 - | | - org.freedesktop.DBus.Properties - | | - org.bluez.GattService1 - | | - | -> /com/example/service0/char0 - | | - org.freedesktop.DBus.Properties - | | - org.bluez.GattCharacteristic1 - | | - | -> /com/example/service0/char1 - | | - org.freedesktop.DBus.Properties - | | - org.bluez.GattCharacteristic1 - | | - | -> /com/example/service0/char1/desc0 - | - org.freedesktop.DBus.Properties - | - org.bluez.GattDescriptor1 - | - -> /com/example/service1 - | - org.freedesktop.DBus.Properties - | - org.bluez.GattService1 - | - -> /com/example/service1/char0 - - org.freedesktop.DBus.Properties - - org.bluez.GattCharacteristic1 - -When a service is registered, BlueZ will automatically obtain information about -all objects using the service's Object Manager. Once a service has been -registered, the objects of a service should not be removed. If BlueZ receives an -InterfacesRemoved signal from a service's Object Manager, it will immediately -unregister the service. Similarly, if the application disconnects from the bus, -all of its registered services will be automatically unregistered. -InterfacesAdded signals will be ignored. - -Examples: - - Client - test/example-gatt-client - client/bluetoothctl - - Server - test/example-gatt-server - tools/gatt-service - - -Service org.bluez -Interface org.bluez.GattManager1 -Object path [variable prefix]/{hci0,hci1,...} - -Methods void RegisterApplication(object application, dict options) - - Registers a local GATT services hierarchy as described - above (GATT Server) and/or GATT profiles (GATT Client). - - The application object path together with the D-Bus - system bus connection ID define the identification of - the application registering a GATT based - service or profile. - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.AlreadyExists - - void UnregisterApplication(object application) - - This unregisters the services that has been - previously registered. The object path parameter - must match the same value that has been used - on registration. - - Possible errors: org.bluez.Error.InvalidArguments - org.bluez.Error.DoesNotExist diff --git a/doc/org.bluez.GattCharacteristic.rst b/doc/org.bluez.GattCharacteristic.rst new file mode 100644 index 000000000000..cd5a0d0c788f --- /dev/null +++ b/doc/org.bluez.GattCharacteristic.rst @@ -0,0 +1,375 @@ +============================ +org.bluez.GattCharacteristic +============================ + +------------------------------------------------ +BlueZ D-Bus GattCharacteristic API documentation +------------------------------------------------ + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +GATT local/server and remote/client characteristic attribute representation +share the same high-level D-Bus API. + +Local/Server refers to GATT based characteristics exported by a plugin or an +external application. + +Remote/Client refers to GATT characteristics exported by the peer. + +Interface +========= + +Client +------ + +:Service: org.bluez +:Interface: org.bluez.GattCharacteristic1 +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY + +Server +------ + +:Service: unique name +:Interface: org.bluez.GattCharacteristic1 +:Object path: freely definable + +Methods +------- + +array{byte} ReadValue(dict options) +``````````````````````````````````` + + Issues a request to read the value of the characteristic and returns the + value if the operation was successful. + + Possible options: + + :uint16_t offset: + + Read start offset in bytes. + + :uint16_t mtu (server only): + + Exchange MTU in bytes. + + :object device (server only): + + Device object. + + Possible Errors: + + :org.bluez.Error.Failed: + + Possible values: string 0x80 - 0x9f + + :org.bluez.Error.InProgress: + :org.bluez.Error.NotPermitted: + :org.bluez.Error.NotAuthorized: + :org.bluez.Error.InvalidOffset: + :org.bluez.Error.NotSupported: + +void WriteValue(array{byte} value, dict options) +```````````````````````````````````````````````` + + Issues a request to write the value of the characteristic. + + Possible options: + + :uint16 offset: + + Write start offset in bytes. + + :string type: + + Possible values: + + :"command": + + Use Write without response procedure. + + :"request": + + Use Write with response procedure. + + :"reliable": + + Use Reliable Write procedure. + + :uint16 mtu: + + Exchanged MTU (Server only). + + :object device: + + Device path (Server only). + + :string link: + + Link type (Server only). + + Possible values: + + :"BR/EDR": + :"LE": + + :boolean prepare-authorize: + + True if prepare authorization request. + + Possible Errors: + + :org.bluez.Error.Failed: + + Possible values: string 0x80 - 0x9f + + :org.bluez.Error.InProgress: + :org.bluez.Error.NotPermitted: + :org.bluez.Error.InvalidValueLength: + :org.bluez.Error.NotAuthorized: + :org.bluez.Error.NotSupported: + +fd, uint16 AcquireWrite(dict options) [optional] +```````````````````````````````````````````````` + + Acquire file descriptor and MTU for writing. Only sockets are supported. + Usage of WriteValue will be locked causing it to return NotPermitted + error. + + For server the MTU returned shall be equal or smaller than the + negotiated MTU. + + For client it only works with characteristic that has **WriteAcquired** + property which relies on write-without-response **Flag**. + + To release the lock the client shall close the file descriptor, a HUP + is generated in case the device is disconnected. + + Note: the MTU can only be negotiated once and is symmetric therefore + this method may be delayed in order to have the exchange MTU completed, + because of that the file descriptor is closed during reconnections as + the MTU has to be renegotiated. + + Possible options: + + :object device: + + Object Device (Server only). + + :uint16 mtu: + + Exchanged MTU (Server only). + + :string link: + + Link type (Server only). + + Possible values: + + :"BR/EDR": + :"LE": + + Possible Errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.NotSupported: + +fd, uint16 AcquireNotify(dict options) [optional] +````````````````````````````````````````````````` + + Acquire file descriptor and MTU for notify. Only sockets are support. + + Usage of StartNotify will be locked causing it to return + **org.bluez.Error.NotPermitted**. + + For server the MTU returned shall be equal or smaller than the + negotiated MTU. + + Only works with characteristic that has **NotifyAcquired** property + which relies on **"notify"** **Flag** and no other client have called + **StartNotify()**. + + Notification are enabled during this procedure so **StartNotify()** + shall not be called, any notification will be dispatched via file + descriptor therefore the Value property is not affected during the time + where notify has been acquired. + + To release the lock the client shall close the file descriptor, a HUP is + generated in case the device is disconnected. + + Note: the MTU can only be negotiated once and is symmetric therefore + this method may be delayed in order to have the exchange MTU completed, + because of that the file descriptor is closed during reconnections as + the MTU has to be renegotiated. + + Possible options: + + :object device: + + Object Device (Server only). + + :uint16 mtu: + + Exchanged MTU (Server only). + + :string link: + + Link type (Server only). + + Possible values: + + :"BR/EDR": + :"LE": + + Possible Errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.NotSupported: + :org.bluez.Error.NotPermitted: + +void StartNotify() +`````````````````` + + Starts a notification session from this characteristic if it supports + value notifications or indications. + + Possible Errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.NotPermitted: + :org.bluez.Error.InProgress: + :org.bluez.Error.NotConnected: + :org.bluez.Error.NotSupported: + +void StopNotify() +````````````````` + + Stops or cancel session previously created by **StartNotify()**. + + Note that notifications from a characteristic are shared between + sessions thus calling StopNotify will release a single session. + + Possible Errors: + + :org.bluez.Error.Failed: + +void Confirm() [noreply, optional] (Server only) +```````````````````````````````````````````````` + + + Confirms value was received. + + Possible Errors: + + org.bluez.Error.Failed + +Properties +---------- + +string UUID [read-only] +``````````````````````` + + 128-bit characteristic UUID. + +object Service [read-only] +`````````````````````````` + + Object path of the GATT service the characteristic belongs to. + +array{byte} Value [read-only, optional] +``````````````````````````````````````` + + The cached value of the characteristic. This property gets updated only + after a successful read request and when a notification or indication + is received, upon which a PropertiesChanged signal will be emitted. + +boolean WriteAcquired [read-only, optional] +``````````````````````````````````````````` + + True, if this characteristic has been acquired by any client using + AcquireWrite. + + For client properties is ommited in case 'write-without-response' flag + is not set. + + For server the presence of this property indicates that AcquireWrite is + supported. + +boolean NotifyAcquired [read-only, optional] +```````````````````````````````````````````` + + True, if this characteristic has been acquired by any client using + AcquireNotify. + + For client this properties is ommited in case 'notify' flag is not set. + + For server the presence of this property indicates that AcquireNotify + is supported. + +boolean Notifying [read-only, optional] +``````````````````````````````````````` + + True, if notifications or indications on this characteristic are + currently enabled. + +array{string} Flags [read-only] +``````````````````````````````` + + Defines how the characteristic value can be used. See Core spec + "Table 3.5: Characteristic Properties bit field", and + "Table 3.8: Characteristic Extended Properties bit field". + + The "x-notify" and "x-indicate" flags restrict access to notifications + and indications by imposing write restrictions on a characteristic's + client characteristic configuration descriptor. + + Possible values: + + :"broadcast": + :"read": + :"write-without-response": + :"write": + :"notify": + :"indicate": + :"authenticated-signed-writes": + :"extended-properties": + :"reliable-write": + :"writable-auxiliaries": + :"encrypt-read": + :"encrypt-write": + :"encrypt-notify" (Server only): + :"encrypt-indicate" (Server only): + :"encrypt-authenticated-read": + :"encrypt-authenticated-write": + :"encrypt-authenticated-notify" (Server only): + :"encrypt-authenticated-indicate" (Server only): + :"secure-read" (Server only): + :"secure-write" (Server only): + :"secure-notify" (Server only): + :"secure-indicate" (Server only): + :"authorize": + +uint16 Handle [read-only] (Client Only) +``````````````````````````````````````` + + Characteristic handle. + +uint16 Handle [read-write, optional] (Server Only) +`````````````````````````````````````````````````` + + Characteristic handle. When available in the server it would attempt to + use to allocate into the database which may fail, to auto allocate the + value 0x0000 shall be used which will cause the allocated handle to be + set once registered. + +uint16 MTU [read-only] +`````````````````````` + + Characteristic MTU, this is valid both for **ReadValue()** and + **WriteValue()** but either method can use long procedures when + supported. diff --git a/doc/org.bluez.GattDescriptor.rst b/doc/org.bluez.GattDescriptor.rst new file mode 100644 index 000000000000..94cc8b26af29 --- /dev/null +++ b/doc/org.bluez.GattDescriptor.rst @@ -0,0 +1,167 @@ +======================== +org.bluez.GattDescriptor +======================== + +-------------------------------------------- +BlueZ D-Bus GattDescriptor API documentation +-------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +GATT local/server and remote/client descriptor attribute representation +share the same high-level D-Bus API. + +Local/Server refers to GATT based descriptors exported by a plugin or an +external application. + +Remote/Client refers to GATT descriptors exported by the peer. + +Interface +========= + +Client +------ + +:Service: org.bluez +:Interface: org.bluez.GattDescriptor1 +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ + +Server +------ + +:Service: unique name +:Interface: org.bluez.GattDescriptor1 +:Object path: freely definable + +Methods +------- + +array{byte} ReadValue(dict flags) +````````````````````````````````` + + Issues a request to read the value of the descriptor and returns the + value if the operation was successful. + + Possible options: + + :uint16_t offset: + + Read start offset in bytes. + + :object device (server only): + + Device object. + + :string link: + + Link type (Server only). + + Possible values: + + :"BR/EDR": + :"LE": + + Possible Errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.InProgress: + :org.bluez.Error.NotPermitted: + :org.bluez.Error.NotAuthorized: + :org.bluez.Error.NotSupported: + +void WriteValue(array{byte} value, dict flags) +`````````````````````````````````````````````` + + Issues a request to write the value of the descriptor. + + Possible flags: + + :uint16 offset: + + Write start offset in bytes. + + :uint16 mtu: + + Exchanged MTU (Server only). + + :object device: + + Device path (Server only). + + :string link: + + Link type (Server only). + + Possible values: + + :"BR/EDR": + :"LE": + + :boolean prepare-authorize: + + True if prepare authorization request. + + Possible Errors: + + :org.bluez.Error.Failed: + :org.bluez.Error.InProgress: + :org.bluez.Error.NotPermitted: + :org.bluez.Error.InvalidValueLength: + :org.bluez.Error.NotAuthorized: + :org.bluez.Error.NotSupported: + +Properties +---------- + +string UUID [read-only] +``````````````````````` + + 128-bit descriptor UUID. + +object Characteristic [read-only] +````````````````````````````````` + + Object path of the GATT characteristic the descriptor belongs to. + +array{byte} Value [read-only, optional] +``````````````````````````````````````` + + The cached value of the descriptor. This property gets updated only + after a successful read request, upon which a PropertiesChanged signal + will be emitted. + +array{string} Flags [read-only] +``````````````````````````````` + + Defines how the descriptor value can be used. + + Possible values: + + :"read": + :"write": + :"encrypt-read": + :"encrypt-write": + :"encrypt-authenticated-read": + :"encrypt-authenticated-write": + :"secure-read" (Server Only): + :"secure-write" (Server Only): + :"authorize": + +uint16 Handle [read-only] (Client Only) +``````````````````````````````````````` + + Descriptor handle. + +uint16 Handle [read-write, optional] (Server Only) +`````````````````````````````````````````````````` + + Descriptor handle. When available in the server it would attempt to + use to allocate into the database which may fail, to auto allocate the + value 0x0000 shall be used which will cause the allocated handle to be + set once registered. diff --git a/doc/org.bluez.GattManager.rst b/doc/org.bluez.GattManager.rst new file mode 100644 index 000000000000..f98296b89a01 --- /dev/null +++ b/doc/org.bluez.GattManager.rst @@ -0,0 +1,114 @@ +===================== +org.bluez.GattManager +===================== + +----------------------------------------- +BlueZ D-Bus GattManager API documentation +----------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +GATT Manager allows external applications to register GATT services and +profiles. + +Registering a profile allows applications to subscribe to *remote/client* +services. + +Registering a service allows applications to publish a *local/server* GATT +service, which then becomes available to remote devices. A GATT service is +represented by a D-Bus object hierarchy where the root node corresponds to a +service and the child nodes represent characteristics and descriptors that +belong to that service. Each node must implement one of +**org.bluez.GattService(5)**, **org.bluez.GattCharacteristic(5)** or +**org.bluez.GattDescriptor(5)** interfaces, based on the attribute it +represents. Each node must also implement the standard D-Bus Properties +interface to expose their properties. These objects collectively represent a +GATT service definition. + +To make service registration simple, **bluetoothd(8)** requires that all objects +that belong to a GATT service be grouped under a D-Bus Object Manager that +solely manages the objects of that service. Hence, the standard +DBus.ObjectManager interface must be available on the root service path. An +example application hierarchy containing two separate GATT services may look +like this: + +.. code-block:: + + -> /com/example + | - org.freedesktop.DBus.ObjectManager + | + -> /com/example/service0 + | | - org.freedesktop.DBus.Properties + | | - org.bluez.GattService1 + | | + | -> /com/example/service0/char0 + | | - org.freedesktop.DBus.Properties + | | - org.bluez.GattCharacteristic1 + | | + | -> /com/example/service0/char1 + | | - org.freedesktop.DBus.Properties + | | - org.bluez.GattCharacteristic1 + | | + | -> /com/example/service0/char1/desc0 + | - org.freedesktop.DBus.Properties + | - org.bluez.GattDescriptor1 + | + -> /com/example/service1 + | - org.freedesktop.DBus.Properties + | - org.bluez.GattService1 + | + -> /com/example/service1/char0 + - org.freedesktop.DBus.Properties + - org.bluez.GattCharacteristic1 + +When a service is registered, **bluetoothd(8)** will automatically obtain +information about all objects using the service's Object Manager. Once a service +has been registered, the objects of a service should not be removed. If +**bluetoothd(8)** receives an InterfacesRemoved signal from a service's Object +Manager, it will immediately unregister the service. Similarly, if the +application disconnects from the bus, all of its registered services will be +automatically unregistered. InterfacesAdded signals will be ignored. + +Interface +========= + +:Service: org.bluez +:Interface: org.bluez.GattManager1 +:Object path: [variable prefix]/{hci0,hci1,...} + +Methods +------- + +void RegisterApplication(object application, dict options) +`````````````````````````````````````````````````````````` + + Registers a local GATT services hierarchy as described above + (GATT Server) and/or GATT profiles (GATT Client). + + The application object path together with the D-Bus system bus + connection ID define the identification of the application registering + a GATT based service (**org.bluez.GattService(5)**) and/or profile + (**org.bluez.GattProfile(5)**). + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.AlreadyExists: + +void UnregisterApplication(object application) +`````````````````````````````````````````````` + + This unregisters the services and/or profiles that has been previously + registered using **RegisterApplication()**. The object path parameter + must match the same value that has been used on registration. + + Possible errors: + + :org.bluez.Error.InvalidArguments: + :org.bluez.Error.DoesNotExist: diff --git a/doc/org.bluez.GattProfile.rst b/doc/org.bluez.GattProfile.rst new file mode 100644 index 000000000000..904301a9773b --- /dev/null +++ b/doc/org.bluez.GattProfile.rst @@ -0,0 +1,46 @@ +===================== +org.bluez.GattProfile +===================== + +----------------------------------------- +BlueZ D-Bus GattProfile API documentation +----------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +Local profile (GATT client) instance. By registering this type of object +an application effectively indicates support for a specific GATT profile +and requests automatic connections to be established to devices +supporting it. + +Interface +========= + +:Service: +:Interface: org.bluez.GattProfile1 +:Object path: + +Methods +------- + +void Release() +`````````````` + + This method gets called when the service daemon + unregisters the profile. The profile can use it to do cleanup tasks. + There is no need to unregister the profile, because when this method + gets called it has already been unregistered. + +Properties +---------- + +array{string} UUIDs [read-only] +``````````````````````````````` + + 128-bit GATT service UUIDs to auto connect. diff --git a/doc/org.bluez.GattService.rst b/doc/org.bluez.GattService.rst new file mode 100644 index 000000000000..4a1e81fc9e03 --- /dev/null +++ b/doc/org.bluez.GattService.rst @@ -0,0 +1,79 @@ +===================== +org.bluez.GattService +===================== + +------------------------------------------------- +BlueZ D-Bus GattService API documentation +------------------------------------------------- + +:Version: BlueZ +:Date: October 2023 +:Manual section: 5 +:Manual group: Linux System Administration + +Description +=========== + +GATT local/server and remote/client services share the same high-level D-Bus +API. + +Local/Server refers to GATT based service exported by a plugin or an external +application. + +Remote/Client refers to GATT services exported by the peer. + +Interface +========= + +Client +------ + +:Service: org.bluez +:Interface: org.bluez.GattService1 +:Object path: [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX + +Server +------ + +:Service: unique name +:Interface: org.bluez.GattService1 +:Object path: freely definable + +Properties +---------- + +string UUID [read-only] +``````````````````````` + + 128-bit service UUID. + +boolean Primary [read-only] +``````````````````````````` + + Indicates whether or not this GATT service is a primary service. If + false, the service is secondary. + +object Device [read-only, optional] +``````````````````````````````````` + + Object path of the Bluetooth device the service belongs to. Only + present on services from remote devices. + +array{object} Includes [read-only, optional] +```````````````````````````````````````````` + + Array of object paths representing the included services of this + service. + +uint16 Handle [read-only] (client only) +``````````````````````````````````````` + + Service handle. + +uint16 Handle [read-write, optional] (Server Only) +`````````````````````````````````````````````````` + + Service handle. When available in the server it would attempt to use to + allocate into the database which may fail, to auto allocate the value + 0x0000 shall be used which will cause the allocated handle to be set + once registered.