From: Luiz Augusto von Dentz <[email protected]>
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.
--
2.41.0
From: Luiz Augusto von Dentz <[email protected]>
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:
+
--
2.41.0
From: Luiz Augusto von Dentz <[email protected]>
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 UUID>":
+
+ 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
--
2.41.0
From: Luiz Augusto von Dentz <[email protected]>
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:
--
2.41.0
From: Luiz Augusto von Dentz <[email protected]>
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.
--
2.41.0
From: Luiz Augusto von Dentz <[email protected]>
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:
- <type> <byte array>
- ...
-
- Example:
- <Transport Discovery> <Organization Flags...>
- 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:
+
+ :<type>:
+
+ <byte array>
+
+ Example:
+ <Transport Discovery> <Organization Flags...>
+ 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.
--
2.41.0
From: Luiz Augusto von Dentz <[email protected]>
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 <application dependent>
-Interface org.bluez.GattProfile1
-Object path <application dependent>
-
-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: <application dependent>
+:Interface: org.bluez.GattProfile1
+:Object path: <application dependent>
+
+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.
--
2.41.0
From: Luiz Augusto von Dentz <[email protected]>
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:
- <type> <byte array>
- ...
-
- Example:
- <Transport Discovery> <Organization Flags...>
- 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:
+
+ :<type>:
+
+ <byte array>
+
+ Example:
+
+ <Transport Discovery> <Organization Flags...>
+ 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.
--
2.41.0
This is automated email and please do not reply to this email!
Dear submitter,
Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=790826
---Test result---
Test Summary:
CheckPatch PASS 2.76 seconds
GitLint PASS 1.92 seconds
BuildEll PASS 32.37 seconds
BluezMake PASS 969.11 seconds
MakeCheck PASS 13.50 seconds
MakeDistcheck FAIL 12.19 seconds
CheckValgrind PASS 300.67 seconds
CheckSmatch PASS 398.19 seconds
bluezmakeextell PASS 126.83 seconds
IncrementalBuild PASS 6324.90 seconds
ScanBuild PASS 1225.83 seconds
Details
##############################
Test: MakeDistcheck - FAIL
Desc: Run Bluez Make Distcheck
Output:
make[2]: *** No rule to make target 'doc/org.bluez.AagentManager.5', needed by 'distdir-am'. Stop.
make[2]: *** Waiting for unfinished jobs....
make[1]: *** [Makefile:11890: distdir] Error 2
make: *** [Makefile:11966: dist] Error 2
---
Regards,
Linux Bluetooth