Return-Path: From: Claudio Takahasi To: linux-bluetooth@vger.kernel.org Cc: claudio.takahasi@openbossa.org Subject: [PATCH BlueZ v7 01/11] doc: Add experimental GATT API Date: Wed, 19 Feb 2014 15:51:23 -0300 Message-Id: <1392835893-6723-2-git-send-email-claudio.takahasi@openbossa.org> In-Reply-To: <1392835893-6723-1-git-send-email-claudio.takahasi@openbossa.org> References: <1B88D85B-35F3-47BB-ACAD-872E6C4F0A79@holtmann.org> <1392835893-6723-1-git-send-email-claudio.takahasi@openbossa.org> Sender: linux-bluetooth-owner@vger.kernel.org List-ID: This patch proposes an unified GATT API for local and remote services. --- doc/gatt-api.txt | 142 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 doc/gatt-api.txt diff --git a/doc/gatt-api.txt b/doc/gatt-api.txt new file mode 100644 index 0000000..0f6b084 --- /dev/null +++ b/doc/gatt-api.txt @@ -0,0 +1,142 @@ +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. + +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 [Experimental] +Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX + +Properties string UUID [read-only] + + 128-bit service UUID. + + array{object} Includes [read-only]: Not implemented + + Array of object paths representing the included + services of this service. + + +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 [Experimental] +Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY + +Properties string UUID [read-only] + + 128-bit characteristic UUID. + + object Service [read-only] + + Object path of the GATT service the characteristc + belongs to. + + array{byte} Value [read-write] + + Value read from the remote Bluetooth device or from + the external application implementing GATT services. + + array{string} Flags [read-only, optional] + + Defines how the characteristic value can be used. See + Core spec page 1898, "Table 3.5: Characteristic + Properties bit field" and page 1900, "Table 3.8: + Characteristic Extended Properties bit field". Allowed + values: "broadcast", "read", "write-without-response", + "write", "notify", "indicate", + "authenticated-signed-writes", "reliable-write", and + "writable-auxiliaries". + + +Characteristic Descriptors hierarchy +==================================== + +Local or remote GATT characteristic descriptors hierarchy. + +Service org.bluez +Interface org.bluez.GattDescriptor1 [Experimental] +Object path [variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ + +Properties string UUID [read-only] + + 128-bit descriptor UUID. + + object Characteristic [read-only] + + Object path of the GATT characteristc the descriptor + belongs to. + + array{byte} Value [read-write] + + Raw characteristic descriptor value read from the + remote Bluetooth device or from the external + application implementing GATT services. + + string Permissions [read-only]: To be defined + + Defines read/write authentication and authorization + requirements. + +Service Manager hierarchy +============================= + +Service Manager allows external applications to register GATT based +services. Services must follow the API for Service and Characteristic +described above. + +Local GATT services, characteristics and characteristic descriptors are +discovered automatically using the D-Bus Object Manager interface. + +Service org.bluez +Interface org.bluez.GattManager1 [Experimental] +Object path /org/bluez + +Methods RegisterService(object service, dict options) + + Registers remote application service exported under + interface GattService1. Characteristic objects must + be hierarchical to their service and must use the + interface GattCharacteristic1. D-Bus Object Manager + is used to fetch the exported objects. + + "service" object path together with the D-Bus system + bus connection ID define the identification of the + application registering a GATT based service. + + Possible errors: org.bluez.Error.InvalidArguments + org.bluez.Error.AlreadyExists + + UnregisterService(object service) + + This unregisters the service 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 -- 1.8.3.1