hci.h

00001 /*
00002  * Copyright (C) 2009-2012 by Matthias Ringwald
00003  *
00004  * Redistribution and use in source and binary forms, with or without
00005  * modification, are permitted provided that the following conditions
00006  * are met:
00007  *
00008  * 1. Redistributions of source code must retain the above copyright
00009  *    notice, this list of conditions and the following disclaimer.
00010  * 2. Redistributions in binary form must reproduce the above copyright
00011  *    notice, this list of conditions and the following disclaimer in the
00012  *    documentation and/or other materials provided with the distribution.
00013  * 3. Neither the name of the copyright holders nor the names of
00014  *    contributors may be used to endorse or promote products derived
00015  *    from this software without specific prior written permission.
00016  * 4. Any redistribution, use, or modification is done solely for
00017  *    personal benefit and not for any commercial purpose or for
00018  *    monetary gain.
00019  *
00020  * THIS SOFTWARE IS PROVIDED BY MATTHIAS RINGWALD AND CONTRIBUTORS
00021  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00022  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00023  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MATTHIAS
00024  * RINGWALD OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00025  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00026  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
00027  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
00028  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00029  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
00030  * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00031  * SUCH DAMAGE.
00032  *
00033  * Please inquire about commercial licensing options at btstack@ringwald.ch
00034  *
00035  */
00036 
00037 /*
00038  *  hci.h
00039  *
00040  *  Created by Matthias Ringwald on 4/29/09.
00041  *
00042  */
00043 
00044 #pragma once
00045 
00046 #include "config.h"
00047 
00048 #include <btstack/hci_cmds.h>
00049 #include <btstack/utils.h>
00050 #include "hci_transport.h"
00051 #include "bt_control.h"
00052 #include "remote_device_db.h"
00053 
00054 #include <stdint.h>
00055 #include <stdlib.h>
00056 #include <stdarg.h>
00057 
00058 #if defined __cplusplus
00059 extern "C" {
00060 #endif
00061     
00062 // packet header sizes
00063 #define HCI_CMD_HEADER_SIZE          3
00064 #define HCI_ACL_HEADER_SIZE          4
00065 #define HCI_SCO_HEADER_SIZE          3
00066 #define HCI_EVENT_HEADER_SIZE        2
00067 
00068 // packet sizes (max payload)
00069 #define HCI_ACL_DM1_SIZE            17
00070 #define HCI_ACL_DH1_SIZE            27
00071 #define HCI_ACL_2DH1_SIZE           54
00072 #define HCI_ACL_3DH1_SIZE           83
00073 #define HCI_ACL_DM3_SIZE           121
00074 #define HCI_ACL_DH3_SIZE           183
00075 #define HCI_ACL_DM5_SIZE           224
00076 #define HCI_ACL_DH5_SIZE           339
00077 #define HCI_ACL_2DH3_SIZE          367
00078 #define HCI_ACL_3DH3_SIZE          552
00079 #define HCI_ACL_2DH5_SIZE          679
00080 #define HCI_ACL_3DH5_SIZE         1021
00081        
00082 #define HCI_EVENT_PAYLOAD_SIZE     255
00083 #define HCI_CMD_PAYLOAD_SIZE       255
00084     
00085 // packet buffer sizes
00086 // HCI_ACL_PAYLOAD_SIZE is configurable and defined in config.h
00087 #define HCI_EVENT_BUFFER_SIZE      (HCI_EVENT_HEADER_SIZE + HCI_EVENT_PAYLOAD_SIZE)
00088 #define HCI_CMD_BUFFER_SIZE        (HCI_CMD_HEADER_SIZE   + HCI_CMD_PAYLOAD_SIZE)
00089 #define HCI_ACL_BUFFER_SIZE        (HCI_ACL_HEADER_SIZE   + HCI_ACL_PAYLOAD_SIZE)
00090     
00091 // size of hci buffers, big enough for command, event, or acl packet without H4 packet type
00092 // @note cmd buffer is bigger than event buffer
00093 #if HCI_ACL_BUFFER_SIZE > HCI_CMD_BUFFER_SIZE
00094 #define HCI_PACKET_BUFFER_SIZE HCI_ACL_BUFFER_SIZE
00095 #else
00096 #define HCI_PACKET_BUFFER_SIZE HCI_CMD_BUFFER_SIZE
00097 #endif
00098     
00099 // OGFs
00100 #define OGF_LINK_CONTROL          0x01
00101 #define OGF_LINK_POLICY           0x02
00102 #define OGF_CONTROLLER_BASEBAND   0x03
00103 #define OGF_INFORMATIONAL_PARAMETERS 0x04
00104 #define OGF_LE_CONTROLLER 0x08
00105 #define OGF_BTSTACK 0x3d
00106 #define OGF_VENDOR  0x3f
00107 
00108 // cmds for BTstack 
00109 // get state: @returns HCI_STATE
00110 #define BTSTACK_GET_STATE                                  0x01
00111 
00112 // set power mode: @param HCI_POWER_MODE
00113 #define BTSTACK_SET_POWER_MODE                             0x02
00114 
00115 // set capture mode: @param on
00116 #define BTSTACK_SET_ACL_CAPTURE_MODE                       0x03
00117 
00118 // get BTstack version
00119 #define BTSTACK_GET_VERSION                                0x04
00120 
00121 // get system Bluetooth state
00122 #define BTSTACK_GET_SYSTEM_BLUETOOTH_ENABLED               0x05
00123 
00124 // set system Bluetooth state
00125 #define BTSTACK_SET_SYSTEM_BLUETOOTH_ENABLED               0x06
00126 
00127 // enable inquiry scan for this client
00128 #define BTSTACK_SET_DISCOVERABLE                           0x07
00129 
00130 // set global Bluetooth state
00131 #define BTSTACK_SET_BLUETOOTH_ENABLED                      0x08
00132 
00133 // create l2cap channel: @param bd_addr(48), psm (16)
00134 #define L2CAP_CREATE_CHANNEL                               0x20
00135 
00136 // disconnect l2cap disconnect, @param channel(16), reason(8)
00137 #define L2CAP_DISCONNECT                                   0x21
00138 
00139 // register l2cap service: @param psm(16), mtu (16)
00140 #define L2CAP_REGISTER_SERVICE                             0x22
00141 
00142 // unregister l2cap disconnect, @param psm(16)
00143 #define L2CAP_UNREGISTER_SERVICE                           0x23
00144 
00145 // accept connection @param bd_addr(48), dest cid (16)
00146 #define L2CAP_ACCEPT_CONNECTION                            0x24
00147 
00148 // decline l2cap disconnect,@param bd_addr(48), dest cid (16), reason(8)
00149 #define L2CAP_DECLINE_CONNECTION                           0x25
00150 
00151 // create l2cap channel: @param bd_addr(48), psm (16), mtu (16)
00152 #define L2CAP_CREATE_CHANNEL_MTU                           0x26
00153 
00154 // register SDP Service Record: service record (size)
00155 #define SDP_REGISTER_SERVICE_RECORD                        0x30
00156 
00157 // unregister SDP Service Record
00158 #define SDP_UNREGISTER_SERVICE_RECORD                      0x31
00159 
00160 // RFCOMM "HCI" Commands
00161 #define RFCOMM_CREATE_CHANNEL       0x40
00162 #define RFCOMM_DISCONNECT           0x41
00163 #define RFCOMM_REGISTER_SERVICE     0x42
00164 #define RFCOMM_UNREGISTER_SERVICE   0x43
00165 #define RFCOMM_ACCEPT_CONNECTION    0x44
00166 #define RFCOMM_DECLINE_CONNECTION   0x45
00167 #define RFCOMM_PERSISTENT_CHANNEL   0x46
00168 #define RFCOMM_CREATE_CHANNEL_WITH_CREDITS   0x47
00169 #define RFCOMM_REGISTER_SERVICE_WITH_CREDITS 0x48
00170 #define RFCOMM_GRANT_CREDITS                 0x49
00171     
00172 // 
00173 #define IS_COMMAND(packet, command) (READ_BT_16(packet,0) == command.opcode)
00174 
00175 // data: event(8)
00176 #define DAEMON_EVENT_CONNECTION_OPENED                     0x50
00177 
00178 // data: event(8)
00179 #define DAEMON_EVENT_CONNECTION_CLOSED                     0x51
00180 
00181 // data: event(8), nr_connections(8)
00182 #define DAEMON_NR_CONNECTIONS_CHANGED                      0x52
00183 
00184 // data: event(8)
00185 #define DAEMON_EVENT_NEW_RFCOMM_CREDITS                    0x53
00186 
00187 // data: event()
00188 #define DAEMON_EVENT_HCI_PACKET_SENT                       0x54
00189     
00190 /**
00191  * Connection State 
00192  */
00193 typedef enum {
00194     AUTH_FLAGS_NONE                = 0x00,
00195     RECV_LINK_KEY_REQUEST          = 0x01,
00196     HANDLE_LINK_KEY_REQUEST        = 0x02,
00197     SENT_LINK_KEY_REPLY            = 0x04,
00198     SENT_LINK_KEY_NEGATIVE_REQUEST = 0x08,
00199     RECV_LINK_KEY_NOTIFICATION     = 0x10,
00200     RECV_PIN_CODE_REQUEST          = 0x20,
00201     SENT_PIN_CODE_REPLY            = 0x40, 
00202     SENT_PIN_CODE_NEGATIVE_REPLY   = 0x80 
00203 } hci_authentication_flags_t;
00204 
00205 typedef enum {
00206     SENT_CREATE_CONNECTION = 1,
00207     RECEIVED_CONNECTION_REQUEST,
00208     ACCEPTED_CONNECTION_REQUEST,
00209     REJECTED_CONNECTION_REQUEST,
00210     OPEN,
00211     SENT_DISCONNECT
00212 } CONNECTION_STATE;
00213 
00214 typedef enum {
00215     BLUETOOTH_OFF = 1,
00216     BLUETOOTH_ON,
00217     BLUETOOTH_ACTIVE
00218 } BLUETOOTH_STATE;
00219 
00220 typedef struct {
00221     // linked list - assert: first field
00222     linked_item_t    item;
00223     
00224     // remote side
00225     bd_addr_t address;
00226     
00227     // module handle
00228     hci_con_handle_t con_handle;
00229 
00230     // state
00231     CONNECTION_STATE state;
00232     
00233     // errands
00234     hci_authentication_flags_t authentication_flags;
00235 
00236     timer_source_t timeout;
00237     
00238 #ifdef HAVE_TIME
00239     // timer
00240     struct timeval timestamp;
00241 #endif
00242 #ifdef HAVE_TICK
00243     uint32_t timestamp; // timeout in system ticks
00244 #endif
00245     
00246     // ACL packet recombination - ACL Header + ACL payload
00247     uint8_t  acl_recombination_buffer[4 + HCI_ACL_BUFFER_SIZE];
00248     uint16_t acl_recombination_pos;
00249     uint16_t acl_recombination_length;
00250     
00251     // number ACL packets sent to controller
00252     uint8_t num_acl_packets_sent;
00253     
00254 } hci_connection_t;
00255 
00256 /**
00257  * main data structure
00258  */
00259 typedef struct {
00260     // transport component with configuration
00261     hci_transport_t  * hci_transport;
00262     void             * config;
00263     
00264     // hardware power controller
00265     bt_control_t     * control;
00266     
00267     // list of existing baseband connections
00268     linked_list_t     connections;
00269 
00270     // single buffer for HCI Command assembly
00271     uint8_t          hci_packet_buffer[HCI_PACKET_BUFFER_SIZE]; // opcode (16), len(8)
00272     
00273     /* host to controller flow control */
00274     uint8_t  num_cmd_packets;
00275     // uint8_t  total_num_cmd_packets;
00276     uint8_t  total_num_acl_packets;
00277     uint16_t acl_data_packet_length;
00278 
00279     // usable packet types given acl_data_packet_length and HCI_ACL_BUFFER_SIZE
00280     uint16_t packet_types;
00281     
00282     /* callback to L2CAP layer */
00283     void (*packet_handler)(uint8_t packet_type, uint8_t *packet, uint16_t size);
00284 
00285     /* remote device db */
00286     remote_device_db_t const*remote_device_db;
00287     
00288     /* hci state machine */
00289     HCI_STATE state;
00290     uint8_t   substate;
00291     uint8_t   cmds_ready;
00292     
00293     uint8_t   discoverable;
00294     uint8_t   connectable;
00295     
00296     /* buffer for scan enable cmd - 0xff no change */
00297     uint8_t   new_scan_enable_value;
00298     
00299     // buffer for single connection decline
00300     uint8_t   decline_reason;
00301     bd_addr_t decline_addr;
00302     
00303 } hci_stack_t;
00304 
00305 // create and send hci command packets based on a template and a list of parameters
00306 uint16_t hci_create_cmd(uint8_t *hci_cmd_buffer, hci_cmd_t *cmd, ...);
00307 uint16_t hci_create_cmd_internal(uint8_t *hci_cmd_buffer, const hci_cmd_t *cmd, va_list argptr);
00308 
00309 // set up HCI
00310 void hci_init(hci_transport_t *transport, void *config, bt_control_t *control, remote_device_db_t const* remote_device_db);
00311 void hci_register_packet_handler(void (*handler)(uint8_t packet_type, uint8_t *packet, uint16_t size));
00312 void hci_close(void);
00313 
00314 // power and inquriy scan control
00315 int  hci_power_control(HCI_POWER_MODE mode);
00316 void hci_discoverable_control(uint8_t enable);
00317 void hci_connectable_control(uint8_t enable);
00318 
00319 /**
00320  * run the hci control loop once
00321  */
00322 void hci_run(void);
00323 
00324 // create and send hci command packets based on a template and a list of parameters
00325 int hci_send_cmd(const hci_cmd_t *cmd, ...);
00326 
00327 // send complete CMD packet
00328 int hci_send_cmd_packet(uint8_t *packet, int size);
00329 
00330 // send ACL packet
00331 int hci_send_acl_packet(uint8_t *packet, int size);
00332 
00333 // non-blocking UART driver needs
00334 int hci_can_send_packet_now(uint8_t packet_type);
00335     
00336 hci_connection_t * connection_for_handle(hci_con_handle_t con_handle);
00337 uint8_t  hci_number_outgoing_packets(hci_con_handle_t handle);
00338 uint8_t  hci_number_free_acl_slots(void);
00339 int      hci_authentication_active_for_handle(hci_con_handle_t handle);
00340 void     hci_drop_link_key_for_bd_addr(bd_addr_t *addr);
00341 uint16_t hci_max_acl_data_packet_length(void);
00342 uint16_t hci_usable_acl_packet_types(void);
00343 uint8_t* hci_get_outgoing_acl_packet_buffer(void);
00344 
00345 // 
00346 void hci_emit_state(void);
00347 void hci_emit_connection_complete(hci_connection_t *conn, uint8_t status);
00348 void hci_emit_l2cap_check_timeout(hci_connection_t *conn);
00349 void hci_emit_disconnection_complete(uint16_t handle, uint8_t reason);
00350 void hci_emit_nr_connections_changed(void);
00351 void hci_emit_hci_open_failed(void);
00352 void hci_emit_btstack_version(void);
00353 void hci_emit_system_bluetooth_enabled(uint8_t enabled);
00354 void hci_emit_remote_name_cached(bd_addr_t *addr, device_name_t *name);
00355 void hci_emit_discoverable_enabled(uint8_t enabled);
00356 
00357 #if defined __cplusplus
00358 }
00359 #endif