Bluetooth HandsFree Profile Support for Windows Mobile 5 - part 2

In our last article, we explored some of the interfaces offered by the Audio Gateway (AG) for developers.
The problem was that some of the mechanisms offered in WinCE to signal the AG core of specific network events are not present in the PPC and Smartphone SDK. In this article, I'll show you how to create a lightweight replacement for the AG without spending two weeks (or more) figuring out what's inside that little "black box" they call the Audio Gateway. Please be aware I've never worked for Microsoft and everything within this article should be considered "as is".

To start, I'll give you some background information on how the AG core is constructed and then I'll share specific details on creating a connection with the Bluetooth device, processing AT commands, and routing audio to the Bluetooth chip.

The AG core consists of 3 modules:

Parser: Once the AG core has established a socket connection with the Bluetooth Headset device, the interactions between the WM5 device and the Bluetooth Headset are signed via the socket connection with AT Commands. The parser' responsibility is to retrieve these messages from the socket, parse them and return them to the Handler module for processing.

Interface: Exposes methods to signal the network states and initiate commands from the services layer. It also listens for incoming Bluetooth device requests that are trying to create a baseband connection, whether synchronously or asynchronously.

Handler: The core module that receives input from both the Interface module and the Parser module and, based on those stimuli and the internal state of the AG core, will respond accordingly, i.e. send AT command responses, create a service level socket connection, an IOCTL call to the audio driver to route voice...etc.

The Meat and Bones of the Parser
The parser is quite simple. After the Handler creates a socket connection with the Bluetooth Headset (I'll talk more about that in the third installment) it passes the connected socket to the Parser module to listen for and receive incoming AT commands. Listed below are the AT commands that are supported by the Bluetooth HandsFree profile and their corresponding general definitions.

"AT+CKPD=200" - Indicates a Bluetooth button press
"AT+VGM=" - Indicates a microphone volume change
"AT+VGS=" - Indicates a speakerphone volume change
"AT+BRSF=" - The Headset is asking what features are supported
"AT+CIND?" - The Headset is asking about the indicators that are signaled
"AT+CIND=?" - The Headset is asking about the test indicators
"AT+CMER=" - The Headset is asking which indicates are registered for updates
"ATA" - When an incoming call has been answered, usually a Bluetooth button press
"AT+CHUP" - When a call has been hung up, usually a Bluetooth button press
"ATD>" - The Headset is requesting the local device to perform a memory dial
"ATD" - The Headset is requesting to dial the number
"AT+BLDN" - The Headset is requesting to perform last number dialed
"AT+CCWA=" - The Headset has enabled call waiting
"AT+CLIP=" - The Headset has enabled CLI (Calling Line Identification)
"AT+VTS=" - The Headset is asking to send DTMF digits
"AT+CHLD=" - The Headset is asking to put the call on Hold
"AT+BVRA=" - The Headset is requesting voice recognition
"ATH" - Call hang-up

Once the parser receives one of these commands, it parses the received buffer for these character sequences and passes the parsed command back to the Handler (discussed later) as an enumeration that the Handler will be able to identify and process.

The Meat and Bones of the Interface Module
The Interface module exposes methods for signaling the Handler of network connections, listens for incoming connections and calls Handler methods of services requests.

Firstly, the Interface layer must ensure that the Bluetooth stack has been started, otherwise there's no point in processing any other commands for the network layer or the services layer. The mechanism in which the underlying layer signals that the Bluetooth stack is fully functional is via waiting on an Event Handle. Here's some code to support this:

#define BTH_NAMEDEVENT_STACK_INITED L"system/events/bluetooth/StackInitialized"
HANDLE btStack = ::OpenEvent( EVENT_ALL_ACCESS, FALSE,BTH_NAMEDEVENT_STACK_INITED );

// m_closeEvent is a previously Created Event to signal other
// waiting threads to stop waiting (created by the developer)

if( btStack && m_closeEvent )
{
    HANDLE waitObjects[] = {btStack, m_closeEvent};
    DWORD result = ::WaitForMultipleObjects( 2, &waitObjects[0], FALSE, INFINITE );
    ::CloseHandle( btStack );
    if( result - WAIT_OBJECT_0 == 0 )
    {
        //The Bluetooth stack is up, signal core module to finish initialization
    }
    else if( 1 == result - WAIT_OBJECT_0 WAIT_FAILED == result )
    {
        // We've been signaled to close, Bluetooth stack is down!
        // Or our application has signaled us to stop waiting
    }
}

Here we wait on the Open Bluetooth Stack Initialized Event or our own pre-created event to indicate either the Bluetooth stack is operational or to exit, since our application is closing too.

This same scheme also works for waiting for a synchronous or asynchronous baseband connection (Which I'll discuss further in the third installment), but instead of waiting on the BTH_NAMEDEVENT_STACK_INITED wstring, we wait on the Opened Event BTH_NAMEDEVENT_CONNECTIONS_CHANGED, as defined below:

#define BTH_NAMEDEVENT_CONNECTIONS_CHANGED L"system/events/bluetooth/ConnectionsChange"

If the Interface module receives a signal of this event, it notifies the Handler module to check its baseband connections for changes.

Aside from the listening for baseband connections, or if the Bluetooth Stack is up, the Interface module also want to process service commands and network layer notifications. So, following the services interface, as mentioned in the previous article, the module needs to support:

Opening audio
Closing audio
Opening a control channel
Closing a control channel
Getting/setting the microphone volume
Getting/setting the speaker volume
Getting/setting the power mode

And these methods simply call the Handler methods for processing (Which I'll talk about more in the third installment).
For reliability, however, a developer can't create a control channel if no Bluetooth device has been paired with the WM5 device (obviously). Also, a developer can't open up a control channel without a fully initialized Interface Module (Bluetooth Stack is operational).
Secondly, you can't open an audio channel if there is no control channel open.

On the Network signaling side, the Interface Module exposes a method call to the network layer, which passes a number to identify the type of network call being signaled. The supported signaling calls are:

#define NETWORK_EVENT_CALL_IN 0x00
#define NETWORK_EVENT_CALL_OUT 0x01
#define NETWORK_EVENT_CALL_CONNECT 0x02
#define NETWORK_EVENT_CALL_DISCONNECT 0x03
#define NETWORK_EVENT_CALL_REJECT 0x04
#define NETWORK_EVENT_CALL_INFO 0x05
#define NETWORK_EVENT_CALL_BUSY 0x06
#define NETWORK_EVENT_RING 0x07

void BthAGOnNetworkEvent( DWORD dwEvent, LPSTR pszParam );

If you're designing the Interface module and the appliction accesses the network layer, you'll have to support these defines and signal your Handler class to handle these events. For more detail on these libraries, visit the MSDN website.

Important Note:
If you're developing the Interface Module alongside Microsoft's Audio Gateway, be sure that you turn off the MS AG in your Interface Module initialization code before doing anything else. If you don't, the Microsoft's AG will interfere with *your* Gateway application. The first article in this series lists code that turn offs the service. Please refer to it for the IOCTL call that corresponds to the service shutdown.

Ok, now we're getting to the really juicy part, The Handler Module. What's ticking underneath that hood, you might ask. In this article, we've explored a system level overview of the AG core and gone into details about the different responsibilities associated with the Parser Module and the Interface Module. But what ties them all together? The Handler module!

Stay tuned for a detailed description of the Handler Module...