蓝牙耳机编程流程-HANDESET Programmers Guide

蓝牙耳机编程流程-HANDESET Programmers Guide HANDESET Programmers Guide 洪林整理HANDESET Programmers Guide1. IntroductionHeadset profile is used to enable wireless connectivity amongBluetooth enabled Headsets, PCs and the cellular phones.2. Concepts2.1 USAGE (用法)Two use cases are presented here for understanding the AG and HS roles. Note that these cases are not comprehensive.Incoming call1 Incoming call arrives at a cellular phone connected to a mobile network.2 The cellular phone acting as an AG indicates this call arrival toa Headset. This is typically perceived as a ring on the HS.3 The user accepts the incoming call, by pressing a button on the HS.第 1 页共 20 页HANDESET Programmers Guide 洪林整理4 The AG on receiving this acceptance routes the audio data from the network to HS. Outgoing call1 An user dials a number using a cellular phone (AG).2 Upon successful connection, the user by pressing a button on theHS initiates a transfer of the audio data from the cell phone to the HS.Note:1 Headset's typically have a user interface by which intentions such as call accept, call transfer are indicated to the AG.2 The word button used above is a simile for any such user interface3 IMPORTANT: Although the word call is frequently used in this document, it shall be read as 'Audio connection'. This is because the AG may treat the HS as the input or output audio port for purposes other than call processing (such as tunes, beeps, alarms, etc..).2.2 控制路径和数据路径1, A Control path typically transmits commands and responsesrelating to a profile and the Data path is typically used to transmit voice data2A Control path should be established prior to the establishment of the Data path.3 The existence of a Data path is optional4. In the context of the Headset profile commands and responses relating to call acceptance, audio data transfer, volume control etc.. are exchanged between the AG and HS over the Control path and the Data path is used to transfer audio (voice) data between the AG and the HS2.3 MODULEThe profile implementation consists of three modules. These are outlined below.This provides the serial port interface that both HS and AG use to SPChannel establish/release Control and Data paths. (See SPChannel programmers guide for details).Implementation of the HS portion of the profile; used by applications Headset (HS) residing on the HS.Implementation of the AG portion of the profile; used by applications Audio-Gateway (AG) residing on the AG.第 2 页共 20 页HANDESET Programmers Guide 洪林整理2.4 Application stateThe Headset API is stateless in nature. This means that the application has to keep track of states.The possible states of an application (with respect to the Headset profile) are typicallyState DescriptionNOT Here the Control path is not established. CONNECTEDHere the Control path is established but the Data path CONNECTED is not.The Data path is also established here and is being used IN_CALL to stream voice the AG to the HS.2.5 Establishment and release of Control and Data pathsThe following matrix specifies the correlation between theControl/Data paths and the roles as per the Headset profile specification.Action Establish ReleaseControl HS or AG AG Path Data AG AG第 3 页共 20 页HANDESET Programmers Guide 洪林整理i.e.1 The Control path can be established either by the HS or AG while its release can be performed only by the AG.2 The Data path can be established and released only by the AG2.6 SPChannel APIThe SPChannel API that provides a means to establish and release Control and Data paths is used by the Headset API. The reader is recommended to read the SPChannel programmers guide before proceeding further.2.7 Headset API usageFrom the HS endHS initializationTo accept an incoming call.To transfer the call from the AG to the HS.To terminate the call.To notify AG about speaker and microphone volume levels.Proprietary commandsHS un-initializationNote that the HS initialization and un-initialization are not necessarily requirements but have been included here for the sake of completeness of the API usage.From the AG endAG initializationTo notify the HS of an incoming call.To transfer the call from the HS to the AG.To control the speaker and microphone volume levels of the HS.Proprietary unsolicited result codesAG un-initialization2.8 Button press handlingThe Headset specification uses the word 'User initiated action' to mean an indication received from the user (typically a button press, or a GUI click etc..) to perform a suitable action. The第 4 页共 20 页HANDESET Programmers Guide 洪林整理suitable action in the context HS in the Headset specification is either a call accept, call transfer or call terminate. Thus the same'User initiated action' that is conveyed by the HS to the AG is interpreted differently. This is based on the states of the HS and AG applications that are currently interaction with each other.The HS_SendButtonPress function of the HS API is used to model this 'Use initiated action'. We shall now look at what it means to handle the button press at theHeadset end andGateway end3. RequirementsThe requirements on the HS and AG units of this profile are statedin the table below.Requirement DescriptionAbility to establish a connection in order to treat the Incoming audio connection HS as an output audio port of the AG.Ability to establish a connection in order to treat the Outgoing audio connection HS as an input audio port of the AG.Audio connection transfer Transferring the audio between the HS and AG.Remote audio volume control Ability of the AG to adjust the volumelevel on the HS.4. API UsageThis section presents the usage of headset (HS and AG) API function. Example use case scenarios are presented here to highlight API usage.4.1 Usage of HS APIThe usage of the HS API is presented in the following sections.第 5 页共 20 页HANDESET Programmers Guide 洪林整理 4.1.1 HS initialization The HS application must first initialize the HS profile. This is done asfollows:Establish a SPChannel Control pathUse the active (established) SPChannel handle to create (initialize) the HS_Handle.This HF_Handle will be used in all the other calls of the HS API.Note that whether the application is listening or connecting, successful establishment of aControl path will be indicated using the spchannel_open_cfm callback.4.1.2 To accept an incoming call (I)Here we present the case on how the HS accepts an incoming call.This is accomplished as follows: HS waits for an incoming Control path establishment by the AG.HS receives the RING code on the Control path thatindicates that the HS could perform a local ring on the headphonethat there is a incoming callUser at HS presses a button to signal call acceptance of the incoming call. This signal is sentto the AG.HS receives a confirmation (response) from the AG for the call accept.HS receives a Data path establishment indication (the Data path being initiated by the AG).Voice data is received on the Data path and rendered on the headphone appropriately.第 6 页共 20 页HANDESET Programmers Guide 洪林整理4.1.3 To accept an incoming call (II)Here we present another case by which the HS accepts an incoming call.This is accomplished as follows: HS waits for an incoming Control path establishment by the AG.HS receives the RING code on the Control path thatindicates that the HS could perform a local ring on the headphonethat there is a incoming callHS receives a Data path establishment indication (the Data path being initiated by the AG).A ring tone is communicated by the AG to the HS using a in-band signal on the Data pathestablished earlier.User at HS presses a button to signal acceptance of the incoming call. This signal is sent tothe AG.HS receives a confirmation from the AG for the call accept sent via the button press at HS.Voice data is received on the Data path and rendered on the headphone appropriately.第 7 页共 20 页HANDESET Programmers Guide 洪林整理4.1.4 Call transfer from AG to HS Here we present a case by whichthe HS transfers a call from the AG to itself (when the call was being attended at the AG). This is accomplished as follows: User at HS presses a button to signal acceptance of the call. This causes the followingthings to happen.HS initiates a Control path establishment to the AG.After which the button press is communicated to the AG.The AG responds to the button press indication with a positive response.HS then receives a Data path establishment indication (the Data path being initiated by theAG.Voice data is received on the Data path and rendered on the headphone appropriately.第 8 页共 20 页HANDESET Programmers Guide 洪林整理4.1.5 Call terminationGiven that the Control path and Data path have been established and voice data is streaming from the AG to the HS via the Data path; the HS can terminate the call as follows: User presses the button, this leads to the button press command being sent from the HS tothe AGUpon reception of positive confirmation, the HS waits for the AG torelease the Data pathrelease the Control path第 9 页共 20 页HANDESET Programmers Guide 洪林整理4.1.6 To notify AG about current volume levelsThe HS typically informs the AG of the volume levels of the speaker and microphone soon after the establishment of the Control path as follows:Issue the command intimating the AG of the current speaker volume level.Receive a confirmation for the same from the AG.第 10 页共 20 页HANDESET Programmers Guide 洪林整理4.1.7 Proprietary commandsIn certain cases the HS may wish to issue commands to the AG thatare not part of the Headset specification. This is typically the case when the manufacturer of the HS and AG are the same, and these devices would like to communicate some implementation specific information between them. In such cases the API function HS_SendVendorCMD can be used. This is used to send commands from the HS to the AG.The command should be formatted as per the AT command specification.Response from the AG can be received as usual via the hs_cmd_status callback4.1.8 Hs un-initializationThe HS application must finally un-initialize the HS profile. This should be done only after the Control and Data paths created using the SPChannel have been released successfully. t_hsapp_info *puHSAppInfo= ....;uResult = HS_Delete (puHSAppInfo->hHeadset);if (uResult == E_GENERIC__OK){/* HS API successfully uninitialized */puHSAppInfo->hHeadset = 0; /* as this becomes invalid now */第 11 页共 20 页HANDESET Programmers Guide 洪林整理....}else{/* Handle error appropriately */....}4.2 Usage of Hs/AG API 4.2.1 AG initialization The AG application must first initialize the AG profile. This is done as follows:4.2.2 To notify HS of an incoming call (I)Here we present the case on how the AG intimates the HS of an incoming call. This isaccomplished as follows:AG initiates a Control path establishment with the HS.Receives intimation that the Control path was set up successfully.AG sends the RING code on the Control path thatindicates t hat the HS could perform a local ring on the headphonethat there is a incoming callAG receives a button press indication signaling call acceptance by the HS.第 12 页共 20 页HANDESET Programmers Guide 洪林整理AG acknowledges this call acceptance.AG establishes the Data path with the HS. (see Control/Data path establishment/release).AG forwards voice data received from the network to the HS on the Data path./** (a) AG initates a Control path establishment with the HS.*/spchannel_config_info uConfInfo = {0};uConfInfo.uRemoteBdaddr = .... /* bluetooth address of the HS */ uConfInfo.iDlc = ....; /* the dlc at which the HS service * is offered. This is found through* service discovery */ uConfInfo.bStartScoServer = BT_FALSE;/* As AG always initiates Data path connections,* we dont need to start* the sco server at the AG */ uConfInfo.uCallbackInfo = .... /* spchannel callbacks */;第 13 页共 20 页HANDESET Programmers Guide 洪林整理uConfInfo.pvAppContext = .... /* application cookie */uResult = SPChannel_Open(hDeviceContext,&uConfInfo,&puAGAppInfo->hConnectionHandle); if (uResult == E_GENERIC__OK){/** Connection establishement initiated sucessfully*/....}else{/** handle error appropriately*/....}/** (b) Receives intimation that the Control path was set up successfully.*/voidSPChannelOpenCfm /* of type spchannel_open_cfm, see SPChannel API */ (SPChannel_Handle hSPChannel,spchannel_session_status_info *puConnectCfmInfo,void *pvAppContext){t_result uResult;t_agapp_info *puAGAppInfo = (t_agapp_info *)pvAppContext;if (puConnectCfmInfo->uStatus == E_SPCHANNEL__SESSION_CONNECTED) {/** Control path has been established successfully* Create the AG_Handle using AG_Create as before.*/puAGAppInfo->iState = CONNECTED;..../** (c) AG sends the RING code on the Control path that*/uResult = AG_Ring(puAGAppInfo->hAudioGateway);第 14 页共 20 页HANDESET Programmers Guide 洪林整理if (uResult == E_GENERIC__OK){/* RING code successfully send */....}....}....}/** (d) AG receives a button press indication signaling call acceptance by the* HS.*/voidOnButtonPress /* of type ag_button_press_ind */(AG_Handle hAudioGateway,void *pvAppContext){t_result uResult;t_agapp_info *puAGAppInfo = (t_agapp_info *)pvAppContext;/* send a +ve ack for this call accept */uResult = AG_SendCmdACK (puAGAppInfo.hGateway, BT_TRUE);if (uResult == E_GENERIC__OK){/* response sent successfully */puAGAppInfo->iState = IN_CALL;....}....}/** (f) AG establishes the Data path establishement with the HS. (see TODO:* Link Roles and Control/Data path establishment/release).*/....uResult = SPChannel_ScoOpen (puAGAppInfo->hConnectionHandle); if (uResult == E_GENERIC__OK){/* successfully initiated Data path establishement */....}第 15 页共 20 页HANDESET Programmers Guide 洪林整理..../** AG receives confirmation of the Data path establishment* through this callback*/voidOnSPChannelDataPathStatusInd /* of type spchannel_sco_status_ind, * see SPChannel API */(SPChannel_Handle hSPChannel,spchannel_sco_status_info *puStatusInfo,void *pvAppContext){t_agapp_info *puAGAppInfo = (t_agapp_info *)pvAppContext;if (puStatusInfo->uStatus == E_SPCHANNEL__SCO_CONNECTED){/** Data path has been established*/puAGAppInfo->iDataPathEstb = 1;....}....}/** (g) AG forwards voice data received from the network to the HS on the* Data path.*//** Assume that the following function is a callback that is invoked * whenever voice data is received from the (telecom) network*/voidOnNWVoiceDataArrival(....,uint8 *pucVoiceData){t_result uResult;t_agapp_info *puAGAppInfo = ....;/** Format the voice data appropriately*/第 16 页共 20 页HANDESET Programmers Guide 洪林整理{....t_data_desc *puDataToHS = ....;uResult = SPChannel_SendScoData(puAGAppInfo->hConnectionHandle, puDataToHS);....}....}4.2.3 To notify HS of an incoming call (II)Here we present another way as to how the AG intimates the HS of an incoming call. Thisis accomplished as follows:AG initiates a Control path establishment with the HS.Receives intimation that the Control path was set up successfully.AG establishes the Data path establishment with the HS. (see Roles and Control/Data pathestablishment/release).After successful establishment of the Data path, AG sends a in-band ring tone on the Datapath.AG sends the RING code on the Control path thatindicates that the HS could perform a local ring on the headphonethat there is a incoming callAG receives a button press indication signaling call acceptance by the HS.AG acknowledges this call acceptance.AG forwards voice data received from the network to the HS on the Data path.第 17 页共 20 页HANDESET Programmers Guide 洪林整理Note that the implementation is akin to the 'To notify the HS of an incoming call (I)' except that the Data path is established earlier in order to send an in-band ring. IMPORTANT NOTE: Irrespective of whether the in-band ring tone is sent or not the AG has to send the RING code on the Control path to the HS. This is as per sec 4.2 of the Headset specification4.2.4 Call transfer from HS to AGAssuming that call is currently being received at the HS, the AG (typically upon user initiation) performs the following actions in order to transfer the call from the HS to the AG.1. Initiate release of the Data path2. Upon Data path release, initiate release of the Control path3. Upon release of the Control path, the call is now available to user at the AG.第 18 页共 20 页HANDESET Programmers Guide 洪林整理Note that the steps (1) and (2) are also performed when a call is needed to be terminated.4.2.5 To control volume levels at HS4.2.6 Proprietary unsolicited result codesProprietary unsolicited result codes set from the AG to the HS typically when the AG and HS are from the same manufacturer can be sent from the AG using the AG_SendVendorData function.第 19 页共 20 页HANDESET Programmers Guide 洪林整理4.2.7 AG un-initializationThe AG application must finally un-initialize the AG profile. This should be done only afterthe Control and Data paths created using the SPChannel have been released successfully.t_hsapp_info *puAGAppInfo = ....;uResult = AG_Delete (puAGAppInfo->hGateway);if (uResult == E_GENERIC__OK){/* AG API successfully uninitialized */puAGAppInfo->hGateway = 0; /* as this becomes invalid now */....}else{/* Handle error appropriately */....}第 20 页共 20 页。