This is session 807, Bluetooth In-Depth. And with that, I'd like to introduce Michael Larson, who is the manager of Bluetooth Engineering at Apple. Thanks, Tom. I'd like to welcome everyone to WWDC this week again. I'm here to talk to you about Bluetooth, what kind of code we've written to support Bluetooth, what the APIs that we're going to provide to you in an SDK later this afternoon are, and what you can do by expanding on our support of Bluetooth using our APIs to make applications that support Bluetooth. and use our APIs to make it even better.

I'm going to start off with a brief description of Bluetooth technology, an overview of the technology, including the terms used in the technology, how RF implementations are built up between two devices, and how data gets transferred between the devices. I'll follow that up with an overview of our implementation of Bluetooth technology, including the framework that we provide, and the objects that you can use to use our framework to develop applications.

Also included in that will be our kernel objects that you can use to write drivers for new and special hardware using different transport types that Apple does not provide support for. We'll kick it off with Bluetooth basics, how Bluetooth works, and basic terminology terms for Bluetooth, then go into Apple's implementation, show you how to find devices, query the services that are on those devices, and open the different channel types to transfer data between devices.

So what is Bluetooth? We started looking at Bluetooth some time ago and implementing what we've released now in Preview 2. Bluetooth is a very low-bandwidth, short-range wireless protocol. As you heard in the previous presentation, if you attended that, we intended to be used for peripherals and not as a networking protocol because of its low bandwidth and short range.

In order to get data to transfer over Bluetooth, it happens over a series of layered protocols. At the very bottom, there's a baseband connection. A baseband connection represents the lowest level RF link between two radio devices. On top of this baseband connection to transfer data, there's a protocol called L2CAP.

L2CAP is, we'll go into that a little more in depth later, but it's a basic data transfer protocol. On top of L2CAP, Bluetooth has built a thing called RFCOM. RFCOM is a serial emulation layer. We'll also go into that later. And an additional protocol on top of RFCOM is OBEX. If any of you were involved in the old IR days, you might remember OBEX as it's a protocol left over from those days.

Bluetooth devices are identified by a 6-byte address. It's identical to an Ethernet address. In fact, it's assigned by the same organization. So if you use Apple's preview implementation and the D-Link card, you'll find that the device address that you get for Bluetooth is actually the same as your built-in Ethernet address.

So let's get into some more of the basics of Bluetooth. In order to build connections, there are really two modes a device can be in. A device can be either discoverable or connectable or both. They're really independent states. So what does it mean to be discoverable? When a device is discoverable, a remote device can use what's known as an inquiry to find that device. If you saw the Bluetooth demo in the last presentation, there was an inquiry done there to find all other devices within range. This is a generic mechanism used to find the devices that are within that 30-foot range of Bluetooth connectivity.

So that is a mode that you will put your device in if you want to be able to be found by others. Sometimes that's not a good thing, so we provide the ability to turn that off. For example, cell phones, a lot of times you don't want to be able to be found, but you'd like to connect them. So that takes us into the next aspect of the Bluetooth connectivity, which is connectable.

It's a different concept than discoverable, so that if devices are looking for you and you're connectable, you won't respond to inquiry requests. But if they know about you explicitly through a prior inquiry, or someone's provided you the device address, they will be able to build a connection. This way, you can design a device that can allow connections, but will not be found if someone's trying to just, for example, show up in this hall and find out what other devices are around and cause trouble. So they're mutually exclusive states. You can use those to design devices and design them so that they behave exactly like you would want them to, and users can control that behavior independently.

There are a number of security concepts with Bluetooth. The first one is a paired relationship. If you can create a paired relationship between two different devices so that you no longer have to do some initial setup or ask for passwords each time you connect-- for example, I've paired my Bluetooth laptop with my Bluetooth phone so that all future connections happen without any user intervention.

Pairing works by using a shared secret that's never transmitted across the air. That secret's known as a passkey. So the first time I go to pair my laptop with my phone, I enter the same passkey on both devices. And that passkey is used to create a link key. That link key is stored inside the hardware and also on the computer so it can be provided for future connections without user intervention. Link keys can also be deleted so that if you want to delete that paired relationship with a device, you can do that.

Another security concept with Bluetooth is encryption. A Bluetooth link can require encryption or it cannot require encryption. That's up to the particular service type. An encryption is done inside the hardware. One of the items used to determine the encryption is the link key, so that encryption is very useful for paired devices. The link key is used as a seed to the encryption engine to provide 128-bit encryption for the Bluetooth connection.

That covers the basic introduction to Bluetooth technology, and we're going to cover where we position it here. We really view it on this slide as a peripheral technology using a wireless connection. It doesn't mean that USB and FireWire devices are going away. They have much higher speed, but also have the burden of cables.

This is for very low-bandwidth devices that can really use the cable to be cut. So cell phones are an obvious choice. PDAs are another good choice, and there are several other out there. And that's what we would like to see you guys start to get into and find those other cables to cut and provide some other functionality over Bluetooth.

We released Preview 1 about a month ago at Macworld Tokyo. Preview 2 is going to be released this afternoon and really doesn't add any new profile support but adds some additional UI and polish to what we did in Preview 1. What we support in Preview 1 and also Preview 2 are three primary profiles. The first being dial-up networking. Dial-up networking replaces the IR or serial cable link that would previously exist between a laptop and a cell phone with Bluetooth.

The serial port profile also replaces the cable that would previously exist between a PDA and a laptop. And then object push enables a quick exchange of objects or small files between two Bluetooth-enabled devices. This can be used to quickly exchange a small file about several hundred K or so between a PDA and a laptop or two laptops, or send a V-card to your phone so you don't have to enter it on the keypad.

So let's get into what the Bluetooth stack looks like. At the very bottom of the stack, there's a Bluetooth module. That'll be a hardware device, rather it be a USB device like we have with the D-Link module that we introduced about a month ago, or it's a serial controller, or a PC card, whatever type of transport it is, there's a Bluetooth module. On top of that, there are several other protocols and profiles that are used to talk to that module, and we'll go into those in a little more depth in the following slides.

The first layer that's used to talk to a Bluetooth module is HCI. HCI stands for host controller interface. It's an abstraction to be able to send commands and receive events and transfer data to the radio. So using a well-defined protocol called HCI, we can talk to any type of Bluetooth device over USB or serial or PCI as long as it conforms to the HCI protocol.

And a driver needs to be written underneath this to transmit the data in the HCI format into whatever bus it is. Apple's provided a USB driver. There are currently no other drivers that Apple provides. That's an opportunity for you guys. To go write a serial one if you want to support a serial device or PC card, whatever else there is out there.

On top of HCI, we need a layer, a protocol layer, to transmit data between two devices. This layer is called L2CAP. It's a link control layer to transfer simple data between two devices. Once there's a baseband connection, which is created using an HCI call, you can use L2CAP calls to open independent channels and transfer data between two devices. L2CAP supports a number of things, including different channel types and channel IDs, and one of its primary goals is to segment and reassemble different packets according to the maximum packet size.

On top of L2CAP is RFCOM. RFCOM's primary purpose in life is to make a data channel appear to be a legacy serial port. So it has mechanisms to open multiplex data channels. You can have several channels over an L2CAP channel to a remote device. And on top of that, it adds some primitives to set serial port speeds.

So if you were actually talking to a device that had a real serial port, you could control those speed settings like it were a real serial cable. And an RFCOM channel, or the multiple RFCOM channels, will use a single L2CAP channel as its transport to the remote device.

Kind of a peer to RFCOM in terms of them both using an L2CAP channel is SDP. SDP is a service discovery protocol, and it is used to query remote devices about what services they support. So if you have a remote device that you found through a prior inquiry, and you want to know whether it supports the service you're interested in, you can use SDP to query that device and find out whether it supports it.

You can query it as to whether it supports a serial port profile, and it will respond with all its services that are serial port profile services. Or you can query it as to whether it supports dial-up networking, and it will tell you whether it supports dial-up networking. It also uses an L2CAP channel as its transport, and there's a single L2CAP channel to be used for SDP.

On top of RFCOM, there is OBEX. OBEX, if any of you know it from the IR days, is an HTTP-like protocol, and it transfers simple objects to another device. It uses primitives like PUT and GET to transfer blocks of data. The OBEX protocol is based on the V1.2 version of the IR OBEX specification.

This is an area where Bluetooth has said, there's already something that exists out there in the world that does the data transfer the way we want to. We'll just leverage that and map those rules onto Bluetooth technology rather than IR technology, and we'll get all the other applications that know OBEX for free. OBEX uses an RFCOM channel as its transport because of the similarities between IRTA and serial.

So that's the description of all the Bluetooth protocols and how they're used. It's a brief description. Now, in order to use those on Mac OS X with either Puma or Jaguar, we're releasing a SDK. It should be on the web this afternoon, and the URL will be available later in the presentation. And alongside the SDK, we're also posting Preview Release 2 for the end users that might want to upgrade their software and see what the latest support we have for Bluetooth is.

In terms of the SDK, there's two important things to know. One is it's a superset, a complete superset of Preview Release 2. So if you install the SDK, you do not need Preview Release 2. It's all included there. The SDK installs header files and the frameworks you need to develop applications using Bluetooth, which Preview Release 2 does not install. And there are two separate SDK versions since you guys just got a Jaguar Preview CD. We've developed one that works under Jaguar, and there's a separate one for Puma. So whichever version of the OS you feel comfortable developing for, there's SDKs for both of those.

What is the SDK going to give you? We provide access to a number of APIs through the SDK. The first two are our in-kernel APIs, the HCI controller, which is the bottom block on the stack diagram we just covered, and then the USB HCI controller, which is Apple's specific implementation of an HCI controller to work over USB.

HCI, we'll cover those in-depth in the next slide. There's also a number of user-level APIs that we provide. We provide objects that represent a Bluetooth device, an L2CAP channel, an RF-COM channel, or an OBEX session. We also provide objects that represent the service discovery profile objects that exist between two devices.

Looking at the kernel objects, the first is the IO Bluetooth HCI controller. It's a representation of a generic HCI controller. This is the base class that you want to look at if you want to write an I/O Kit driver for a different type of Bluetooth hardware, i.e. a PC card or something that Apple does not provide. The class is available in the SDK and the documentation is available there as well.

In addition to the base HCI controller, we have a USB HCI controller. If you have a USB bit of hardware that more or less works with our class driver implementation, because our USB driver in the preview release and the SDK is a generic USB class driver, but it adds some additional features like, say, a special LED to show something, you can subclass this to add these special features for your USB device. In terms of what Apple has done support for, Apple's supporting the USB driver, and we have not looked at any other transports now. So if you have hardware that uses the other one, this is a good opportunity to provide the driver for that hardware.

Getting into the user space objects. The way that the Bluetooth API is designed from the user space, it's very object-oriented. There are objects to represent all the different channels and the remote devices on the system. We also provide both a C version and an Objective-C version of the APIs for the Bluetooth stack.

In addition to that, we've also provided some common UI elements so that you can call and don't have to handle things like inquiries or SDP searches. You can just call one of our UI elements, and we will bring up the UI and search for devices and do the service discovery to find exactly the device or the service you're interested in. In order to provide similarity between the C version and the Objective-C version, we've adopted a naming convention, which is shown on the slide. The C version tacks on a ref to the end of what the Objective-C version name would be.

So getting into the IO Bluetooth device. This is the one object in our stack that you can have that really does not need to have a concrete representation behind it. An IO Bluetooth device can be created and can represent a remote device for which there is no connection. These devices can either be created programmatically by code if you know the device address or have saved that off from a previous device search.

In addition to that, this is the root object that you will use to create any type of connection you would like to a remote device. The baseband connection is started from here. You can open L2CAP channels using the device as the root object. You can also open RFCOM channels, and it's used for OBEX session connections. In addition, if you want to do any kind of SDP service searches, the device is really the important part to remember and use to do those service searches.

On top of the device, there's a Bluetooth L2CAP channel. These can exist. I said before that the device is the only one that can exist without a concrete representation behind it. It's really the only one that can be created without a concrete representation behind it. The rest of the channels, like an L2CAP channel or future channels, can exist, but they will have to be created when a concrete channel representation exists. They will exist after the channel goes away behind it, but will return errors for all the calls.

An IO Bluetooth L2CAT channel represents the data conduit between the local device you're running on and a remote device. Using that data conduit, there are commands to open the channel, read and write data to and from the channel, and close the channel. And following the naming convention, there's a C version that tacks on the ref to the name.

On top of L2CAP, we have the IO Bluetooth RF Comp channel. Similarly to L2CAP, there are APIs to open, read, write, or close a channel. There are, in addition, event notifications, and incoming data is considered an event type. But other event types for RFCOM might be changing the serial port speed or some other bits of the serial port emulation things that RFCOM handles and was designed to do. Also, following the naming convention, just tack on the ref to the end of the name to get the C version.

For implementation of the service discovery profile, there are three things that you can do. You can create a service to Vend. If you write an application that's Bluetooth-aware and say you wanted to provide a chat application over Bluetooth, you would create a special chat service and Vend that from your chat application, and that would enter our service database to be Vended for other devices to query.

If you're writing the chat client on another machine, you will use the SDP APIs to go query remote devices and find out if they support the chat service and then exist and what channel that's on. There are a number of SDP-specific classes, including the service record, the service attribute, data element, and UUID.

and their C versions for all those APIs. So a UUID is it's a UUID and the typical, if you've used Core Foundation, they have UUID services. It's a 128-bit value that can be reduced down to 16 or 32 bits to represent a unique service. The Bluetooth Special Interest Group has defined a number of generic UUIDs. For example, serial port has one or dial-up networking has another.

If you were to create a chat service that was your specific one, you would generate your own 128-bit value one and use that to identify the chat service. The data element and service attribute classes are used to extract data from a service record and tell whether that service has the attribute of chat or dial-up networking or whatever other type of service you're looking for.

On top of RF-COM, there's OBEX, which is the generic object exchange. OBEX transfers happen through an OBEX session. There's both a client session object and a service session object that both work over an RF-COM channel. The current API that we're providing in the SDK requires a pretty in-depth knowledge of the OBEX protocol in terms of knowing when to respond to different portions of things. We do plan on releasing a convenience API that will handle a lot of that for you if you don't want to get that in-depth.

In addition to that, we plan to provide some simple file transfer services if you just want to transfer a file from one device to another. That's coming in a future version of the SDK. What is provided in the SDK today are some simple OBEX header parsing utilities and creation utilities. In addition to that, to simplify OBEX, we've provided some vCard or vObject, as we call them, creation utilities, so you can create a vCard or a vCalendar event from code easily.

So you've got your idea that you want to implement over Bluetooth. Now you need to know how to do it. There are three UI elements that you might want to use to either pair with the device, find a particular service, or just find a remote device. These UI objects have common aspects in terms of their ability to filter on different types of devices, so you can find only phones or only laptops or whatever device type you would like. They also have the ability to filter out to only certain services, so if you're only interested in devices that have your chat service as an example, you can filter out only those devices.

The first device is the pairing panel. If any of you had a chance to play with Preview 1, you've probably seen this when you've connected to your Bluetooth phone, if you've done that. This is a common UI element available to any application, which is Bluetooth Aware. You can use this element to find and create a paired device relationship between your computer and a remote device.

The second panel that's available through our API in the SDK is a service search panel. This handles all the aspects of doing the finding remote devices and doing the service searches for those devices. You can tell this panel when you call it to look for certain device types or only certain service types, and it will handle all the SDP transactions for you so you don't have to go learn how to do that code and how to parse out those responses.

All you need to do is provide the service type that you're interested in, and we can filter that out for you. So this will return to you a list of the device and the service that the user selected, and you can go do things on that. We have a code example later that exhibits how this works.

And then the third panel is a device search panel. For example, if you're doing a file transfer application thing or if you want to send a vCard to somebody, you may want to send it to several devices at once. This is a UI panel we've created to allow the user to select one or multiple devices and return those to the application so they can decide how many files to send to remote devices and how to handle that.

Now we have some code examples. What we've done here is the elements in orange, we've highlighted orange to show that it's either an API name or one of the data types that we've defined for Bluetooth use. So the first example we're going to step through here is a C code example. We also have an Objective-C version coming later. And this example uses an RF com channel to open up and transfer data between two devices.

There's really four elements that you will need to do if you want to open a remote connection to a device. The first is a reference to that remote device. The second is the service record to find out what the services are on that device. And if you're dealing with RF com channel, the last two are an RF com channel reference and the ID number of that channel.

So for the first step of finding the device to connect to, the first call is the IO Bluetooth Service Browser Controller Browse Devices. That's our API to bring up the service browser to find all the devices within range and list the services on them. It will return to you a service record that gets filled out based on which service the user selected.

On top of the, one of the calls into the SDP services on a service record will return you exactly which device was selected. Using that call, you can find out what device, what remote device the user selected, and that returns to you an IO Bluetooth device. Once you have the device, you can also query the SDP info that was returned to find out which RF com channel number that service is on. It's an important bit of data to know that you're opening the proper RF com channel.

So once we get to this portion of the slide, we've already got the remote device that we want to talk to, and we have the channel ID of the channel we want to open on that device. So the first step is to create the connection to that remote device. That's the first call that you see up there. That will go and page the remote device. It will answer back, and an RF link will be established between the two devices.

Once we have that initial RF link between the two devices, we need to open the other layered protocols on top of that. If you recall back from the layered slide, on top of ACI there's L2CAP and then RFCOM. If you're interested in the RFCOM channel, we open the L2CAP channel for that automatically for you. All you need to do is request for that channel to be opened. That's the second call you see there. Once you've made that second call, now you have an open RF com channel that you can use to transfer data between two devices.

The next step you must do with RFCOM is to register an incoming listener for that RFCOM channel. That way you will get notified of incoming data or incoming event types over RFCOM. So you register that on the third line there. Also, the fifth line shows the function declaration for that if you're curious.

Then the next step, you now have an open RF comm channel. You can start transferring data. There's an example of the write call. Send data on the write call. You'll get data back on the read or on the event listener. And from there, you've got an open conduit to a remote device.

The next example is the Objective-C version. For those of you who are coming from the next days or have been around OS X for a while, it's just a little different. And to change things around for this example, instead of using RFCOM, we use L2CAP as a different channel type to use. It just looks slightly different.

It's very similar to the C version. The first step is to call the service browser controller. A little different look because it's Objective C, but it's the same idea. Service record browser controller will run. The user will select the device, and it will return that to you in the service record.

Then, using the service record, you can get the remote device that was a part of that service record. You can also, the same way there is a RFCOM channel ID for RFCOM channels, the same concept for L2CAP is called a PSM. So you can get the L2CAP PSM from the service record. And now you have all the information you need to go and open that particular channel for that remote device.

Using that information, slightly different than RFCOM, opening an L2CAP channel automatically handles the opening the baseband connection. So if you're doing L2CAP, we don't need to open the baseband connection ahead of time. That gets handled for us. Just tell the remote device to open a particular RFCOM channel with the parameters we're interested in. That returns to us an L2CAP channel object.

Using that L2CAP channel object, we can now register for incoming data to come into us on a particular data listener, which is my data listener up there. And then we can start writing to the channel. Data will come in on our listener routine, and we've got all the pieces we need to communicate to a remote device over an L2CAP channel.

So as part of the SDK, we've provided a series of sample applications. A lot of them work over OBEX. They're all listed there. OBEX Quick Push is a quick sample application to transfer a file or a vCard or any other type of data from one machine to another. The complete sample code is there.

Obix Sample Send vCard allows you to enter in address and telephone contact information, and it will package that up as a vCard data object and send that to a remote device. Similar, you can enter address book entries onto your Bluetooth phone that way, all sample codes there. The two RFCOM sample applications, the Client Sample and the Server Sample, are actually an RFCOM chat application. They exhibit how to create a service, then that service on your local Bluetooth device, and then the Client Sample exhibits how to connect to a remote Bluetooth device that sends a service you're interested in and open up an RFCOM sample to transfer data back and forth.

In addition to the sample code, we provided object code for two different tools. One thing, if you're doing Bluetooth development, you're really interested in what the data is that's being transferred between the two devices, both HCI commands and events and also the L2CAP or RFCOM data that's being transferred. The Packet Decoder 2 application is just this.

It logs every single HCI command or HCI event as well as all the ACL or L2CAP data being transferred. And it will decode that according to the different specification protocols. Currently, we decode the Service Discovery Protocol, L2CAP protocol, and RFCOM, although we have been thinking about adding decoding options for different protocols as they're needed.

In addition to that, there's also an application called Bluetooth Monitor. If you're developing your Bluetooth code and sometimes the Bluetooth connection remains live because your app crashed or something and you want to go kill that connection, Bluetooth Monitor will list all existing connections and channels between devices, and you can kill off those channels or connections independently. So it's a handy little tool as you're developing Bluetooth stuff when you get into trouble and just want to knock things down and start over again. It can do that for you.

There's some other presentations that touch on Bluetooth. The only other one at WWDC this week was a session just prior to this one. So there's not much you can do about it now other than if you get the DVDs and slide sets, you might want to go look at that one to find out what Apple's future plans are with Bluetooth and also how it integrates with 802.11.

For future contact information, the person to start off your initial contacts with is Tom Weier. He'll be joining me on stage in just a few moments to handle the Q&A, and he was the person who introduced me. In addition to that, we've set up a developer mailing list. The URL is listed there. The entire Bluetooth team will be monitoring that, so feel free to ask questions. Whatever you need there, we'll be monitoring that for what you want from us.

And here are a series of links for more information about Bluetooth. There's a link provided for our SDK that you should be able to download this afternoon. In addition to that, the Bluetooth specifications available online and other specifications which the Bluetooth specification uses are also available online. So if you're looking for any of the specifications referred to in the initial Bluetooth spec, there are some URLs to start looking at.

In addition, as Tom mentioned in the presentation before, we found one book that we really like that simplifies the description of all the Bluetooth stuff. As a specification, it's about 1,600 pages. It's a little dry, a lot to read. Bluetooth Connect without cables simplifies that down to about 250 pages and is a very good description of what Bluetooth is and how to use it.