BlueStack User Manual

BlueStack User Manual

General Information General Information Ownership of Information Mezoe 2001 (Mezoe is a division of Cambridge Consultants Ltd) All information contained in this document is owned by Mezoe and should not be copied or reused for any purpose. Trademarks BlueStack is a trademark of Mezoe that is registered in the United Kingdom StackPrimer is a trademark of Mezoe Proto Developer is a trademark of Mezoe Interface Express is a trademark of Mezoe Mezoe is a trademark of Cambridge Consultants Ltd. CCL is a trademark of Cambridge Consultants Ltd that is registered in the United Kingdom and Germany Bluetooth is a trademark owned by the Bluetooth SIG, Inc. and used by Mezoe under license Bluecore is a trademark of Cambridge Silicon Radio All other trademarks are acknowledged as owned by their respective proprietors Confidentiality This document contains confidential information that is proprietary to Mezoe. This information must only be used for its intended purpose and should not be disclosed to third parties. Fitness for Purpose and Liability Mezoe makes no warranty of any kind with regard to the information contained in this document, expressed or implied, including but not limited to implied warranties of fitness for purpose or satisfactory quality. Mezoe does not warrant that the Software to which this document refers or this document itself is error free or suitable for use in safety-critical applications. The user shall take full responsibility for ensuring that the Software and the document is suitable for the user s intended purposes and for its subsequent use. Mezoe does not accept any liability for any loss or damage arising from the use of this document or the information within it, howsoever caused, including but not limited to direct, indirect, unforeseen or consequential loss or damage, other than death or personal injury resulting from Mezoe s proven negligence. Contact Mezoe Mezoe, Cambridge Consultants Ltd Science park Milton Road Cambridge CB4 0DW UK Tel. +44 (0) 1223 425093 Fax. +44 (0) 1223 392323 Email bluetooth@mezoe.com www.mezoe.com 2001 2

Contents Contents Contents 3 List of Figures 11 List of Tables 12 1 Introduction 15 1.1 Audience 15 1.2 In This Document 15 1.2.1 About this Manual 15 1.2.2 Finding Your Way Around 15 1.3 Conventions 16 1.3.1 Getting More Information 17 2 Overview 18 2.1 Introducing BlueStack 18 2.2 BlueStack as a Software Component 19 2.2.1 Standard Two-Processor Solution 22 2.2.2 Embedded Two-Processor Solution 22 2.2.3 Wholly Embedded Solution 22 2.3 The Application Interface to BlueStack 23 2.3.1 Scheduler and BlueStack Initialisation 23 2.3.2 Memory Management Functions 24 2.3.3 HCI Transport Driver Configuration 24 2.3.4 Scheduler Services 25 2.4 BlueStack Layers 26 2.4.1 Link Manager 26 2.4.2 L2CAP 26 2.4.3 Device Manager 26 2.4.4 Service Discovery 27 2.4.5 RFCOMM 27 2.4.6 TCS Binary 28 2.4.7 Host Controller Interface 29 2.5 Internal Communications Model Adopted for BlueStack 29 2.5.1 Interface Library Functions 32 2.5.2 Registration and phandles 33 2.6 Error Handling and Debug Facilities 34 2.7 Management Entity 34 2.8 Partitioning 36 2.9 Porting and Building 36 3 BlueStack Application Interface 37 3.1 Overview 37 3.2 Key Concepts 38 3.2.1 The Scheduler 38 3.2.2 Inter-process Communication, Messaging and Events 39 3.2.3 Communications Services 40 3.2.4 Timed Events 41 3.3 Configurability and Tuners 41 3.4 Application Interface Functions Initialisation 42 3.4.1 BST_InitScheduler 42 3.4.2 BST_ConfigureStack 42 3.4.3 BST_StartScheduler 43 3.4.4 BST_sched_protect_tasks 44 3.4.5 BST_ReconfigurePool 44 2001 3

Contents 3.4.6 BST_InitHCIdrv 45 3.4.7 BST_HCIdrv_enum_drivers 46 3.4.8 BST_HCIdrv_select_driver 47 3.4.9 BST_HCIdrv_get_current_driver 47 3.4.10 BST_HCIdrv_query_driver_available 48 3.4.11 BST_HCIdrv_get_driver_name 48 3.4.12 BST_HCIdrv_get_driver_description 49 3.4.13 BST_HCIdrv_get_driver_id 49 3.5 Application Interface Functions Scheduler Services 50 3.5.1 BST_putMessage 50 3.5.2 BST_getMessage 51 3.5.3 BST_put_message_at 51 3.5.4 BST_put_message_in 52 3.5.5 BST_cancel_timed_message 53 3.5.6 BST_timed_event_at 54 3.5.7 BST_timed_event_in 55 3.5.8 BST_cancel_timed_event 55 3.5.9 BST_get_time 56 3.5.10 BST_sched_claim_task_mutex 56 3.5.11 BST_sched_release_task_mutex 57 3.5.12 BST_CallbackOnPanic 57 3.6 Application Interface Functions Memory Management 58 3.6.1 BST_pmalloc 58 3.6.2 BST_pfree 58 3.6.3 BST_zpmalloc 59 3.6.4 BST_xpmalloc 59 3.6.5 BST_xzpmalloc 59 3.6.6 BST_RFC_DLC_malloc 60 3.6.7 BST_prealloc 60 3.6.8 BST_xprealloc 61 3.6.9 BST_pcopy 62 3.6.10 BST_xpcopy 62 3.6.11 BST_pstrdup 63 3.6.12 BST_xpstrdup 63 3.7 Application Interface Functions Utilities 64 3.7.1 bd_addr_copy 64 3.7.2 bd_addr_zero 64 3.7.3 bd_addr_eq 65 3.7.4 BST_ReportPoolStats 65 3.7.5 BST_ReportPoolUsage 66 3.7.6 BST_SendWatchText 66 3.7.7 BST_send_watch_text 67 3.7.8 BST_get_config_string 68 3.7.9 BST_get_scheduler_identifier 68 3.8 Usage Scenarios and Examples 69 3.8.1 Scheduler and BlueStack Initialisation 69 3.8.2 Sending Messages 71 3.8.3 Getting Messages 71 3.8.4 Callback on Panic 71 4 RFCOMM 72 4.1 Overview 72 4.2 Key Concepts 73 4.2.1 Mux ID 74 4.2.2 Local Server Channel 74 2001 4

Contents 4.2.3 RFCOMM Flow Control 74 4.3 Configurability and Tuners 78 4.4 RFCOMM API Primitives 79 4.4.1 RFC_INIT 79 4.4.2 RFC_REGISTER 80 4.4.3 RFC_START 81 4.4.4 RFC_STARTCMP 83 4.4.5 RFC_CLOSE 85 4.4.6 RFC_PARNEG 86 4.4.7 RFC_ESTABLISH 88 4.4.8 RFC_RELEASE 90 4.4.9 RFC_CONTROL 91 4.4.10 RFC_PORTNEG 93 4.4.11 RFC_FCON 96 4.4.12 RFC_FCOFF 97 4.4.13 RFC_DATA 98 4.4.14 RFC_DATAWRITE 99 4.4.15 RFC_LINESTATUS 100 4.4.16 RFC_TEST 101 4.4.17 RFC_NSC 102 4.5 Usage Scenarios and Examples 103 4.5.1 Starting and Configuring a Multiplexer Session As an Initiator 103 4.5.2 Starting and Configuring a Multiplexer Session As a Recipient 105 4.5.3 Opening a Server Channel and Negotiating 107 5 Service Discovery Protocol 111 5.1 Overview of SDP and its API 111 5.1.1 Service Discovery Client (SDC) Interface 111 5.1.2 Service Discovery Server (SDS) Interface 112 5.2 Key Concepts within SDP 112 5.2.1 Service Record Formats 112 5.3 Configurability and Tuners 115 5.4 SDP API Primitives SDC 116 5.4.1 SDC_SERVICE_SEARCH 116 5.4.2 SDC_SERVICE_ATTRIBUTE 118 5.4.3 SDC_SERVICE_SEARCH_ATTRIBUTE 119 5.4.4 SDC_TERMINATE_PRIMITIVE 120 5.4.5 SDC_OPEN_SEARCH 121 5.4.6 SDC_CLOSE_SEARCH 122 5.4.7 SDC_CONFIG 122 5.5 SDP API Primitives SDS 123 5.5.1 SDS_REGISTER 123 5.5.2 SDS_UNREGISTER 124 5.5.3 SDS_CONFIG 124 5.6 Usage Scenarios and Examples 125 5.6.1 Service Registration 125 5.6.2 Service Search Request 129 5.6.3 Service Attribute Request 132 6 TCS 136 6.1 Overview 136 6.2 Key Concepts 139 6.2.1 Attach 139 6.2.2 SCO Bearer Call Management 139 6.2.3 Connectionless Call Management 140 2001 5

Contents 6.2.4 Group Management 141 6.2.5 Memory Management 142 6.2.6 TCS Constraints 142 6.2.7 Race Conditions / Multiple Resources 143 6.3 Configurability and Tuners 143 6.4 TCS API Primitives 144 6.4.1 TCS_REGISTER 144 6.4.2 TCS_UNREGISTER 145 6.4.3 TCS_ATTACH 146 6.4.4 TCS_PREATTACH 148 6.4.5 TCS_DETACH 149 6.4.6 TCS_SETUP 150 6.4.7 TCS_CL_SETUP 154 6.4.8 TCS_INFO 158 6.4.9 TCS_CALL_PROCEEDING 161 6.4.10 TCS_ALERTING 163 6.4.11 TCS_OPEN_SCO 165 6.4.12 TCS_CONNECT 167 6.4.13 TCS_PROGRESS 169 6.4.14 TCS_DISCONNECT 170 6.4.15 TCS_RELEASING 172 6.4.16 TCS_RELEASED 174 6.4.17 TCS_CL_RELEASE 176 6.4.18 TCS_CL_RELEASED 178 6.4.19 TCS_START_DTMF 179 6.4.20 TCS_STOP_DTMF 181 6.4.21 TCS_ACCESS_RIGHTS 182 6.4.22 TCS_WUG_INFO 184 6.4.23 TCS_LISTEN_REQUEST 186 6.4.24 TCS_LISTEN_SUGGEST 188 6.4.25 TCS_LISTEN_QUERY 190 6.4.26 TCS_CL_INFO 192 7 L2CAP 194 7.1 Overview of L2CAP and its API 194 7.2 Key Concepts 195 7.2.1 PSM 195 7.2.2 CID 195 7.2.3 MTU 195 7.2.4 RTX 195 7.2.5 ERTX 196 7.3 Configurability and Tuners 196 7.4 L2CAP API Primitives 197 7.4.1 L2CA_REGISTER 197 7.4.2 L2CA_CONNECT 198 7.4.3 L2CA_CONFIG 200 7.4.4 L2CA_DATAWRITE 202 7.4.5 L2CA_DATAREAD 203 7.4.6 L2CA_DISCONNECT 204 7.4.7 L2CA_TIMEOUT 205 7.4.8 L2CA_QOSVIOLATION 205 7.4.9 L2CA_PING 206 7.4.10 L2CA_GETINFO 207 7.4.11 L2CA_GROUP_CREATE 208 7.4.12 L2CA_GROUP_CLOSE 209 2001 6

Contents 7.4.13 L2CA_ENABLE_CONNECTIONLESS 210 7.4.14 L2CA_DISABLE_CONNECTIONLESS 210 7.5 Usage Scenarios and Examples 211 7.5.1 Registration 211 7.5.2 Connection Establishment and Configuration Outgoing 212 7.5.3 Connection Establishment and Configuration Incoming 214 7.5.4 Data Transfer 216 7.5.5 Disconnection Local Initiation 217 7.5.6 Disconnection Remote Initiation 217 8 Device Manager 219 8.1 Overview 219 8.2 Key Concepts 220 8.2.1 Device Discoverability and Inquiry 221 8.2.2 Security Manager 221 8.2.3 Link Policy 222 8.2.4 ACL Link Management 223 8.2.5 SCO Flow Control 224 8.2.6 Local Name 225 8.2.7 Parameter Caching 225 8.3 Configurability and Tuners 225 8.4 Device Manager API Primitives General 225 8.5 Device Manager API Primitives Application Manager Related 226 8.5.1 DM_AM_REGISTER 226 8.5.2 DM_WRITE_CACHED_PAGE_MODE 227 8.5.3 DM_WRITE_CACHED_CLOCK_OFFSET 228 8.5.4 DM_CLEAR_PARAM_CACHE 229 8.6 Device Manager API Primitives Link Control 230 8.6.1 DM_HCI_INQUIRY 230 8.6.2 DM_HCI_INQUIRY_RESULT 231 8.6.3 DM_HCI_INQUIRY_COMPLETE 232 8.6.4 DM_HCI_INQUIRY_CANCEL 233 8.6.5 DM_HCI_INQUIRY_CANCEL_COMPLETE 233 8.6.6 DM_HCI_CHANGE_PACKET_TYPE 234 8.6.7 DM_HCI_CHANGE_LINK_KEY 235 8.6.8 DM_HCI_MASTER_LINK_KEY 235 8.6.9 DM_HCI_REMOTE_NAME_REQUEST 236 8.6.10 DM_HCI_READ_REMOTE_FEATURES 236 8.6.11 DM_HCI_READ_REMOTE_VERSION 237 8.6.12 DM_HCI_READ_CLOCK_OFFSET 237 8.6.13 DM_HCI_REMOTE_NAME_COMPLETE 238 8.7 Device Manager API Primitives Link Policy 239 8.7.1 DM_SET_DEFAULT_LINK_POLICY 239 8.7.2 DM_HCI_WRITE_LP_SETTINGS 240 8.7.3 DM_HCI_WRITE_LP_SETTINGS_COMPLETE 241 8.7.4 DM_HCI_READ_LP_SETTINGS 242 8.7.5 DM_HCI_READ_LP_SETTINGS_COMPLETE 242 8.7.6 DM_HCI_PARK_MODE 243 8.7.7 DM_HCI_EXIT_PARK_MODE 244 8.7.8 DM_HCI_HOLD_MODE 245 8.7.9 DM_HCI_SNIFF_MODE 246 8.7.10 DM_HCI_EXIT_SNIFF_MODE 247 8.7.11 DM_HCI_ROLE_DISCOVERY 248 8.7.12 DM_HCI_SWITCH_ROLE 248 2001 7

Contents 8.8 Device Manager API Primitives Host Controller and Baseband 249 8.8.1 DM_HCI_CHANGE_LOCAL_NAME 249 8.8.2 DM_HCI_CHANGE_LOCAL_NAME_COMPLETE 249 8.8.3 DM_HCI_WRITE_SCAN_ENABLE 250 8.8.4 DM_HCI_WRITE_CURRENT_IAC_LAP 251 8.8.5 DM_HCI_FLUSH 252 8.8.6 DM_HCI_READ_AUTO_FLUSH_TIMEOUT 252 8.8.7 DM_HCI_WRITE_AUTO_FLUSH_TIMEOUT 253 8.8.8 DM_HCI_READ_TX_POWER_LEVEL 254 8.8.9 DM_HCI_READ_SCO_FLOW_CONTROL_ENABLE 255 8.8.10 DM_HCI_WRITE_SCO_FLOW_CONTROL_ENABLE 255 8.8.11 DM_HCI_READ_LINK_SUPERV_TIMEOUT 256 8.8.12 DM_HCI_WRITE_LINK_SUPERV_TIMEOUT 256 8.9 Device Manager API Primitives Status 257 8.9.1 DM_HCI_FAILED_CONTACT_COUNTER 257 8.9.2 DM_HCI_RESET_CONTACT_COUNTER 257 8.9.3 DM_HCI_GET_LINK_QUALITY 258 8.9.4 DM_HCI_READ_RSSI 258 8.10 Device Manager API Primitives SCO Control Related 259 8.10.1 DM_SCO_INCOMING_REGISTER 259 8.10.2 DM_SCO_INCOMING_UNREGISTER 260 8.10.3 DM_SCO_CONNECT 261 8.10.4 DM_SCO_DISCONNECT 262 8.10.5 DM_SCO_BUFFER_SIZE 263 8.10.6 DM_SCO_ DATA_SENT 264 8.11 Device Manager API Primitives Security Manager Related 265 8.11.1 DM_SM_PIN_REQUEST 265 8.11.2 DM_SM_LINK_KEY_REQUEST 266 8.11.3 DM_SM_SET_DEFAULT_SECURITY 267 8.11.4 DM_SM_REGISTER 268 8.11.5 DM_SM_REGISTER_OUTGOING 269 8.11.6 DM_SM_UNREGISTER 270 8.11.7 DM_SM_UNREGISTER_OUTGOING 271 8.11.8 DM_SM_ACCESS 272 8.11.9 DM_SM_SET_SEC_MODE_REQ 273 8.11.10 DM_SM_ADD_DEVICE_REQ 274 8.11.11 DM_SM_REMOVE_DEVICE 275 8.11.12 DM_SM_AUTHORISE 276 8.11.13 DM_SM_AUTHENTICATE 277 8.11.14 DM_SM_ENCRYPT 278 8.11.15 DM_SM_ENCRYPTION_CHANGE 279 8.12 ACL link management and monitoring 280 8.12.1 DM_ACL_OPEN 280 8.12.2 DM_ACL_OPENED_IND 281 8.12.3 DM_ACL_CLOSED_IND 281 8.13 Usage Scenarios and Examples 281 8.13.1 Registration 282 8.13.2 SCO Connection Establishment 283 8.13.3 Inquiry 285 8.13.4 Limited Discoverability Mode 288 9 HCI Transport 293 9.1 HCI Top Interface 294 9.1.1 Overview 294 2001 8

Contents 9.2 Downstream SCO Data Interface 296 9.2.1 HCI_Send_SCO_Data_Packet 296 9.2.2 Example 297 9.3 Upstream SCO Data Interface 298 9.3.1 HCI_SCO_DATA_PACKET 298 9.3.2 Example 299 9.4 SCO data application management 301 9.5 UART Driver Function Interface and USB Interface 301 Annex A Writing a Port Entity 302 A.1 Overview 302 A.2 Example Action Functions 308 Send_Start_Req 308 Send_ParNeg_Req 309 Send_Establish_Req 310 Send_Close_Req 310 Send_Established_ok 310 Send_Data 310 Read_Data 311 Store_Data 311 Close_Connection 311 Annex B Error Codes 313 B.1 GENERAL_ERROR 313 B.2 RFCOMM_ERROR 313 B.3 L2CAP_ERROR 313 B.4 DM_ERROR 314 B.5 HCI_ERROR 314 B.6 LM_ERROR 314 B.7 SDP_ERROR 314 B.8 CS_ERROR 314 Annex C Changes in this version 315 C.1 General 315 C.2 Introduction 315 C.3 Overview 315 C.4 BlueStack Application Interface 315 C.5 RFCOMM 315 C.6 SDP 315 C.7 TCS 316 C.8 L2CAP 316 C.9 Device Manager 316 C.10 HCI Transport 317 C.11 Annex A Writing a port entity 317 C.12 Annex B Error Codes 317 Glossary 318 event 318 Big Endian 318 downstream 318 host 318 host controller 318 phandle 318 server channel 318 upstream 318 2001 9

Contents Acronyms 319 2001 10

Contents List of Figures Figure 2-1: Bluetooth Protocol Stack as Specified by the Bluetooth SIG...18 Figure 2-2: BlueStack Protocols Layers...19 Figure 2-3: Layers Required in an Application Running over Bluetooth...20 Figure 2-4: Showing the relationship between the Application Interface to BlueStack (bluestack.h) and the Interface Library Functions....21 Figure 2-5: Three Integration Approaches Illustrated...22 Figure 2-6: RFCOMM Devices Type 1 and Type 2...28 Figure 2-7: HCI showing physical split between Host and Host Controller...29 Figure 2-8: Use of Primitives with Layered Protocols...30 Figure 2-9: Protocol Message Construction Within a Layered Architecture...30 Figure 2-10: Management Entity in the Integrated Application...35 Figure 3-1: The Application Interface to BlueStack....37 Figure 3-2: Illustration of Event Handling and Message Passing...40 Figure 3-3: Primitive Definition Format...41 Figure 4-1: RFCOMM Overview Architecture...73 Figure 4-2: MUX and Service Channel Relationship Example...74 Figure 4-3: RFCOMM Credit-based Flow Control, successful negotiation...75 Figure 4-4: RFCOMM Credit-based Flow Control, unsuccessful negotiation...76 Figure 4-5: Updating flow control with no user data...77 Figure 4-6: Starting a Multiplexer Session As an Initiator...103 Figure 4-7: Starting a Multiplexer Session As a Recipient...105 Figure 4-8: Opening a Server Channel and Negotiating...107 Figure 5-1: Service Record Attribute List...112 Figure 5-2: Service Record Structure...115 Figure 5-3: Service Registration...125 Figure 5-4: COM1 Service Record Example...129 Figure 5-5: Service Search Request...130 Figure 5-6: Service Attribute Request...132 Figure 6-1: TCS Binary Relationship to Other Entities...136 Figure 6-2: Cordless Telephony Application supporting multiple profiles...137 Figure 6-3: Cordless Telephony Scenario...138 Figure 7-1: Registration...211 Figure 7-2: Connection Establishment Outgoing...212 Figure 7-3: Connection Establishment Incoming...214 Figure 7-4: Data Transfer...216 Figure 7-5: Disconnection Local Initiation...217 Figure 7-6: Disconnection Remote Initiation...217 Figure 8-1: Device Manager Interfaces...219 Figure 8-2: SCO Control Entity Credit Counter...224 Figure 8-3: Registration Example...282 Figure 8-4: SCO Connection Establishment...284 Figure 8-5: Inquiry...285 Figure 8-6: Inquiry Flowchart...286 Figure 9-1: HCI Transport Component Relationship...294 Figure 9-2: SCO Control and Data Flows...295 Figure 9-3: Layers Required in an Application Running over Bluetooth...302 Figure 9-4: Differences in Data Transfer...304 Figure 9-5: Port Entity Phases...304 Figure 9-6: Port Entity Application to RFCOMM Calls...305 Figure 9-7: Message Exchange...306 Figure 9-8: Basic Flow Control...307 2001 11

Contents List of Tables Table 2-1: Allowable BlueStack Partitioning Combinations...36 Table 4-1: RFC_INIT Primitives...79 Table 4-2: RFC_REGISTER Primitives...80 Table 4-3: RFC_START Primitives...81 Table 4-4: RFC_STARTCMP Primitive...83 Table 4-5: RFC_CLOSE Primitives...85 Table 4-6: RFC_PARNEG Primitives...86 Table 4-7: RFC_ESTABLISH Primitives...88 Table 4-8: RFC_RELEASE Primitive...90 Table 4-9: RFC_CONTROL Primitives...91 Table 4-10: Mapping From the Control Signal Octet by a Receiving Entity...92 Table 4-11: Mapping To the Control Signal Octet by a Sending Entity...92 Table 4-12: RFC_PORTNEG Primitives...93 Table 4-13: RFC_FCON Primitives...96 Table 4-14: RFC_FCOFF Primitives...97 Table 4-15: RFC_DATA Primitives...98 Table 4-16: RFC_DATAWRITE Primitives...99 Table 4-17: RFC_LINESTATUS Primitives...100 Table 4-18: RFC_TEST Primitives...101 Table 4-19: RFC_NSC Primitive...102 Table 5-1: Data Types from Bluetooth Specification...113 Table 5-2: Size Indexes from Bluetooth Specification...114 Table 5-3: SDC_SERVICE_SEARCH Primitives...116 Table 5-4: SDC_SERVICE_ATTRIBUTE Primitives...118 Table 5-5: SDC_SERVICE_SEARCH_ATTRIBUTE Primitives...119 Table 5-6: SDC_TERMINATE_PRIMITIVE Primitives...120 Table 5-7: SDC_OPEN_SEARCH Primitives...121 Table 5-8: SDC_CLOSE_SEARCH Primitive...122 Table 5-9: SDC_CONFIG Primitive...122 Table 5-10: SDS_REGISTER Primitives...123 Table 5-11: SDS_UNREGISTER Primitives...124 Table 5-12: SDS_CONFIG Primitive...124 Table 5-13: Serial Port Profile Service Database Entries...126 Table 6-1: TCS Primitives and wug_master Flag Relationship...142 Table 6-2: TCS_REGISTER Primitives...144 Table 6-3: TCS_UNREGISTER Primitives...145 Table 6-4: TCS_ATTACH Primitives...146 Table 6-5: TCS_ PRE_ATTACH Primitives...148 Table 6-6: TCS_DETACH Primitives...149 Table 6-7: TCS_SETUP Primitives...150 Table 6-8: TCS_CL_SETUP Primitives...154 Table 6-9: TCS_INFO Primitives...158 Table 6-10: TCS_CALL_PROCEEDING Primitives...161 Table 6-11: TCS_ALERTING Primitives...163 Table 6-12: TCS_OPEN_SCO Primitives...165 Table 6-13: TCS_CONNECT Primitives...167 Table 6-14: TCS_PROGRESS Primitives...169 Table 6-15: TCS_DISCONNECT Primitives...170 Table 6-16: TCS_RELEASING Primitives...172 Table 6-17: TCS_RELEASED Primitives...174 Table 6-18: TCS_CL_RELEASE Primitive...176 Table 6-19: TCS_CL_RELEASED Primitive...178 2001 12

Contents Table 6-20: TCS_START_DTMF Primitives...179 Table 6-21: TCS_STOP_DTMF Primitives...181 Table 6-22: TCS_ACCESS_RIGHTS Primitives...182 Table 6-23: TCS_WUG_INFO Primitives...184 Table 6-24: TCS_LISTEN_REQUEST Primitives...186 Table 6-25: TCS_LISTEN_SUGGEST Primitives...188 Table 6-26: TCS_LISTEN_QUERY Primitives...190 Table 6-27: TCS_CL_INFO Primitives...192 Table 7-1: L2CA_REGISTER Primitives...197 Table 7-2: L2CA_CONNECT Primitives...198 Table 7-3: L2CA_CONFIG Primitives...200 Table 7-4: L2CA_DATAWRITE Primitives...202 Table 7-5: L2CA_DATAREAD Primitives...203 Table 7-6: L2CA_DISCONNECT Primitives...204 Table 7-7: L2CA_TIMEOUT Primitives...205 Table 7-8: L2CA_QOSVIOLATION Primitives...205 Table 7-9: L2CA_PING Primitives...206 Table 7-10: L2CA_GETINFO Primitives...207 Table 7-11: L2CA_GROUP_CREATE Primitives...208 Table 7-12: L2CA_GROUP_CLOSE Primitives...209 Table 7-13: L2CA_ENABLE_CONNECTIONLESS Primitives...210 Table 7-14: L2CA_DISABLE_CONNECTIONLESS Primitives...210 Table 8-1: DM_AM_REGISTER Primitives...226 Table 8-2: DM_WRITE_CACHED_PAGE_MODE Primitives...227 Table 8-3: DM_WRITE_CACHED_CLOCK_OFFSET Primitives...228 Table 8-4: DM_CLEAR_PARAM_CACHE Primitives...229 Table 8-5: DM_HCI_INQUIRY Primitive...230 Table 8-6: DM_HCI_INQUIRY_RESULT Primitive...231 Table 8-7: DM_HCI_INQUIRY_COMPLETE Primitive...232 Table 8-8: DM_HCI_INQUIRY_CANCEL Primitive...233 Table 8-9: DM_HCI_INQUIRY_CANCEL_COMPLETE Primitive...233 Table 8-10: DM_HCI_CHANGE_PACKET_TYPE Primitive...234 Table 8-11: DM_HCI_CHANGE_LINK_KEY Primitive...235 Table 8-12: DM_HCI_MASTER_LINK_KEY Primitive...235 Table 8-13: DM_HCI_REMOTE_NAME_REQUEST Primitive...236 Table 8-14: DM_HCI_READ_REMOTE_FEATURES Primitive...236 Table 8-15: DM_HCI_READ_REMOTE_VERSION Primitive...237 Table 8-16: DM_HCI_READ_CLOCK_OFFSET Primitive...237 Table 8-17: DM_HCI_REMOTE_NAME_COMPLETE Primitive...238 Table 8-18: DM_SET_DEFAULT_LINK_POLICY Primitive...239 Table 8-19: DM_HCI_WRITE_LP_SETTINGS Primitive...240 Table 8-20: DM_HCI_WRITE_LP_SETTINGS_COMPLETE Primitive...241 Table 8-21: DM_HCI_READ_LP_SETTINGS Primitive...242 Table 8-22: DM_HCI_READ_LP_SETTINGS_COMPLETE Primitive...242 Table 8-23: DM_HCI_PARK_MODE Primitive...243 Table 8-24: DM_HCI_EXIT_PARK_MODE Primitive...244 Table 8-25: DM_HCI_HOLD_MODE Primitive...245 Table 8-26: DM_HCI_SNIFF_MODE Primitive...246 Table 8-27: DM_HCI_EXIT_SNIFF_MODE Primitive...247 Table 8-28: DM_HCI_ROLE_DISCOVERY Primitive...248 Table 8-29: DM_HCI_SWITCH_ROLE Primitive...248 Table 8-30: DM_HCI_CHANGE_LOCAL_NAME Primitive...249 Table 8-31: DM_HCI_CHANGE_LOCAL_NAME_COMPLETE Primitive...249 Table 8-32: DM_HCI_WRITE_SCAN_ENABLE Primitive...250 Table 8-33: DM_HCI_WRITE_CURRENT_IAC_LAP Primitive...251 2001 13

Contents Table 8-34: DM_HCI_FLUSH Primitive...252 Table 8-35: DM_HCI_READ_AUTO_FLUSH_TIMEOUT Primitive...252 Table 8-36: DM_HCI WRITE_AUTO_FLUSH_TIMEOUT Primitive...253 Table 8-37: DM_HCI_READ_TX_POWER_LEVEL Primitive...254 Table 8-38: DM_HCI_READ_SCO_FLOW_CONTROL_ENABLE Primitive...255 Table 8-39: DM_HCI_WRITE_SCO_FLOW_CONTROL_ENABLE Primitive...255 Table 8-40: DM_HCI_READ_LINK_SUPERV_TIMEOUT Primitive...256 Table 8-41: DM_HCI_WRITE_LINK_SUPERV_TIMEOUT Primitive...256 Table 8-42: DM_HCI_FAILED_CONTACT_COUNTER Primitive...257 Table 8-43: DM_HCI_RESET_CONTACT_COUNTER Primitive...257 Table 8-44: DM_HCI_GET_LINK_QUALITY Primitive...258 Table 8-45: DM_HCI_READ_RSSI Primitive...258 Table 8-46: DM_SCO_INCOMING_REGISTER primitive...259 Table 8-47: DM_SCO_INCOMING_UNREGISTER primitive...260 Table 8-48: DM_SCO_CONNECT Primitive...261 Table 8-49: DM_SCO_DISCONNECT Primitives...262 Table 8-50: DM_SCO_BUFFER_SIZE Primitive...263 Table 8-51: DM_SCO_DATA_SENT Primitive...264 Table 8-52: DM_SM_PIN_REQUEST Primitive...265 Table 8-53: DM_SM_LINK_KEY_REQUEST Primitive...266 Table 8-54: DM_SM_SET_DEFAULT_SECURITY Primitives...267 Table 8-55: DM_SM_REGISTER Primitives...268 Table 8-56: DM_SM_REGISTER_OUTGOING_REQ Primitives...269 Table 8-57: DM_SM_UNREGISTER Primitives...270 Table 8-58: DM_SM_UNREGISTER_OUTGOING Primitives...271 Table 8-59: DM_SM_ACCESS Primitives...272 Table 8-60: DM_SM_SET_SEC_MODE Primitives...273 Table 8-61: DM_SM_ADD_DEVICE Primitives...274 Table 8-62: DM_SM_REMOVE_DEVICE Primitives...275 Table 8-63: DM_SM_AUTHORISE Primitive...276 Table 8-64: DM_AUTHENTICATE Primitive...277 Table 8-65: DM_SM_ENCRYPT Primitive...278 Table 8-66: DM_SM_ENCRYPTION_CHANGE Primitive...279 Table 8-67: DM_ACL_OPEN Primitives...280 Table 8-68: DM_ACL_OPENED_IND Primitive...281 Table 8-69: DM_ACL_CLOSED_IND Primitive...281 Table 9-1: HCI_SCO_DATA_PACKET...298 Table 9-2: Message Exchange State Table...307 2001 14

Introduction 1 Introduction This chapter describes the BlueStack User Guide and the conventions used within. It contains the following sections: ΠAudience on page 15 ΠIn This Document on page 15 ΠConventions on page 16 1.1 Audience This User Guide is written for systems and product developers who want to incorporate BlueStack as a software component into their designs. The Guide assumes that the reader is familiar with C, the language BlueStack is written in. It is assumed that the reader is familiar with the basic Bluetooth concepts; it is possible to apply BlueStack without a need for a detailed understanding of the Bluetooth specification. Different sections of the manual are applicable to different application areas. Consequently, product developers can omit sections that are not relevant to them. 1.2 In This Document This document is the user s guide to BlueStack, the Bluetooth protocol software developed by Mezoe. It provides an overview of BlueStack that covers the design philosophy of the software and the Application Programming Interfaces (APIs). It does not provide a detailed description of the design of the individual software sub-systems that comprise BlueStack, nor does it describe the operation of Bluetooth. 1.2.1 About this Manual Each of the API s is described in detail. The information provided for the API primitives is illustrated with individual examples. Examples are also included for more complicated scenarios. This User Guide does not describe in detail how to design a Bluetooth system, nor does it provide any sample applications. Sample applications are included with Proto Developer for BlueStack (the BlueStack software development toolkit). 1.2.2 Finding Your Way Around We have provided some guideposts within the document concerning the relevancy of sections - see Conventions on page 16 for details. It is suggested that you begin by reading the Overview on page 18 if you are new to BlueStack. Once you become familiar with the overall philosophy, you can concentrate on those detailed sections that are of direct relevance. 2001 15

Introduction The BlueStack User Guide contains the following sections: Introduction on page 15 An overview of the BlueStack User Guide Overview on page 18 An overview of BlueStack and its various components. BlueStack Application Interface on page 37 RFCOMM on page 72 Service Discovery Protocol on page 111 TCS on page 136 L2CAP on page 194 Device Manager on page 219 HCI Transport on page 293 Annex A Writing a Port Entity on page 302 Annex B Error Codes on page 313 Annex C Changes in this version on page 315 Glossary on page 315 An overview of the BlueStack Application Interface and an introduction to the API. An overview of RFCOMM - a protocol that provides serial port emulation over the L2CAP protocol - and an introduction to its API. An overview of SDP and an introduction to its API. An overview of TCS the Telephony Control Specification (also know as TCS binary) - and an introduction to its API. An overview of L2CAP - the Logical Link Control and Adaptation Protocol - and an introduction to its API. An overview of the Device Manager - the management functions that relate to the Management aspects of Bluetooth. An introduction to the DM API is also provided. An overview of the HCI transport function and an introduction to its associated APIs. A description of the process of writing a Port Entity, along with a simple model. A list of the error codes that BlueStack can return at its API s A list of the changes made to this document since its last formal release. A list of terms and acronyms associated with BlueStack, which have been used throughout this document. 1.3 Conventions The following conventions are used in the BlueStack User Guide: Narrative text is always in the Arial font. Example C code is in the Courier New font. Note: Where possible, the example C code can be compiled and executed. The Times New Roman font is used for illustrative text, for example pseudo code. This text is also indented. Italicized text is used to indicate a note of explanation and is accompanied with the note symbol. The warning symbol is used to draw to the reader s attention where a situation could occur that could result in an undesirable side effect. This is accompanied by text in bold. 2001 16

Introduction The light bulb symbol is used to indicate an idea or hint that the reader may find useful. This text is also italicized. The C code includes both source code (.c) and header (.h) files. The header files: ΠΠdeclare all the necessary information to provide the interface to the functionality provided by an identically named.c file. define the interface parameters ( primitives ) of a protocol layer interface. For all files there is a naming convention adopted whereby the file is preceded with an identifier that shows the owning layer. For example l2cap_prim.h is the primitive header file for L2CAP. Common files are not preceded with an identifier. There are a number of different product s that can be realised using BlueStack. Within the manual the following symbols are used to identify sections that are of particular relevance to product designers. 1.3.1 Getting More Information The Bluetooth website, www.bluetooth.com, contains the Bluetooth specification, profiles and other documents relevant to Bluetooth. General information regarding BlueStack, Proto Developer for BlueStack 1, Interface Express 2 and other Bluetooth products from Mezoe can be found on the Mezoe website www.mezoe.com. Technical support is available to licensees of BlueStack. The email address is bluetooth@mezoe.com. Cambridge Consultants Ltd. can provide design services on a contract basis to those people requiring professional assistance with the design and/or development of Bluetooth products. For further information, visit the CCL website: www.cambridge-consultants.com. Further information on the BlueCore single-chip solution, which is used in some examples in this manual, can be obtained from Cambridge Silicon Radio, www.csr.com. 1 Proto Developer is a software toolkit to assist you developing with BlueStack. 2 Interface Express provides an application abstraction for BlueStack tailored to the Bluetooth profiles. It also provides Bluetooth management functions that expand the capability of the BlueStack Device Manager. 2001 17

Overview 2 Overview This chapter introduces the Bluetooth protocol stack and the BlueStack layers. The different s of products that can incorporate BlueStack as a component are also discussed. It contains the following sections: ΠIntroducing BlueStack on page 18 ΠBlueStack as a Software Component on page 19 ΠThe Application Interface to BlueStack on page 23 ΠBlueStack Layers on page 26 ΠInternal Communications Model Adopted for BlueStack on page 29 ΠError Handling and Debug Facilities on page 34 ΠRegistration and phandles on page 33 ΠManagement Entity on page 34 ΠPartitioning on page 36 ΠPorting and Building on page 36 2.1 Introducing BlueStack The layered model proposed by the Bluetooth Special Interest Group (SIG) is shown in Figure 2-1. The shaded boxes indicate the layers defined in version 1.1 of the Bluetooth specification. Figure 2-1: Bluetooth Protocol Stack as Specified by the Bluetooth SIG 2001 18

Overview BlueStack is a software implementation in C of the Bluetooth protocol stack, as shown in Figure 2-2 on page 19. It has been designed to be applicable to a wide range of Bluetooth applications. It does not include Obex 1, WAP, VCal or VCard. TCS Binary RFCOMM SDP L2CAP Device Mgr HCI Top HCI Upper driver HCI lower driver HCI bottom Link Manager Baseband and RF Figure 2-2: BlueStack Protocols Layers BlueStack introduces the Device Manager. This provides a number of stack management functions, such as security management, and allows access to the HCI command and event interface. 2.2 BlueStack as a Software Component BlueStack is a software component that is designed to allow product developers to incorporate Bluetooth functionality within their products. BlueStack is supplied with the following elements: Device Manager (DM) SDP RFCOMM TCS L2CAP HCI Top HCI Upper Driver (H:4 or BCSP) Scheduler services 1 Supplied as part of Interface Express from Mezoe 2001 19

Overview BlueStack is intended to be used in conjunction with Bluetooth hardware. Since the HCI is a standard interface, BlueStack works with Bluetooth hardware from a range of silicon vendors. The BlueStack HCI Bottom and Link Manager are not supplied as standard as part of BlueStack. HCI Bottom and the Link Manager have been implemented for the BlueCore 1 single chip device from Cambridge Silicon Radio, however they can be ported to other silicon vendors host controller devices please contact Mezoe at Bluetooth@mezoe.com for further information if you need to incorporate the BlueStack Link Manager in your design and wish to purchase it. See also page 26. As a software component, BlueStack requires integrating with other software to realise a complete product. Typically, this software is some form of application. It may be an existing application, or a completely new application. The integration model adopted for BlueStack is based on integrating the stack with an application. The integration can be carried out in an integration layer, which sits between the application and BlueStack. An example of such an integration layer is defined in the serial port profile, the Port Entity. This sits between the Application and RFCOMM. Application Layer Application BT App Integration Layer Port Entity Application Management Entity Profile Specific Layer RFCOMM Bluetooth Generic Stack Layers SDP L2CAP and Device Manager HCI Link Manager Baseband and Link Control Figure 2-3: Layers Required in an Application Running over Bluetooth RFCOMM is a profile specific layer. For example, when developing a Bluetooth cordless telephone that meets the interoperability requirements laid down in the Cordless Telephony profile, TCS binary would be used as the profile specific layer, and not RFCOMM. The examples in this User Guide use applications that run over RFCOMM. In Figure 2-3 RFCOMM is the Port Entity - this is the integration layer between RFCOMM and the application. When the application is wholly new, the application could be designed to interface directly to the RFCOMM API. However, in many cases the application already exists, 1 BlueCore is a Trademark of Cambridge Silicon Radio Ltd. 2001 20

Overview so the Port Entity is introduced to adapt the RFCOMM API to the form required by the application. The integration layer can also provide the adaptation between the application s environment and the BlueStack operating environment. BlueStack is designed to be portable. Part of the porting decision that a designer must make is whether to wholly integrate each of the host-resident software subsystems ( layers ) into the host operating system. However, an easier alternative is to take the environment of BlueStack - the scheduler and memory manager - and to port them with the host layers onto the host. Porting is dealt with in detail in the document BlueStack Porting Guide. Access to the BlueStack operating environment services, and hence to the BlueStack APIs, is via the interface defined in the file bluestack.h. This is referred to as the Application Interface to BlueStack and is further described in the section The Application Interface to BlueStack on page 23. Application and Integration Layer RFCOMM Lib SDP Lib DM Lib bluestack.h RFCOMM SDP BlueStack Operating Environment L2CAP Device Mgr HCI Top Figure 2-4: Showing the relationship between the Application Interface to BlueStack (bluestack.h) and the Interface Library Functions. The application can access the APIs directly, using the operating environment services provided by bluestack.h, or can access the APIs using the Interface Library Functions. The relationship between the Application Interface and the Interface Library Functions is shown in Figure 2-4. The Interface Library Functions are described further on page 32. The exact integration approach taken also depends on the of product being developed. For example, performance will be different depending on the integration approach adopted. Broadly speaking, there are three categories of products that designers might consider: ΠΠtwo-processor standard solutions involving a host and host controller, where the higher layers have to be ported to and implemented on the host, the physical split at the Bluetooth - defined HCI (for example, a PC-based application) two-processor embedded solutions where the split between host and embedded (host) controller does not take place at the HCI (for example, an embedded host with limited resources, such as a mobile phone) 2001 21

Overview Πwholly embedded single processor solutions, where there is no external host, for example, a wireless headset The protocol layer models for the different categories can be represented as shown in Figure 2-5. Application Port Entity RFCOMM Service Discovery L2CAP HCI Device Manager Application Port Entity Application APPLICATION INTERFACE RFCOMM SDP RFCOMM SDP L2CAP Device Manager L2CAP Device Manager HCI HCI HCI LINK MANAGER LINK MANAGER Drivers LINK MANAGER BASEBAND and RF BASEBAND and RF Hardware BASEBAND and RF Standard Two-Processor Architecture Embedded Two-Processor Architecture Wholly-Embedded Single- Processor Architecture Figure 2-5: Three Integration Approaches Illustrated 2.2.1 Standard Two-Processor Solution For the standard two-processor solution, where the split between higher and lower layers of the stack takes place at the HCI, it is assumed that the host is a personal computer of some description. However, in general this category can include any computing platform with communications capability that is not resource limited. 2.2.2 Embedded Two-Processor Solution The embedded two-processor category is a feature of BlueStack demonstrated by BlueCore. This allows products to be designed that incorporate Bluetooth, where the host is resource limited and cannot readily support the addition of the Bluetooth functionality. One such example is a mobile phone; not all mobile phones have the spare resources to readily implement additional protocol stacks. 2.2.3 Wholly Embedded Solution The wholly embedded solution, for example a single chip Bluetooth product, also shows where the additional hardware drivers sit within the architecture. One example is of a cordless headset, however the model is equally applicable to any small wireless device that would benefit from a single processor solution. 2001 22

Overview 2.3 The Application Interface to BlueStack The application interface to BlueStack is defined in the file bluestack.h. This file #includes all the header files required to define the application interfaces that are needed to access the individual layer APIs. An overview of the individual layers is given in the section BlueStack Layers that starts on page 26. The services provided via this interface allow the application to: initialise the scheduler and BlueStack access the memory management functions configure the driver for the HCI transport layer use the scheduler services such as message passing and timed events. This section provides an overview for each of these services. A full description of the functions that comprise this interface can be found in the section BlueStack Application Interface that starts on page 37. The same application interface is used both for the portable code of BlueStack, and the BlueStack library supplied with Proto Developer. This allows users to develop code using Proto Developer, in conjunction with the Microsoft Developer Studio and Visual C++ tools. Developing products using Proto Developer is described in the Proto Developer User Guide. 2.3.1 Scheduler and BlueStack Initialisation The scheduler and BlueStack initialisation services allow the application to control the start up of the scheduler and BlueStack. Specifically, the application: initialises the scheduler initialises the HCI transport driver configures BlueStack and starts the scheduler running. The configuration of BlueStack controls which BlueStack layers have been implemented on the host. This configuration code does NOT control the configuration of any higher layers that are implemented in firmware on the host controller device. Hence the configuration of the layers on the host must reflect the configuration of the firmware on the host controller. If there is a mis-match in the configuration code between the host and the host controller then the protocol software may behave in a unpredictable manner. Configuring BlueStack via the Application Interface does not control which layers are present within the build, and which are absent. For example, if an application requires RFCOMM and not TCS Binary, then it is possible to build BlueStack without TCS Binary, thus saving memory. In this case, if any configuration settings are made for TCS Binary via the Application Interface, then they will be ignored. Additionally, the dynamic configuration of the resources assigned to the memory manager can be selected, provided that this option has been set up by use of the compiler flag PMALLOC_DYNAMIC_LINK. Further configuration options allow the protection of tasks using mutex. 2001 23

Overview The function calls are described in detail in the section BlueStack Application Interface on page 37. Within that section is an example scenario for Scheduler and BlueStack Initialisation on page 69. 2.3.2 Memory Management Functions The memory manager is a library that provides a pool of memory blocks that are available for the dynamic allocation of storage. The memory management functions primarily allow the application to access the same memory management services that the BlueStack protocol software uses. Thus an application can allocate, using pmalloc(), and free memory blocks, using pfree(); typically allocating memory blocks for downstream messages and freeing the memory blocks of received upstream messages once the data has been dealt with (consumed). The memory manager services also include a number of utility functions that: allocate memory and set the contents to zero, and report the memory pool status. Optionally, the memory pool configuration can be modified dynamically during BlueStack initialisation as described on page 44. With the source code portable version of BlueStack, this task is normally carried out by editing the appropriate files prior to building the code. Further details are given in the document BlueStack Porting Guide. The memory manager library is not a true malloc()-style memory allocator - it does not obtain memory from any underlying operating system nor does it perform defragmentation of returned memory. 2.3.3 HCI Transport Driver Configuration The HCI Transport driver configuration allows the application to set up the driver for the HCI Transport. The functions available via the Application Interface allow the application to: find the identifier for the next available driver, select a driver, initialise the selected driver, find the identifier of any installed drivers, then query for a specific driver, obtain the driver s name and its description and obtain the identifier of a driver from its name. The HCI Transport itself is described in the section HCI Transport on page 293 2001 24

Overview 2.3.4 Scheduler Services Tbe BlueStack protocol software uses a lightweight scheduler to co-ordinate the execution of the stack layers. The scheduler has many similarities to a STREAMS 1 scheduler and is therefore well suited for use with protocol stacks. The scheduler is designed to be portable. There are two options for the porting of the scheduler, either as the sole operating system or as an adaptation layer to work within another operating system environment. The scheduler provides a single-threaded co-operative non pre-emptive multi-tasking environment. This places a requirement on the programmers to ensure that the length of any single task execution time is as short as possible so that control is returned to the scheduler as soon as possible. If tasks take too long to execute, it results in buffer overflows, which could cause the stack to miss events. Where there is a possibility that a single task may take too long to execute, it can usually be broken down into several shorter tasks. In this case, the software module posts a message back to itself via the scheduler queue, to ensure that the scheduler calls it again to continue the execution later. A direct consequence of the use of this simple scheduler is that there can be no blocking calls. These cause the stack to halt. The BlueStack interface philosophy follows on from the use of the scheduler; the APIs to the layers cannot block. A message passing method is used where a message is sent to a particular task via the scheduler, using a queue identifier as the destination. Queue identifiers are set up for the tasks at build time and are part of the scheduler configuration. The protocol stack layer queues are pre-assigned to tasks at build time. Queue identifiers are also referred to within the software as protocol handles, or phandles. For the higher layers of BlueStack, a registration procedure is used whereby the phandle of the upper layer is registered with the lower layer before communication starts. This is to allow the dynamic configuration of protocol stacks. Phandles are dealt with in detail in Registration and phandles on page 33. The scheduler executes the tasks that have messages pending. It is up to the software module to pull the message or messages from the queue and to act on them. The result of this is that the BlueStack protocol stack is message driven. The scheduler provides timer support. Timer support is hardware dependent and any port to a different platform needs to take this fact into consideration. 1 STREAMS was originally developed as a framework for communications services under Unix. 2001 25

Overview 2.4 BlueStack Layers This section provides an overview for each of the BlueStack layers. Within BlueStack, the protocol layers above the HCI: L2CAP, SDP, RFCOMM and Device Manager, are referred to as the Higher Layers and the layers below the HCI: Link Manager and Link Controller, are referred to as the Lower Layers. 2.4.1 Link Manager The Link Manager implements the Link Management Protocol (LMP) as defined by the Bluetooth SIG. The Link Manager is not supplied as standard with BlueStack and is included here only for completeness. The Link Manager is responsible for the establishment of Asynchronous ConnectionLess (ACL) and Synchronous Connection Oriented (SCO) links and as a consequence, is also responsible for both Paging and Page Scanning. Similarly, it is responsible for the initiation and control of Inquiry and Inquiry Scanning, plus Hold, Sniff and Park modes. Authentication and encryption is controlled by the Link Manager, which includes the implementation of the authentication algorithms. The Link Manager also implements the event filters. Event filters are mechanisms specified by the Bluetooth SIG to allow automatic link establishment without reference to the higher layers. The event filters constrain which links can be established without higher layer intervention. There is no direct API provided for the control of the Link Manager from the application. Control of the Link Manager from the application may be achieved indirectly using the HCI calls that are available via the Device Manager API. The Link Manager layer is not covered in detail in this User Guide. 2.4.2 L2CAP L2CAP implements the Logical Link Control and Adaptation Protocol (L2CAP) as defined by the Bluetooth SIG. The purpose of L2CAP is to provide connection oriented and connectionless data services to higher layer protocols. In order to do this, it provides: ΠΠΠmultiplexing of higher layer protocols segmentation and re-assembly of large data packets establishment and maintenance of logical connections between L2CAP entities Although the L2CAP protocol layer is used by both SDP and RFCOMM, it can also support other services above it. Therefore, there is an API defined to allow developers to use L2CAP with transport services other than RFCOMM applications. L2CAP is probably of little interest to developers who are developing applications that only use RFCOMM and SDP. 2.4.3 Device Manager For BlueStack, the Bluetooth protocol model has been expanded to include the Device Manager. This is part of the management entity, which is discussed in more detail later in this overview (Management Entity on page 34). The Device Manager is a collection of functions that relate to the management aspects of Bluetooth. These functions include resource management, which is responsible for ensuring that the available resources (typically at the air interface) are not over-allocated to the different applications, which can all make service requests independently of each other. 2001 26

Overview Device specific (silicon vendor dependent) management is not a function of the Device Manager. However the HCI interface can be readily extended to incorporate the required functionality and the Management Entity may interface directly to the extension. The Device Manager API is provided to allow more sophisticated control of the Bluetooth stack. This is an API that allows Bluetooth-aware applications to exploit the full capabilities of Bluetooth. For example, Bluetooth Inquiries should be handled via this API. It is not necessary to write an integration layer that explicitly uses the HCI commands via the Device Manager interface much of the service provision is managed by the Device Manager in response to requests made to L2CAP. 2.4.4 Service Discovery SDP is the implementation of the Service Discovery Protocol, as defined by the Bluetooth SIG. It consists of the Service Discovery Database for the device and subsequently, the Service Discovery Server and the Service Discovery Client. The Service Discovery API provides both Server and Client interfaces. The Server interface is used for the registration of services in the Service Discovery Database. The local Client interface allows an application, sometimes referred to as the Service Discovery Application, to browse for services on a remote device. SDP does not include this application. 2.4.5 RFCOMM RFCOMM implements the RFCOMM protocol as defined by the Bluetooth SIG. RFCOMM is a protocol that provides an emulation of serial ports over the L2CAP protocol, including the transfer of the state of non-data circuits, for example RS-232 Clear to Send (CTS). The RFCOMM architecture supports two device s (see Figure 2-6): ΠΠType 1 is a communication end point, such as a computer. Type 2 is a device that is part of a communication segment such as a modem. The Port Emulation Entity (PEE) maps a system specific communication interface (API) to the RFCOMM services. The Port Proxy Entity (PPE) relays data from RFCOMM to an external serial interface, for example RS-232, linked to a Data Communication Equipment (DCE), such as a modem. 2001 27