@@ -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
deleted file mode 100644
@@ -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
new file mode 100644
@@ -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.
new file mode 100644
@@ -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.
new file mode 100644
@@ -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:
new file mode 100644
@@ -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.
new file mode 100644
@@ -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.
From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com> 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