Home | History | Annotate | Download | only in hardware
      1 /*
      2  * Copyright (C) 2012 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 #ifndef ANDROID_INCLUDE_BLUETOOTH_H
     18 #define ANDROID_INCLUDE_BLUETOOTH_H
     19 
     20 #include <stdint.h>
     21 #include <sys/cdefs.h>
     22 #include <sys/types.h>
     23 
     24 #include <hardware/hardware.h>
     25 
     26 __BEGIN_DECLS
     27 
     28 /**
     29  * The Bluetooth Hardware Module ID
     30  */
     31 
     32 #define BT_HARDWARE_MODULE_ID "bluetooth"
     33 #define BT_STACK_MODULE_ID "bluetooth"
     34 #define BT_STACK_TEST_MODULE_ID "bluetooth_test"
     35 
     36 
     37 /* Bluetooth profile interface IDs */
     38 
     39 #define BT_PROFILE_HANDSFREE_ID "handsfree"
     40 #define BT_PROFILE_ADVANCED_AUDIO_ID "a2dp"
     41 #define BT_PROFILE_HEALTH_ID "health"
     42 #define BT_PROFILE_SOCKETS_ID "socket"
     43 #define BT_PROFILE_HIDHOST_ID "hidhost"
     44 #define BT_PROFILE_PAN_ID "pan"
     45 
     46 #define BT_PROFILE_GATT_ID "gatt"
     47 #define BT_PROFILE_AV_RC_ID "avrcp"
     48 
     49 /** Bluetooth Address */
     50 typedef struct {
     51     uint8_t address[6];
     52 } __attribute__((packed))bt_bdaddr_t;
     53 
     54 /** Bluetooth Device Name */
     55 typedef struct {
     56     uint8_t name[249];
     57 } __attribute__((packed))bt_bdname_t;
     58 
     59 /** Bluetooth Adapter Visibility Modes*/
     60 typedef enum {
     61     BT_SCAN_MODE_NONE,
     62     BT_SCAN_MODE_CONNECTABLE,
     63     BT_SCAN_MODE_CONNECTABLE_DISCOVERABLE
     64 } bt_scan_mode_t;
     65 
     66 /** Bluetooth Adapter State */
     67 typedef enum {
     68     BT_STATE_OFF,
     69     BT_STATE_ON
     70 }   bt_state_t;
     71 
     72 /** Bluetooth Error Status */
     73 /** We need to build on this */
     74 
     75 typedef enum {
     76     BT_STATUS_SUCCESS,
     77     BT_STATUS_FAIL,
     78     BT_STATUS_NOT_READY,
     79     BT_STATUS_NOMEM,
     80     BT_STATUS_BUSY,
     81     BT_STATUS_DONE,        /* request already completed */
     82     BT_STATUS_UNSUPPORTED,
     83     BT_STATUS_PARM_INVALID,
     84     BT_STATUS_UNHANDLED,
     85     BT_STATUS_AUTH_FAILURE,
     86     BT_STATUS_RMT_DEV_DOWN
     87 
     88 } bt_status_t;
     89 
     90 /** Bluetooth PinKey Code */
     91 typedef struct {
     92     uint8_t pin[16];
     93 } __attribute__((packed))bt_pin_code_t;
     94 
     95 /** Bluetooth Adapter Discovery state */
     96 typedef enum {
     97     BT_DISCOVERY_STOPPED,
     98     BT_DISCOVERY_STARTED
     99 } bt_discovery_state_t;
    100 
    101 /** Bluetooth ACL connection state */
    102 typedef enum {
    103     BT_ACL_STATE_CONNECTED,
    104     BT_ACL_STATE_DISCONNECTED
    105 } bt_acl_state_t;
    106 
    107 /** Bluetooth 128-bit UUID */
    108 typedef struct {
    109    uint8_t uu[16];
    110 } bt_uuid_t;
    111 
    112 /** Bluetooth SDP service record */
    113 typedef struct
    114 {
    115    bt_uuid_t uuid;
    116    uint16_t channel;
    117    char name[256]; // what's the maximum length
    118 } bt_service_record_t;
    119 
    120 
    121 /** Bluetooth Remote Version info */
    122 typedef struct
    123 {
    124    int version;
    125    int sub_ver;
    126    int manufacturer;
    127 } bt_remote_version_t;
    128 
    129 /* Bluetooth Adapter and Remote Device property types */
    130 typedef enum {
    131     /* Properties common to both adapter and remote device */
    132     /**
    133      * Description - Bluetooth Device Name
    134      * Access mode - Adapter name can be GET/SET. Remote device can be GET
    135      * Data type   - bt_bdname_t
    136      */
    137     BT_PROPERTY_BDNAME = 0x1,
    138     /**
    139      * Description - Bluetooth Device Address
    140      * Access mode - Only GET.
    141      * Data type   - bt_bdaddr_t
    142      */
    143     BT_PROPERTY_BDADDR,
    144     /**
    145      * Description - Bluetooth Service 128-bit UUIDs
    146      * Access mode - Only GET.
    147      * Data type   - Array of bt_uuid_t (Array size inferred from property length).
    148      */
    149     BT_PROPERTY_UUIDS,
    150     /**
    151      * Description - Bluetooth Class of Device as found in Assigned Numbers
    152      * Access mode - Only GET.
    153      * Data type   - uint32_t.
    154      */
    155     BT_PROPERTY_CLASS_OF_DEVICE,
    156     /**
    157      * Description - Device Type - BREDR, BLE or DUAL Mode
    158      * Access mode - Only GET.
    159      * Data type   - bt_device_type_t
    160      */
    161     BT_PROPERTY_TYPE_OF_DEVICE,
    162     /**
    163      * Description - Bluetooth Service Record
    164      * Access mode - Only GET.
    165      * Data type   - bt_service_record_t
    166      */
    167     BT_PROPERTY_SERVICE_RECORD,
    168 
    169     /* Properties unique to adapter */
    170     /**
    171      * Description - Bluetooth Adapter scan mode
    172      * Access mode - GET and SET
    173      * Data type   - bt_scan_mode_t.
    174      */
    175     BT_PROPERTY_ADAPTER_SCAN_MODE,
    176     /**
    177      * Description - List of bonded devices
    178      * Access mode - Only GET.
    179      * Data type   - Array of bt_bdaddr_t of the bonded remote devices
    180      *               (Array size inferred from property length).
    181      */
    182     BT_PROPERTY_ADAPTER_BONDED_DEVICES,
    183     /**
    184      * Description - Bluetooth Adapter Discovery timeout (in seconds)
    185      * Access mode - GET and SET
    186      * Data type   - uint32_t
    187      */
    188     BT_PROPERTY_ADAPTER_DISCOVERY_TIMEOUT,
    189 
    190     /* Properties unique to remote device */
    191     /**
    192      * Description - User defined friendly name of the remote device
    193      * Access mode - GET and SET
    194      * Data type   - bt_bdname_t.
    195      */
    196     BT_PROPERTY_REMOTE_FRIENDLY_NAME,
    197     /**
    198      * Description - RSSI value of the inquired remote device
    199      * Access mode - Only GET.
    200      * Data type   - int32_t.
    201      */
    202     BT_PROPERTY_REMOTE_RSSI,
    203     /**
    204      * Description - Remote version info
    205      * Access mode - SET/GET.
    206      * Data type   - bt_remote_version_t.
    207      */
    208 
    209     BT_PROPERTY_REMOTE_VERSION_INFO,
    210 
    211     BT_PROPERTY_REMOTE_DEVICE_TIMESTAMP = 0xFF,
    212 } bt_property_type_t;
    213 
    214 /** Bluetooth Adapter Property data structure */
    215 typedef struct
    216 {
    217     bt_property_type_t type;
    218     int len;
    219     void *val;
    220 } bt_property_t;
    221 
    222 /** Bluetooth Device Type */
    223 typedef enum {
    224     BT_DEVICE_DEVTYPE_BREDR = 0x1,
    225     BT_DEVICE_DEVTYPE_BLE,
    226     BT_DEVICE_DEVTYPE_DUAL
    227 } bt_device_type_t;
    228 /** Bluetooth Bond state */
    229 typedef enum {
    230     BT_BOND_STATE_NONE,
    231     BT_BOND_STATE_BONDING,
    232     BT_BOND_STATE_BONDED
    233 } bt_bond_state_t;
    234 
    235 /** Bluetooth SSP Bonding Variant */
    236 typedef enum {
    237     BT_SSP_VARIANT_PASSKEY_CONFIRMATION,
    238     BT_SSP_VARIANT_PASSKEY_ENTRY,
    239     BT_SSP_VARIANT_CONSENT,
    240     BT_SSP_VARIANT_PASSKEY_NOTIFICATION
    241 } bt_ssp_variant_t;
    242 
    243 #define BT_MAX_NUM_UUIDS 32
    244 
    245 /** Bluetooth Interface callbacks */
    246 
    247 /** Bluetooth Enable/Disable Callback. */
    248 typedef void (*adapter_state_changed_callback)(bt_state_t state);
    249 
    250 /** GET/SET Adapter Properties callback */
    251 /* TODO: For the GET/SET property APIs/callbacks, we may need a session
    252  * identifier to associate the call with the callback. This would be needed
    253  * whenever more than one simultaneous instance of the same adapter_type
    254  * is get/set.
    255  *
    256  * If this is going to be handled in the Java framework, then we do not need
    257  * to manage sessions here.
    258  */
    259 typedef void (*adapter_properties_callback)(bt_status_t status,
    260                                                int num_properties,
    261                                                bt_property_t *properties);
    262 
    263 /** GET/SET Remote Device Properties callback */
    264 /** TODO: For remote device properties, do not see a need to get/set
    265  * multiple properties - num_properties shall be 1
    266  */
    267 typedef void (*remote_device_properties_callback)(bt_status_t status,
    268                                                        bt_bdaddr_t *bd_addr,
    269                                                        int num_properties,
    270                                                        bt_property_t *properties);
    271 
    272 /** New device discovered callback */
    273 /** If EIR data is not present, then BD_NAME and RSSI shall be NULL and -1
    274  * respectively */
    275 typedef void (*device_found_callback)(int num_properties,
    276                                          bt_property_t *properties);
    277 
    278 /** Discovery state changed callback */
    279 typedef void (*discovery_state_changed_callback)(bt_discovery_state_t state);
    280 
    281 /** Bluetooth Legacy PinKey Request callback */
    282 typedef void (*pin_request_callback)(bt_bdaddr_t *remote_bd_addr,
    283                                         bt_bdname_t *bd_name, uint32_t cod);
    284 
    285 /** Bluetooth SSP Request callback - Just Works & Numeric Comparison*/
    286 /** pass_key - Shall be 0 for BT_SSP_PAIRING_VARIANT_CONSENT &
    287  *  BT_SSP_PAIRING_PASSKEY_ENTRY */
    288 /* TODO: Passkey request callback shall not be needed for devices with display
    289  * capability. We still need support this in the stack for completeness */
    290 typedef void (*ssp_request_callback)(bt_bdaddr_t *remote_bd_addr,
    291                                         bt_bdname_t *bd_name,
    292                                         uint32_t cod,
    293                                         bt_ssp_variant_t pairing_variant,
    294                                      uint32_t pass_key);
    295 
    296 /** Bluetooth Bond state changed callback */
    297 /* Invoked in response to create_bond, cancel_bond or remove_bond */
    298 typedef void (*bond_state_changed_callback)(bt_status_t status,
    299                                                bt_bdaddr_t *remote_bd_addr,
    300                                                bt_bond_state_t state);
    301 
    302 /** Bluetooth ACL connection state changed callback */
    303 typedef void (*acl_state_changed_callback)(bt_status_t status, bt_bdaddr_t *remote_bd_addr,
    304                                             bt_acl_state_t state);
    305 
    306 typedef enum {
    307     ASSOCIATE_JVM,
    308     DISASSOCIATE_JVM
    309 } bt_cb_thread_evt;
    310 
    311 /** Thread Associate/Disassociate JVM Callback */
    312 /* Callback that is invoked by the callback thread to allow upper layer to attach/detach to/from
    313  * the JVM */
    314 typedef void (*callback_thread_event)(bt_cb_thread_evt evt);
    315 
    316 /** Bluetooth Test Mode Callback */
    317 /* Receive any HCI event from controller. Must be in DUT Mode for this callback to be received */
    318 typedef void (*dut_mode_recv_callback)(uint16_t opcode, uint8_t *buf, uint8_t len);
    319 
    320 /* LE Test mode callbacks
    321 * This callback shall be invoked whenever the le_tx_test, le_rx_test or le_test_end is invoked
    322 * The num_packets is valid only for le_test_end command */
    323 typedef void (*le_test_mode_callback)(bt_status_t status, uint16_t num_packets);
    324 /** TODO: Add callbacks for Link Up/Down and other generic
    325   *  notifications/callbacks */
    326 
    327 /** Bluetooth DM callback structure. */
    328 typedef struct {
    329     /** set to sizeof(bt_callbacks_t) */
    330     size_t size;
    331     adapter_state_changed_callback adapter_state_changed_cb;
    332     adapter_properties_callback adapter_properties_cb;
    333     remote_device_properties_callback remote_device_properties_cb;
    334     device_found_callback device_found_cb;
    335     discovery_state_changed_callback discovery_state_changed_cb;
    336     pin_request_callback pin_request_cb;
    337     ssp_request_callback ssp_request_cb;
    338     bond_state_changed_callback bond_state_changed_cb;
    339     acl_state_changed_callback acl_state_changed_cb;
    340     callback_thread_event thread_evt_cb;
    341     dut_mode_recv_callback dut_mode_recv_cb;
    342     le_test_mode_callback le_test_mode_cb;
    343 } bt_callbacks_t;
    344 
    345 /** NOTE: By default, no profiles are initialized at the time of init/enable.
    346  *  Whenever the application invokes the 'init' API of a profile, then one of
    347  *  the following shall occur:
    348  *
    349  *    1.) If Bluetooth is not enabled, then the Bluetooth core shall mark the
    350  *        profile as enabled. Subsequently, when the application invokes the
    351  *        Bluetooth 'enable', as part of the enable sequence the profile that were
    352  *        marked shall be enabled by calling appropriate stack APIs. The
    353  *        'adapter_properties_cb' shall return the list of UUIDs of the
    354  *        enabled profiles.
    355  *
    356  *    2.) If Bluetooth is enabled, then the Bluetooth core shall invoke the stack
    357  *        profile API to initialize the profile and trigger a
    358  *        'adapter_properties_cb' with the current list of UUIDs including the
    359  *        newly added profile's UUID.
    360  *
    361  *   The reverse shall occur whenever the profile 'cleanup' APIs are invoked
    362  */
    363 
    364 /** Represents the standard Bluetooth DM interface. */
    365 typedef struct {
    366     /** set to sizeof(bt_interface_t) */
    367     size_t size;
    368     /**
    369      * Opens the interface and provides the callback routines
    370      * to the implemenation of this interface.
    371      */
    372     int (*init)(bt_callbacks_t* callbacks );
    373 
    374     /** Enable Bluetooth. */
    375     int (*enable)(void);
    376 
    377     /** Disable Bluetooth. */
    378     int (*disable)(void);
    379 
    380     /** Closes the interface. */
    381     void (*cleanup)(void);
    382 
    383     /** Get all Bluetooth Adapter properties at init */
    384     int (*get_adapter_properties)(void);
    385 
    386     /** Get Bluetooth Adapter property of 'type' */
    387     int (*get_adapter_property)(bt_property_type_t type);
    388 
    389     /** Set Bluetooth Adapter property of 'type' */
    390     /* Based on the type, val shall be one of
    391      * bt_bdaddr_t or bt_bdname_t or bt_scanmode_t etc
    392      */
    393     int (*set_adapter_property)(const bt_property_t *property);
    394 
    395     /** Get all Remote Device properties */
    396     int (*get_remote_device_properties)(bt_bdaddr_t *remote_addr);
    397 
    398     /** Get Remote Device property of 'type' */
    399     int (*get_remote_device_property)(bt_bdaddr_t *remote_addr,
    400                                       bt_property_type_t type);
    401 
    402     /** Set Remote Device property of 'type' */
    403     int (*set_remote_device_property)(bt_bdaddr_t *remote_addr,
    404                                       const bt_property_t *property);
    405 
    406     /** Get Remote Device's service record  for the given UUID */
    407     int (*get_remote_service_record)(bt_bdaddr_t *remote_addr,
    408                                      bt_uuid_t *uuid);
    409 
    410     /** Start SDP to get remote services */
    411     int (*get_remote_services)(bt_bdaddr_t *remote_addr);
    412 
    413     /** Start Discovery */
    414     int (*start_discovery)(void);
    415 
    416     /** Cancel Discovery */
    417     int (*cancel_discovery)(void);
    418 
    419     /** Create Bluetooth Bonding */
    420     int (*create_bond)(const bt_bdaddr_t *bd_addr);
    421 
    422     /** Remove Bond */
    423     int (*remove_bond)(const bt_bdaddr_t *bd_addr);
    424 
    425     /** Cancel Bond */
    426     int (*cancel_bond)(const bt_bdaddr_t *bd_addr);
    427 
    428     /** BT Legacy PinKey Reply */
    429     /** If accept==FALSE, then pin_len and pin_code shall be 0x0 */
    430     int (*pin_reply)(const bt_bdaddr_t *bd_addr, uint8_t accept,
    431                      uint8_t pin_len, bt_pin_code_t *pin_code);
    432 
    433     /** BT SSP Reply - Just Works, Numeric Comparison and Passkey
    434      * passkey shall be zero for BT_SSP_VARIANT_PASSKEY_COMPARISON &
    435      * BT_SSP_VARIANT_CONSENT
    436      * For BT_SSP_VARIANT_PASSKEY_ENTRY, if accept==FALSE, then passkey
    437      * shall be zero */
    438     int (*ssp_reply)(const bt_bdaddr_t *bd_addr, bt_ssp_variant_t variant,
    439                      uint8_t accept, uint32_t passkey);
    440 
    441     /** Get Bluetooth profile interface */
    442     const void* (*get_profile_interface) (const char *profile_id);
    443 
    444     /** Bluetooth Test Mode APIs - Bluetooth must be enabled for these APIs */
    445     /* Configure DUT Mode - Use this mode to enter/exit DUT mode */
    446     int (*dut_mode_configure)(uint8_t enable);
    447 
    448     /* Send any test HCI (vendor-specific) command to the controller. Must be in DUT Mode */
    449     int (*dut_mode_send)(uint16_t opcode, uint8_t *buf, uint8_t len);
    450     /** BLE Test Mode APIs */
    451     /* opcode MUST be one of: LE_Receiver_Test, LE_Transmitter_Test, LE_Test_End */
    452     int (*le_test_mode)(uint16_t opcode, uint8_t *buf, uint8_t len);
    453 
    454 } bt_interface_t;
    455 
    456 /** TODO: Need to add APIs for Service Discovery, Service authorization and
    457   *       connection management. Also need to add APIs for configuring
    458   *       properties of remote bonded devices such as name, UUID etc. */
    459 
    460 typedef struct {
    461     struct hw_device_t common;
    462     const bt_interface_t* (*get_bluetooth_interface)();
    463 } bluetooth_device_t;
    464 
    465 typedef bluetooth_device_t bluetooth_module_t;
    466 __END_DECLS
    467 
    468 #endif /* ANDROID_INCLUDE_BLUETOOTH_H */
    469