wearable/doc/attribute-api.txt

   1 BlueZ D-Bus Attribute API description
   2 *************************************
   3
   4 Copyright (C) 2004-2010  Marcel Holtmann <marcel@holtmann.org>
   5
   6 Service details
   7 ---------------
   8
   9 One service object path for every remote SDP record or service in the
  10 attribute database. One service object path for every local SDP record
  11 or service from attribute database.
  12
  13 Local services are children of the adapter object path. Remote services
  14 are children of the remote device object path. This doesn't solve the
  15 problem where local attributes can have different instances based on
  16 the remote device.
  17
  18 In general the idea is to also represent SDP records as services so that
  19 new style application can just use the service interfaces to retrieve the
  20 needed information. That way the usage of SDP and GATT would be mostly
  21 fully transparent and a differentiation becomes unimportant in the future.
  22
  23 A service consists of some generic service information and a set of
  24 characteristics. All characteristic are presented as object path as well.
  25
  26
  27 Local Service hierarchy
  28 =======================
  29
  30 Service         org.bluez
  31 Interface       org.bluez.Service
  32                 org.bluez.Characteristic
  33 Object path     [prefix]/{hci0}/{service0, service1, ...}
  34
  35 Methods
  36
  37 Properties
  38
  39
  40 Device Service hierarchy
  41 ========================
  42
  43 Service         org.bluez
  44 Interface       org.bluez.Characteristic
  45 Object path     [prefix]/{hci0}/{device0}/{service0, service1, ...}
  46                 [prefix]/{hci0}/{device1}/{service0, service1, ...}
  47
  48 Methods         dict GetProperties()
  49
  50                         Returns all properties for the interface. See the
  51                         Properties section for the available properties.
  52
  53                 array{object} DiscoverCharacteristics()
  54
  55                         Discover all characteristics that belongs in this service.
  56                         When it returns all the characteristics paths will be
  57                         already registered. It will return the characteristics paths
  58                         as soon as they are discovered. After that it will try to
  59                         read all values.
  60
  61                 RegisterCharacteristicsWatcher(object agent)
  62
  63                         Register a watcher to monitor characteristic changes.
  64
  65                         A watcher will be registered for this service and will
  66                         notify about any changed characteristics in the service.
  67                         This also notifies about any included characteristics.
  68
  69                 UnregisterCharacteristicsWatcher(object agent)
  70
  71                         Unregister a watcher.
  72
  73 Properties      string Name (mandatory) [readonly]
  74
  75                         General name of service
  76
  77                 string Description (optional) [readonly]
  78
  79                         Description of service
  80
  81                 string UUID (mandatory) [readonly]
  82
  83                         UUID of service. Service class value for SDP and GATT
  84                         UUID for attribute based services.
  85
  86                 array{object} Characteristics [readonly]
  87
  88                         This list contains the characteristics owned by this
  89                         specific service and other characteristics from service
  90                         includes. That way no complicated service includes array
  91                         is needed.
  92
  93
  94 Device Characteristic hierarchy
  95 ===============================
  96
  97 Service         org.bluez
  98 Interface       org.bluez.Characteristic
  99 Object path     [prefix]/{hci0}/{device0}/{service0}/{characteristic0,...}
 100                 [prefix]/{hci0}/{device0}/{service1}/{characteristic0,...}
 101
 102 Methods         dict GetProperties()
 103
 104                         Returns all properties for the characteristic. See the
 105                         properties section for available properties.
 106
 107                 void SetProperty(string name, variant value)
 108
 109                         Changes the value of the specified property. Only
 110                         read-write properties can be changed. On success
 111                         this will emit a PropertyChanged signal.
 112
 113                         Possible Errors: org.bluez.Error.InvalidArguments
 114
 115 Properties      string UUID [readonly]
 116
 117                         UUID128 of this characteristic.
 118
 119                 string Name [readonly]
 120
 121                         Optional field containing a friendly name for the
 122                         Characteristic UUID.
 123
 124                 string Description [readonly]
 125
 126                         Textual optional characteristic descriptor describing
 127                         the Characteristic Value.
 128
 129                 struct Format [readonly]
 130
 131                         Optional Characteristic descriptor which defines the
 132                         format of the Characteristic Value. For numeric
 133                         values, the actual value can be value * 10^Exponent.
 134                         NameSpace and Description are defined on the Assigned
 135                         Number Specification.
 136
 137                           uint8  | Format: format of the value
 138                           uint8  | Exponent: Field to determine how the value is
 139                                  | further formatted.
 140                           uint16 | Unit: unit of the characteristic
 141                           uint8  | NameSpace: Name space of description.
 142                           uint16 | Description: Description of the characteristic defined
 143                                  | in a high layer profile.
 144
 145                 array{byte} Value [readwrite]
 146
 147                         Raw value of the Characteristic Value attribute.
 148
 149                 string Representation (of the binary Value) [readonly]
 150
 151                         Friendly representation of the Characteristic Value
 152                         based on the format attribute.
 153
 154
 155 Characteristic Watcher hierarchy
 156 ===============================
 157
 158 Service         unique name
 159 Interface       org.bluez.Watcher
 160 Object path     freely definable
 161
 162 Methods         void ValueChanged(object characteristic, array{byte})
 163
 164                         New raw value of the Characteristic Value attribute.