btnut/btnode/include/bt/bt_hci_api.h File Reference

Detailed Description

This headerfile describes the API of the HCI cmd and some get functions to retrieve connection information.

Author:
Mathias Payer <payerm@stud.ethz.ch>

Martin Hinz <btnode@hinz.ch>

Matthias Ringwald <mringwal@inf.ethz.ch>

So far only the most important calls are listed.

#include <bt/bt_defs.h>
#include <bt/bt_hci_defs.h>
#include <bt/bt_hci_transport_uart.h>

Data Structures

struct  bt_hci_cmd_response
struct  bt_hci_inquiry_result
struct  bt_hci_local_version_result
#define BT_ACL_PKT_MAX_PAYLOAD(btstack)   (btstack->host_acl_len)
#define BT_ERR_ACL_PLOAD_OVFLW   -0x010b
#define BT_ERR_ACL_WRITE   -0x010c
#define BT_ERR_BT_MODULE   -0x0100
#define BT_ERR_CON_BROKEN   -0x010a
#define BT_ERR_CON_EXIST   -0x0107
#define BT_ERR_CON_PEND_ACTIVE   -0x0108
#define BT_ERR_CON_PEND_PASSIVE   -0x0109
#define BT_ERR_MAX_CON   -0x0104
#define BT_ERR_MAX_WAITCMD   -0x0106
#define BT_ERR_NO_CON   -0x0103
#define BT_ERR_ROLE_CHANGE_NOT_ALLOWED   -0x21
#define BT_ERR_RST_RUN   -0x0105
#define BT_ERR_UART_COM   -0x0101
#define BT_ERR_UNKNOWN_HCI_COMMAND   -0x01
#define BT_ERR_USB_COM   -0x0102
#define BT_HCI_CON_HANDLE_OWN   0
#define BT_HCI_DISCON_ABOUT_TO_POWER_OFF   0x15
#define BT_HCI_DISCON_BY_LOCAL_DEVICE   0x16
#define BT_HCI_DISCON_LINK_LOST   0x08
#define BT_HCI_DISCON_LOW_RESSOURCE   0x14
#define BT_HCI_DISCON_OTHER_DEVICE   0x13
typedef bt_hci_con_handle_t bt_hci_con_handle_array [BT_HCI_MAX_NUM_CON]
long bt_hci_get_con_handle (struct btstack *stack, bt_addr_t addr)
long bt_hci_get_con_handles (struct btstack *stack, bt_hci_con_handle_array con_handles)
long bt_hci_get_local_bt_addr (struct btstack *stack, bt_addr_t addr)
long bt_hci_get_remote_bt_addr (struct btstack *stack, bt_hci_con_handle_t con_handle, bt_addr_t addr)
long bt_hci_get_remote_cod (struct btstack *stack, bt_hci_con_handle_t con_handle)
btstack * bt_hci_init (void *transport)
 Initializes hci-layer (specified by given stack argument).
long bt_hci_is_con_open (struct btstack *stack, bt_hci_con_handle_t con_handle)
long bt_hci_local_mode_discovery (struct btstack *stack, bt_hci_con_handle_t app_con_handle)
long bt_hci_local_role_discovery (struct btstack *stack, bt_hci_con_handle_t con_handle)
void bt_hci_register_accept_con_cb (struct btstack *stack, HCI_CON_RQST_CB, void *cb_arg)
 Registers the accept-connection callback.
void bt_hci_register_cl_acl_cb (struct btstack *stack, hci_acl_cb_t co_acl_cb, struct bt_hci_pkt_acl *pkt, void *arg)
 Registers acl-callback handler for connection-less (channel id = 2) acl packets.
void bt_hci_register_co_acl_cb (struct btstack *stack, hci_acl_cb_t co_acl_cb, struct bt_hci_pkt_acl *pkt, void *arg)
 Registers acl-callback handler for l2cap connection-oriented acl packets.
void bt_hci_register_con_table_cb (struct btstack *stack, HCI_CON_TABLE_CB, void *cb_arg)
void bt_hci_register_link_key_notification_cb (struct btstack *stack, HCI_LINK_KEY_NOTIFICATION_CB, void *cb_arg)
 Registers the Link Key Available callback.
void bt_hci_register_pin_code_request_cb (struct btstack *stack, HCI_PIN_CODE_REQUEST_CB, void *cb_arg)
 Registers the PIN Code Request callback.
void bt_hci_register_sco_cb (struct btstack *stack, HCI_SCO_CB, struct bt_hci_pkt_sco *pkt)
 Registers the acl-callback handler.
long bt_hci_send_acl_pkt (struct btstack *stack, bt_hci_con_handle_t con_handle, u_char pb_flag, u_char bc_flag, u_short length, struct bt_hci_pkt_acl *pkt)
 Send a ACL Packet .
void bt_hci_set_pin_code (struct btstack *stack, char *pin_code)
void bt_hw_reset (struct btstack *stack)
 Doing a hardware reset of the Bluetooth module.
void * bt_hw_shutdown (struct btstack *stack)
 Prepare the BT stack for shutdown and power off the Bluetooth module.
void bt_hw_startup (struct btstack *stack, HCI_CON_RQST_CB)
 Doing a hardware reset of the Bluetooth module.
void bt_setup (struct btstack *stack)
 Setups the Bluetooth module.

Variables

u_char _bt_hci_debug_uart

Define Documentation

#define BT_ACL_PKT_MAX_PAYLOAD ( btstack   )     (btstack->host_acl_len)

Shortcut to get the maximal payload size of an acl communication packet.

#define BT_ERR_ACL_PLOAD_OVFLW   -0x010b

too much data written to an open acl link

#define BT_ERR_BT_MODULE   -0x0100

problems with bluetooth module

Examples:
bt-lego/bt-lego.c.

#define BT_ERR_CON_BROKEN   -0x010a

disconnected during cmd execution

#define BT_ERR_CON_EXIST   -0x0107

a connection to bd addr already exists

#define BT_ERR_CON_PEND_ACTIVE   -0x0108

a connection to bd addr is actively opened

#define BT_ERR_CON_PEND_PASSIVE   -0x0109

a connection to bd addr is passively opened

#define BT_ERR_MAX_CON   -0x0104

max nr of connection reached

#define BT_ERR_MAX_WAITCMD   -0x0106

stack waitqueue full

#define BT_ERR_NO_CON   -0x0103

no connection with this app_con_handle exists

Examples:
bt-lego/bt-lego.c.

#define BT_ERR_RST_RUN   -0x0105

reset already running

#define BT_ERR_UART_COM   -0x0101

There was an error with the uart-commun.

#define BT_ERR_USB_COM   -0x0102

There was an error with the usb-commun.

#define BT_HCI_DISCON_ABOUT_TO_POWER_OFF   0x15

Disconnection because of device shutting down

#define BT_HCI_DISCON_BY_LOCAL_DEVICE   0x16

Disconnection because local device requested

#define BT_HCI_DISCON_LINK_LOST   0x08

Disconnection because of connection link lost

#define BT_HCI_DISCON_LOW_RESSOURCE   0x14

Disconnection because of low ressource

#define BT_HCI_DISCON_OTHER_DEVICE   0x13

Disconnection because other end terminated connection

Function Documentation

long bt_hci_get_con_handle ( struct btstack *  stack,
bt_addr_t  addr 
)

once a connection is established the connection will be addressed via a unique connection handle. The function returns the handle via the argument pointer con_handle (to have a similar API to the inverse function!)

Does not go over the wire!

Parameters:
stack The bt-stack to use
addr The bdaddr wich is associated with the con_handle
Returns:
con_handle or possible errors:

long bt_hci_get_con_handles ( struct btstack *  stack,
bt_hci_con_handle_array  con_handles 
)

Does not go over the wire!

This function returns the list of open connections. If only the number of connections is needed, the function can be called with a NULL pointer for the con_handles. Pass NULL instead of con_handles if only interested in number of open connections.

Parameters:
stack The bt-stack to use
con_handles Pointer to array with all active connections
Returns:
The number of connections (indicating valid position in con_handles)

long bt_hci_get_local_bt_addr ( struct btstack *  stack,
bt_addr_t  addr 
)

The bluetooth address of the local node can be retrieved.

Does not go over the wire!

Replaces bt_hci_read_bt_addr.

Parameters:
stack The bt-stack to use
addr The bt_addr where the result will be stored
Returns:
always 0
Examples:
bt-lego/bt-lego.c, and btstreamer/streamer/btstreamer.c.

long bt_hci_get_remote_bt_addr ( struct btstack *  stack,
bt_hci_con_handle_t  con_handle,
bt_addr_t  addr 
)

The bluetooth address of the remote node of a connection can be retrieved calling this function with the connection handle.

Does not go over the wire!

Parameters:
stack The bt-stack to use
con_handle The handle which is associated with the con_handle
addr The bt_addr where the result will be stored
Returns:
0 or possible errors:

long bt_hci_get_remote_cod ( struct btstack *  stack,
bt_hci_con_handle_t  con_handle 
)

returns the cod of the connection with handle con_handle (24-bit)

Does not go over the wire!

Parameters:
stack The bt-stack to use
con_handle The handle of the connection
Returns:
cod or possible errors:

struct btstack* bt_hci_init ( void *  transport  ) 

Initializes hci-layer (specified by given stack argument).

Initializes the bt-stack, dispatches a new thread (the bt-receive thread) and enters (in this thread) an infinite loop to process all the packets.

Returns:
pointer of bt stack
Examples:
bt-lego/bt-lego.c, bt-remoteprog/demo-rprog.c, btstreamer/receiver/btreceiver.c, btstreamer/streamer/btstreamer.c, l2cap-cmd/l2cap-cmd.c, mhop_blink/mhop_blink.c, and rfcomm-cmd/rfcomm-cmd.c.

long bt_hci_is_con_open ( struct btstack *  stack,
bt_hci_con_handle_t  con_handle 
)

If the connection with handle con_handle is open, this function returns 0. If the connection is not open anymore, the return value will indicate an error with value BT_ERR_NO_CON.

Does not go over the wire!

If the connection is in the initialization phase (active or passive), then this function will return BT_ERR_NO_CON, because the connect-process is not jet completed!

Parameters:
stack The bt-stack to use
con_handle The handle to check
Returns:
0 or possible errors:

long bt_hci_local_mode_discovery ( struct btstack *  stack,
bt_hci_con_handle_t  app_con_handle 
)

Returns the Mode of the specified conn.handle

Does not go over the wire!

mode (1 Byte): BT_HCI_CONN_MODE_ACTIVE BT_HCI_CONN_MODE_HOLD BT_HCI_CONN_MODE_SNIFF BT_HCI_CONN_MODE_PARK

interval (u_short): 0x0000-0xFFFF

return (last 3 bytes meaningful): ... | interval | mode |

Parameters:
stack The bt-stack to use
con_handle The handle of the connection
Returns:
mode with interval or possible errors:

long bt_hci_local_role_discovery ( struct btstack *  stack,
bt_hci_con_handle_t  con_handle 
)

Returns the Role of the specified conn.handle

Does not go over the wire!

Do not confuse this command with bt_hci_role_discovery(...)! That cmd. sends a hci-pkt to the host, this (local) cmd just does a lookup in the conn.table!

If you opened the connection and allowed a role change, then this information may be inaccurate! After the first call to bt_hci_role_discovery, the local con. is accurate and keeps track of all role changes!

BT_HCI_MY_ROLE_MASTER (this device is master of this connection) BT_HCI_MY_ROLE_SLAVE (this device is slave of this connection)

Parameters:
stack The bt-stack to use
con_handle The handle of the connection
Returns:
BT_HCI_MY_ROLE_MASTER or BT_HCI_MY_ROLE_SLAVE or possible errors:

void bt_hci_register_accept_con_cb ( struct btstack *  stack,
HCI_CON_RQST_CB  ,
void *  cb_arg 
)

Registers the accept-connection callback.

Registers a filter function that is called each time a connection request arrives.

Parameters:
stack The bt-stack to use
HCI_ACCEPT_CON_CB the function pointer to the callback
cb_arg Pointer to an argument
See also:
HCI_ACCEPT_CON_CB

void bt_hci_register_cl_acl_cb ( struct btstack *  stack,
hci_acl_cb_t  co_acl_cb,
struct bt_hci_pkt_acl *  pkt,
void *  arg 
)

Registers acl-callback handler for connection-less (channel id = 2) acl packets.

HCI and ACL-Layer will exchange pkts. HCI->ACL everytime when a pkt comes in and ACL->HCI everytime when the ACL-layer wants to send a pkt. We dont want the hci layer to run out of free buffers, so the above layer has to hand down a free pkt-buffer everytime an interaction happens.

Parameters:
stack The bt-stack to use
HCI_ACL_CB the functionpointer to the callback
pkt a first packet that the HCI-layer can hand upwards!
void pointer that will be passed to the callback function
Examples:
btstreamer/receiver/btreceiver.c.

void bt_hci_register_co_acl_cb ( struct btstack *  stack,
hci_acl_cb_t  co_acl_cb,
struct bt_hci_pkt_acl *  pkt,
void *  arg 
)

Registers acl-callback handler for l2cap connection-oriented acl packets.

HCI and ACL-Layer will exchange pkts. HCI->ACL everytime when a pkt comes in and ACL->HCI everytime when the ACL-layer wants to send a pkt. We dont want the hci layer to run out of free buffers, so the above layer has to hand down a free pkt-buffer everytime an interaction happens.

Parameters:
stack The bt-stack to use
HCI_ACL_CB the functionpointer to the callback
pkt a first packet that the HCI-layer can hand upwards!
void pointer that will be passed to the callback function

void bt_hci_register_con_table_cb ( struct btstack *  stack,
HCI_CON_TABLE_CB  ,
void *  cb_arg 
)

With this function an application can register a callback function that will be called as soon as the connection table changes. This is the case if:
-a connection was opened
-a connection was closed
-a role change occured
The callback function will be passed 3 arguments: type of change, details, con_handle:

Type can be:

Only one callback can be registered at a given time!

For BT_HCI_CONNECTION, details tells whether the connection was opened by us:

For BT_HCI_DISCONNECTION, details give the disconnect reason:

Parameters:
stack The bt-stack to use
HCI_CON_TABLE_CB The callback that will be registered.
cb_arg Pointer to a argument.
Examples:
btstreamer/receiver/btreceiver.c, btstreamer/streamer/btstreamer.c, and mhop_blink/mhop_blink.c.

void bt_hci_register_link_key_notification_cb ( struct btstack *  stack,
HCI_LINK_KEY_NOTIFICATION_CB  ,
void *  cb_arg 
)

Registers the Link Key Available callback.

Parameters:
stack The bt-stack to use
HCI_LINK_KEY_NOTIFICATION_CB the function pointer to the callback
cb_arg Pointer to an argument
See also:
HCI_LINK_KEY_NOTIFICATION_CB

void bt_hci_register_pin_code_request_cb ( struct btstack *  stack,
HCI_PIN_CODE_REQUEST_CB  ,
void *  cb_arg 
)

Registers the PIN Code Request callback.

Parameters:
stack The bt-stack to use
HCI_PIN_CODE_REQUEST_CB the function pointer to the callback
cb_arg Pointer to an argument
See also:
HCI_PIN_CODE_REQUEST_CB

void bt_hci_register_sco_cb ( struct btstack *  stack,
HCI_SCO_CB  ,
struct bt_hci_pkt_sco *  pkt 
)

Registers the acl-callback handler.

HCI and SCO-Layer will exchange pkts. HCI->SCO everytime when a pkt comes in and SCO->HCI everytime when the SCO-layer wants to send a pkt. We dont want the hci layer to run out of free buffers, so the above layer has to hand down a free pkt-buffer everytime an interaction happens.

Parameters:
stack The bt-stack to use
HCI_SCO_CB the functionpointer to the callback
pkt a first packet that the HCI-layer can hand upwards!

long bt_hci_send_acl_pkt ( struct btstack *  stack,
bt_hci_con_handle_t  con_handle,
u_char  pb_flag,
u_char  bc_flag,
u_short  length,
struct bt_hci_pkt_acl *  pkt 
)

Send a ACL Packet .

Does internal conversion from bt_hci_con_handle_t to baseband tables.

The HCI-Layer fills the pkt->header fields!
The higher layer needs to keep track of length (it shall not be larger than stack->acl_max_len or max buffer size)
This function does NOT fragment the pkts!

If you want the pkts fragmented, you have to implement it either in this function or handle the pkt->header in a higher layer.
Most probably the second option would be the better choice!

If the connection is in the initialization phase (active or passive), then this function will return BT_ERR_NO_CON, because the connect-process is not yet completed!

Parameters:
stack The bt-stack to use
con_handle The outgoing handle
pb_flag Packet Boundary Flag HCI_PB_FIRST_FRAGMENT or HCI_PB_CONTD_FRAGMENT
bc_flag Broadcast Flag HCI_BC_UNICAST, HCI_BC_ACTIVE or HCI_BC_PICONET
length The length of the payload
pkt Pointer to the actual pkt, with payload already filled.
Returns:
0 or possible errors:
Examples:
btstreamer/streamer/btstreamer.c.

void bt_hw_reset ( struct btstack *  stack  ) 

Doing a hardware reset of the Bluetooth module.

only available on BTnode3

Parameters:
stack The bt-stack to use

void* bt_hw_shutdown ( struct btstack *  stack  ) 

Prepare the BT stack for shutdown and power off the Bluetooth module.

only available on BTnode3

Parameters:
stack The bt-stack to use
Returns:
pointer to the hci connection request callback (needed by startup)

void bt_hw_startup ( struct btstack *  stack,
HCI_CON_RQST_CB   
)

Doing a hardware reset of the Bluetooth module.

only available on BTnode3

Parameters:
stack The bt-stack to use
con_rqst_cb pointer to the hci connection request callback

void bt_setup ( struct btstack *  stack  ) 

Setups the Bluetooth module.

Sets common parameters like baudrate etc.

Variable Documentation

u_char _bt_hci_debug_uart

for uart debugging. to turn on uart debugging set this value to 1

Generated on Wed Apr 29 11:12:28 2009 for BTnut System Software by doxygen 1.5.1
!!! Dieses Dokument stammt aus dem ETH Web-Archiv und wird nicht mehr gepflegt !!!
!!! This document is stored in the ETH Web archive and is no longer maintained !!!