doc/settings-storage.txt

   1 BlueZ settings storage
   2 **********************
   3
   4 Purpose
   5 =======
   6
   7 The purpose of this document is to describe the directory structure of
   8 BlueZ settings storage. In effect, this document will serve as the primary,
   9 up to date source of BlueZ storage information.
  10
  11 It is intended as reference for developers. Direct access to the storage
  12 outside from bluetoothd is highly discouraged.
  13
  14 Adapter and remote device info are read form the storage during object
  15 initialization. Write to storage is performed immediately on every value
  16 change.
  17
  18 Default storage directory is /var/lib/bluetooth. This can be adjusted
  19 by the --localstatedir configure switch. Default is --localstatedir=/var.
  20
  21 All files are in ini-file format.
  22
  23
  24 Storage directory structure
  25 ===========================
  26
  27 There is one directory per adapter, named by its Bluetooth address, which
  28 contains:
  29  - a settings file for the local adapter
  30  - an attributes file containing attributes of supported LE services
  31  - a cache directory containing:
  32     - one file per device, named by remote device address, which contains
  33     device name
  34  - one directory per remote device, named by remote device address, which
  35    contains:
  36     - an info file
  37     - an attributes file containing attributes of remote LE services
  38     - a ccc file containing persistent Client Characteristic Configuration
  39       (CCC) descriptor information for GATT characteristics
  40
  41 So the directory structure is:
  42     /var/lib/bluetooth/<adapter address>/
  43         ./settings
  44         ./attributes
  45         ./cache/
  46             ./<remote device address>
  47             ./<remote device address>
  48             ...
  49         ./<remote device address>/
  50             ./info
  51             ./attributes
  52             ./ccc
  53         ./<remote device address>/
  54             ./info
  55             ./attributes
  56         ...
  57
  58
  59 Settings file format
  60 ====================
  61
  62 Settings file contains one [General] group with adapter info like:
  63
  64   Alias                 String          Friendly user provided name advertised
  65                                         for this adapter
  66
  67                                         This value overwrites the system
  68                                         name (pretty hostname)
  69
  70   Discoverable          Boolean         Discoverability of the adapter
  71
  72   PairableTimeout       Integer         How long to stay in pairable mode
  73                                         before going back to non-pairable.
  74                                         The value is in seconds.
  75                                         0 = disable timer, i.e. stay
  76                                         pairable forever
  77
  78   DiscoverableTimeout   Integer         How long to stay in discoverable mode
  79                                         before going back to non-discoverable.
  80                                         The value is in seconds.
  81                                         0 = disable timer, i.e. stay
  82                                         discoverable forever
  83
  84 #ifdef __TIZEN_PATCH__
  85   LocalIrk              String          Identity resolving key for local
  86                                         adapter. This key value is used to
  87                                         generate the RPA to suport privacy feature.
  88                                         If value is NULL, i.e IRK to be generated
  89                                         for this adapter.
  90 #endif
  91
  92 Sample:
  93   [General]
  94   Name=My PC
  95   Discoverable=false
  96   Pairable=true
  97   DiscoverableTimeout=0
  98 #ifdef __TIZEN_PATCH__
  99   LocalIrk=""
 100 #endif
 101
 102
 103 Attributes file format
 104 ======================
 105
 106 The attributes file lists all attributes supported by the local adapter or
 107 remote device.
 108
 109 Attributes are stored using their handle as group name (decimal format).
 110
 111 Each group contains:
 112
 113   UUID                  String          128-bit UUID of the attribute
 114
 115   Value                 String          Value of the attribute as hexadecimal encoded
 116                                         string
 117
 118   EndGroupHandle        Integer         End group handle in decimal format
 119
 120 Sample:
 121   [1]
 122   UUID=00002800-0000-1000-8000-00805f9b34fb
 123   Value=0018
 124
 125   [4]
 126   UUID=00002803-0000-1000-8000-00805f9b34fb
 127   Value=020600002A
 128
 129   [6]
 130   UUID=00002a00-0000-1000-8000-00805f9b34fb
 131   Value=4578616D706C6520446576696365
 132
 133
 134 CCC file format
 135 ======================
 136
 137 The ccc file stores the current CCC descriptor values for GATT characteristics
 138 which have notification/indication enabled by the remote device.
 139
 140 Information is stored using CCC attribute handle as group name (in decimal
 141 format).
 142
 143 Each group contains:
 144
 145   Value                 String          CCC descriptor value encoded in
 146                                         hexadecimal
 147
 148
 149 Cache directory file format
 150 ============================
 151
 152 Each file, named by remote device address, may includes multiple groups
 153 (General, ServiceRecords, Attributes).
 154
 155 In ServiceRecords, SDP records are stored using their handle as key
 156 (hexadecimal format).
 157
 158 In "Attributes" group GATT database is stored using attribute handle as key
 159 (hexadecimal format). Value associated with this handle is serialized form of
 160 all data required to re-create given attribute. ":" is used to separate fields.
 161
 162 [General] group contains:
 163
 164   Name          String          Remote device friendly name
 165
 166   ShortName     String          Remote device shortened name
 167
 168 [ServiceRecords] group contains
 169
 170   <0x...>       String          SDP record as hexadecimal encoded
 171                                 string
 172
 173 In [Attributes] group value always starts with attribute type, that determines
 174 how to interpret rest of value:
 175
 176   Primary service:
 177     2800:end_handle:uuid
 178
 179   Secondary service:
 180     2801:end_handle:uuid
 181
 182   Included service:
 183     2802:start_handle:end_handle:uuid
 184
 185   Characteristic:
 186     2803:value_handle:properties:uuid
 187
 188   Descriptor:
 189     uuid
 190
 191 Sample Attributes section:
 192   [Attributes]
 193   0001=2800:0005:1801
 194   0002=2803:0003:20:2a05
 195   0014=2800:001c:1800
 196   0015=2803:0016:02:2a00
 197   0017=2803:0018:02:2a01
 198   0019=2803:001a:02:2aa6
 199   0028=2800:ffff:0000180d-0000-1000-8000-00805f9b34fb
 200   0029=2803:002a:10:00002a37-0000-1000-8000-00805f9b34fb
 201   002b=2803:002c:02:00002a38-0000-1000-8000-00805f9b34fb
 202   002d=2803:002e:08:00002a39-0000-1000-8000-00805f9b34fb
 203
 204
 205 Info file format
 206 ================
 207
 208 Info file may includes multiple groups (General, Device ID, Link key and
 209 Long term key) related to a remote device.
 210
 211 [General] group contains:
 212
 213   Name                  String          Remote device friendly name
 214
 215   Alias                 String          Alias name
 216
 217   Class                 String          Device class in hexadecimal,
 218                                         i.e. 0x000000
 219
 220   Appearance            String          Device appearance in hexadecimal,
 221                                         i.e. 0x0000
 222
 223   SupportedTechnologies List of         List of technologies supported by
 224                         strings         device, separated by ";"
 225                                         Technologies can be BR/EDR or LE
 226
 227   AddressType           String          An address can be "static" or "public"
 228
 229   Trusted               Boolean         True if the remote device is trusted
 230
 231   Blocked               Boolean         True if the remote device is blocked
 232
 233   Services              List of         List of service UUIDs advertised by
 234                         strings         remote in 128-bits UUID format,
 235                                         separated by ";"
 236
 237
 238 [DeviceID] group contains:
 239
 240   Source                Integer         Assigner of Device ID
 241
 242   Vendor                Integer         Device vendor
 243
 244   Product               Integer         Device product
 245
 246   Version               Integer         Device version
 247
 248
 249 [LinkKey] group contains:
 250
 251   Key                   String          Key in hexadecimal format
 252
 253   Type                  Integer         Type of link key
 254
 255   PINLength             Integer         Length of PIN
 256
 257
 258 [LongTermKey] group contains:
 259
 260   Key                   String          Long term key in hexadecimal format
 261
 262   Authenticated         Boolean         True if remote device has been
 263                                         authenticated
 264
 265   EncSize               Integer         Encrypted size
 266
 267   EDiv                  Integer         Encrypted diversifier
 268
 269   Rand                  Integer         Randomizer
 270
 271
 272 [SlaveLongTermKey] group contains:
 273
 274   Same as the [LongTermKey] group, except for slave keys.
 275
 276
 277 [ConnectionParameters] group contains:
 278
 279   MinInterval           Integer         Minimum Connection Interval
 280
 281   MaxInterval           Integer         Maximum Connection Interval
 282
 283   Latency               Integer         Connection Latency
 284
 285   Timeout               Integer         Supervision Timeout
 286
 287
 288 [LocalSignatureKey] and [RemoteSignatureKey] groups contain:
 289
 290   Key                   String          Key in hexadecimal format
 291
 292   Counter               Integer         Signing counter
 293
 294   Authenticated         Boolean         True if the key is authenticated
 295
 296 #ifdef __TIZEN_PATCH__
 297 [IdentityResolvingKey] group contains:
 298
 299   Key                   String          Identity Resolving key in hexadecimal format
 300
 301   IdentityAddress       String          Identity Address of the device
 302
 303   IdentityAddressType   String          Type of Identity Address of the device
 304 #endif