1 // Copyright 2014 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 // The <code>chrome.bluetoothLowEnergy</code> API is used to communicate with 6 // Bluetooth Smart (Low Energy) devices using the 7 // <a href="https://developer.bluetooth.org/TechnologyOverview/Pages/GATT.aspx"> 8 // Generic Attribute Profile (GATT)</a>. 9 namespace bluetoothLowEnergy { 10 // Values representing the possible properties of a characteristic. 11 enum CharacteristicProperty {broadcast, read, writeWithoutResponse, write, 12 notify, indicate, authenticatedSignedWrites, 13 extendedProperties, reliableWrite, 14 writableAuxiliaries}; 15 16 // Represents a peripheral's Bluetooth GATT Service, a collection of 17 // characteristics and relationships to other services that encapsulate 18 // the behavior of part of a device. 19 dictionary Service { 20 // The UUID of the service, e.g. 0000180d-0000-1000-8000-00805f9b34fb. 21 DOMString uuid; 22 23 // Indicates whether the type of this service is primary or secondary. 24 boolean isPrimary; 25 26 // Indicates whether this service represents a local service hosted by the 27 // application and available to other peripherals, or a remote service 28 // hosted and received from a remote peripheral. 29 [nodoc] boolean isLocal; 30 31 // Returns the identifier assigned to this service. Use the instance ID to 32 // distinguish between services from a peripheral with the same UUID and 33 // to make function calls that take in a service identifier. Present, if 34 // this instance represents a remote service. 35 DOMString? instanceId; 36 37 // The device address of the remote peripheral that the GATT service belongs 38 // to. Present, if this instance represents a remote service. 39 DOMString? deviceAddress; 40 }; 41 42 // Represents a GATT characteristic, which is a basic data element that 43 // provides further information about a peripheral's service. 44 dictionary Characteristic { 45 // The UUID of the characteristic, e.g. 46 // 00002a37-0000-1000-8000-00805f9b34fb. 47 DOMString uuid; 48 49 // Indicates whether this characteristic represents a local characteristic 50 // hosted by the application and available to other peripherals, or a remote 51 // characteristic hosted and received from a remote peripheral. 52 [nodoc] boolean isLocal; 53 54 // The GATT service this characteristic belongs to. 55 Service service; 56 57 // The properties of this characteristic. 58 CharacteristicProperty[] properties; 59 60 // Returns the identifier assigned to this characteristic. Use the instance 61 // ID to distinguish between characteristics from a peripheral with the same 62 // UUID and to make function calls that take in a characteristic identifier. 63 // Present, if this instance represents a remote characteristic. 64 DOMString? instanceId; 65 66 // The currently cached characteristic value. This value gets updated when 67 // the value of the characteristic is read or updated via a notification 68 // or indication. 69 ArrayBuffer? value; 70 }; 71 72 // Represents a GATT characteristic descriptor, which provides further 73 // information about a characteristic's value. 74 dictionary Descriptor { 75 // The UUID of the characteristic descriptor, e.g. 76 // 00002902-0000-1000-8000-00805f9b34fb. 77 DOMString uuid; 78 79 // Indicates whether this descriptor represents a local descriptor 80 // hosted by the application and available to other peripherals, or a remote 81 // descriptor hosted and received from a remote peripheral. 82 [nodoc] boolean isLocal; 83 84 // The GATT characteristic this descriptor belongs to. 85 Characteristic characteristic; 86 87 // Returns the identifier assigned to this descriptor. Use the instance ID 88 // to distinguish between descriptors from a peripheral with the same UUID 89 // and to make function calls that take in a descriptor identifier. Present, 90 // if this instance represents a remote characteristic. 91 DOMString? instanceId; 92 93 // The currently cached descriptor value. This value gets updated when 94 // the value of the descriptor is read. 95 ArrayBuffer? value; 96 }; 97 98 // The connection properties specified during a call to $(ref:connect). 99 dictionary ConnectProperties { 100 // Flag indicating whether a connection to the device is left open when the 101 // event page of the application is unloaded (see <a 102 // href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App 103 // Lifecycle</a>). The default value is <code>false.</code> 104 boolean persistent; 105 }; 106 107 // Optional characteristic notification session properties specified during a 108 // call to $(ref:startCharacteristicNotifications). 109 dictionary NotificationProperties { 110 // Flag indicating whether the app should receive notifications when the 111 // event page of the application is unloaded (see <a 112 // href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App 113 // Lifecycle</a>). The default value is <code>false</code>. 114 boolean persistent; 115 }; 116 117 callback CharacteristicCallback = void(Characteristic result); 118 callback CharacteristicsCallback = void(Characteristic[] result); 119 callback DescriptorCallback = void(Descriptor result); 120 callback DescriptorsCallback = void(Descriptor[] result); 121 callback ResultCallback = void(); 122 callback ServiceCallback = void(Service result); 123 callback ServicesCallback = void(Service[] result); 124 125 // These functions all report failures via chrome.runtime.lastError. 126 interface Functions { 127 // Establishes a connection between the application and the device with the 128 // given address. A device may be already connected and its GATT services 129 // available without calling <code>connect</code>, however, an app that 130 // wants to access GATT services of a device should call this function to 131 // make sure that a connection to the device is maintained. If the device 132 // is not connected, all GATT services of the device will be discovered 133 // after a successful call to <code>connect</code>. 134 // |deviceAddress| : The Bluetooth address of the remote device to which a 135 // GATT connection should be opened. 136 // |properties| : Connection properties (optional). 137 // |callback| : Called when the connect request has completed. 138 static void connect(DOMString deviceAddress, 139 optional ConnectProperties properties, 140 ResultCallback callback); 141 142 // Closes the app's connection to the device with the given address. Note 143 // that this will not always destroy the physical link itself, since there 144 // may be other apps with open connections. 145 // |deviceAddress| : The Bluetooth address of the remote device. 146 // |callback| : Called when the disconnect request has completed. 147 static void disconnect(DOMString deviceAddress, 148 optional ResultCallback callback); 149 150 // Get the GATT service with the given instance ID. 151 // |serviceId| : The instance ID of the requested GATT service. 152 // |callback| : Called with the requested Service object. 153 static void getService(DOMString serviceId, ServiceCallback callback); 154 155 // Get all the GATT services that were discovered on the remote device with 156 // the given device address. 157 // |deviceAddress| : The Bluetooth address of the remote device whose GATT 158 // services should be returned. 159 // |callback| : Called with the list of requested Service objects. 160 static void getServices(DOMString deviceAddress, ServicesCallback callback); 161 162 // Get the GATT characteristic with the given instance ID that belongs to 163 // the given GATT service, if the characteristic exists. 164 // |characteristicId| : The instance ID of the requested GATT 165 // characteristic. 166 // |callback| : Called with the requested Characteristic object. 167 static void getCharacteristic(DOMString characteristicId, 168 CharacteristicCallback callback); 169 170 // Get a list of all discovered GATT characteristics that belong to the 171 // given service. 172 // |serviceId| : The instance ID of the GATT service whose characteristics 173 // should be returned. 174 // |callback| : Called with the list of characteristics that belong to the 175 // given service. 176 static void getCharacteristics(DOMString serviceId, 177 CharacteristicsCallback callback); 178 179 // Get a list of GATT services that are included by the given service. 180 // |serviceId| : The instance ID of the GATT service whose included 181 // services should be returned. 182 // |callback| : Called with the list of GATT services included from the 183 // given service. 184 static void getIncludedServices(DOMString serviceId, 185 ServicesCallback callback); 186 187 // Get the GATT characteristic descriptor with the given instance ID. 188 // |descriptorId| : The instance ID of the requested GATT characteristic 189 // descriptor. 190 // |callback| : Called with the requested Descriptor object. 191 static void getDescriptor(DOMString descriptorId, 192 DescriptorCallback callback); 193 194 // Get a list of GATT characteristic descriptors that belong to the given 195 // characteristic. 196 // |characteristicId| : The instance ID of the GATT characteristic whose 197 // descriptors should be returned. 198 // |callback| : Called with the list of descriptors that belong to the given 199 // characteristic. 200 static void getDescriptors(DOMString characteristicId, 201 DescriptorsCallback callback); 202 203 // Retrieve the value of a specified characteristic from a remote 204 // peripheral. 205 // |characteristicId| : The instance ID of the GATT characteristic whose 206 // value should be read from the remote device. 207 // |callback| : Called with the Characteristic object whose value was 208 // requested. The <code>value</code> field of the returned Characteristic 209 // object contains the result of the read request. 210 static void readCharacteristicValue(DOMString characteristicId, 211 CharacteristicCallback callback); 212 213 // Write the value of a specified characteristic from a remote peripheral. 214 // |characteristicId| : The instance ID of the GATT characteristic whose 215 // value should be written to. 216 // |value| : The value that should be sent to the remote characteristic as 217 // part of the write request. 218 // |callback| : Called when the write request has completed. 219 static void writeCharacteristicValue(DOMString characteristicId, 220 ArrayBuffer value, 221 ResultCallback callback); 222 223 // Enable value notifications/indications from the specified characteristic. 224 // Once enabled, an application can listen to notifications using the 225 // $(ref:onCharacteristicValueChanged) event. 226 // |characteristicId| : The instance ID of the GATT characteristic that 227 // notifications should be enabled on. 228 // |properties| : Notification session properties (optional). 229 // |callback| : Called when the request has completed. 230 static void startCharacteristicNotifications( 231 DOMString characteristicId, 232 optional NotificationProperties properties, 233 ResultCallback callback); 234 235 // Disable value notifications/indications from the specified 236 // characteristic. After a successful call, the application will stop 237 // receiving notifications/indications from this characteristic. 238 // |characteristicId| : The instance ID of the GATT characteristic on which 239 // this app's notification session should be stopped. 240 // |callback| : Called when the request has completed (optional). 241 static void stopCharacteristicNotifications( 242 DOMString characteristicId, 243 optional ResultCallback callback); 244 245 // Retrieve the value of a specified characteristic descriptor from a remote 246 // peripheral. 247 // |descriptorId| : The instance ID of the GATT characteristic descriptor 248 // whose value should be read from the remote device. 249 // |callback| : Called with the Descriptor object whose value was requested. 250 // The <code>value</code> field of the returned Descriptor object contains 251 // the result of the read request. 252 static void readDescriptorValue(DOMString descriptorId, 253 DescriptorCallback callback); 254 255 // Write the value of a specified characteristic descriptor from a remote 256 // peripheral. 257 // |descriptorId| : The instance ID of the GATT characteristic descriptor 258 // whose value should be written to. 259 // |value| : The value that should be sent to the remote descriptor as part 260 // of the write request. 261 // |callback| : Called when the write request has completed. 262 static void writeDescriptorValue(DOMString descriptorId, 263 ArrayBuffer value, 264 ResultCallback callback); 265 }; 266 267 interface Events { 268 // Fired whan a new GATT service has been discovered on a remote device. 269 // |service| : The GATT service that was added. 270 static void onServiceAdded(Service service); 271 272 // Fired when the state of a remote GATT service changes. This involves any 273 // characteristics and/or descriptors that get added or removed from the 274 // service, as well as "ServiceChanged" notifications from the remote 275 // device. 276 // |service| : The GATT service whose state has changed. 277 static void onServiceChanged(Service service); 278 279 // Fired when a GATT service that was previously discovered on a remote 280 // device has been removed. 281 // |service| : The GATT service that was removed. 282 static void onServiceRemoved(Service service); 283 284 // Fired when the value of a remote GATT characteristic changes, either as 285 // a result of a read request, or a value change notification/indication 286 // This event will only be sent if the app has enabled notifications by 287 // calling $(ref:startCharacteristicNotifications). 288 // |characteristic| : The GATT characteristic whose value has changed. 289 static void onCharacteristicValueChanged(Characteristic characteristic); 290 291 // Fired when the value of a remote GATT characteristic descriptor changes, 292 // usually as a result of a read request. This event exists 293 // mostly for convenience and will always be sent after a successful 294 // call to $(ref:readDescriptorValue). 295 // |descriptor| : The GATT characteristic descriptor whose value has 296 // changed. 297 static void onDescriptorValueChanged(Descriptor descriptor); 298 }; 299 }; 300
