Kernel Versions

Developers have used the OpenBT source on a wide range of kernel versions, including uCLinux. Because the source is available, people are free to port it to whatever kernel version they require.

The BlueDrekar binaries, on the other hand, are compiled only against certain 2.2.x kernel versions at the time of this writing, so you can’t use them with older or newer kernels.

Hardware Platforms

Developers around the world have used OpenBT on a variety of processor types. This author’s company has used it on ARM and MIPS, as well as x86 processors, and according to the mailing list archives for OpenBT, some people have used it with PowerPCs as well. Again, because you have the source, if you need to port it or even just cross-compile it for a non-x86 platform, you can do so.

With BlueDrekar, you only get the x86 binaries. You don’t have the source unless you apply for a license, so obviously you’re limited to just x86 platforms.

Bluetooth Protocols

Here’s where BlueDrekar starts to catch up. The OpenBT project does not currently support the Synchronous Connection Oriented (SCO) connections used for voice, which is a major drawback. It does include support for an HCI-USB layer, however.

BlueDrekar does have support for SCO already. For BlueDrekar, you can get the source for their HCI-UART module. This is the one part of their stack, which is open source. IBM released this source under GPL with the hope that others could use it as a basis for developing the other HCI link drivers.

SDP Support

The Service Discovery Protocol (SDP) is used by a client device to find out about the services it can use on a server device. An SDP server maintains a database of services; this can be preconfigured (static), or can be built up dynamically as services register with the database system. Once a database is in place, clients send SDP requests to query its contents, and servers reply with SDP responses giving details of services supported and information needed to connect to those services.

SDP is another area where BlueDrekar is ahead of OpenBT. The OpenBT project does provide an SDP server daemon to handle SDP requests from remote devices. However, it does not yet provide an API for local applications to dynamically register themselves in the SDP database. Another disadvantage is that applications must frame their own SDP request packets and parse the resulting SDP responses.

BlueDrekar is much nicer. It also provides a server daemon, but additionally, it has an API for dynamically registering services in the local database as well as handling a lot of the details of SDP. Applications still need to know the basic components of SDP packets, but they don’t have to hand-tool the packets themselves like they do with OpenBT.

API

The OpenBT stack provides a set of device files for applications to use. These are all TTYs (terminals) and follow the standard Linux API for TTY drivers. Stack control is done via blocking ioctl calls. Since there’s no intervening library layer, all of the control I/O is synchronous. There is no event notification aspect of the API.

The BlueDrekar stack provides a library layer and a daemon (referred to collectively as middleware). Although data transfers are handled over standard drivers, control operations are done via library calls. These often employ callback mechanisms for event notification.

License Terms

Licensing is the big issue. The OpenBT project is released under the AXIS OpenBT Stack license. You can see the text of this license at http://developer.axis.com/software/bluetooth/OpenBT_license.txt. Basically, it is the GPL with some additional freedoms. If you write applications that use the stack, they will not fall under the GPL and may remain proprietary. But if you write applications that are a derived work of the applications in the OpenBT source tree, then they will fall under the GPL—unless they have nothing to do with Bluetooth technology. Note that just because the stack is under GPL doesn’t mean applications that use the stack must be. However, if you modify or add SCO support to the stack (for example) then these changes would be under GPL.

BlueDrekar is released under IBM’s Alpha Works license. You can download the binaries for free and write applications that use them, but if you want to see the source or distribute the binaries with a product then, you’ll need extra permissions. According to their Web site, you must be a Bluetooth SIG member to get this additional permission.

 It’s freely available.

 I’m under no restrictions to not discuss any aspect of it.

 I have access to the source, so I understand it much better.

 I’ve used it in the past on several different platforms, for several different kernel versions.

 I’ve contributed to it in the past.

 I think it has the best chance of making it into the standard Linux kernel tree (eventually).

 If I can encourage you to use it and contribute, then I benefit from your use as you can benefit from mine.

Fair Warning

It’s only fair to be perfectly clear on something at this point: the OpenBT stack is a work in progress, and is not feature-complete as a client stack. Here are the big issues, in order of severity:

Also, as with any implementation, the stack still has some bugs—especially when supporting client applications. You can get a list of the current known bugs from the OpenBT Web site on SourceForge.

Nonetheless, OpenBT has one major advantage: the source is open. It goes without saying that one of the reasons I know about all these problems is because I can look in the source and see them. I can also look in the source and fix them.

That being said, let’s talk about the basics of how the OpenBT stack works. From here on, when I use the term Bluetooth driver I’ll be referring to the OpenBT stack. Specifically, I will be referring to version 0.0.2, released in March of 2001.

Investigating the Kernel Module

To load the Bluetooth driver into the kernel, execute the following command in a terminal window as root:

$ insmod bt.o

Now let’s browse through the proc directory and see what just happened. Enter this:

$ cat /proc/devices

One of the char driver entries will be listed as bt. This is our driver. On the same line, you’ll see its major number. This major number uniquely identifies the Bluetooth driver in the kernel. Later, when we look at the Bluetooth device files, we’ll see that their major number matches up with this, effectively binding them to this driver. This is what tells the Linux kernel which driver to invoke when we make system calls like open on those device files.

Now enter this:

$ ls /proc/bt_*

And you’ll see the proc files installed by the driver. Enter this to see some status information on the driver:

$ cat /proc/bt_status

Finally enter this:

$ cat /proc/tty/drivers; cat /proc/tty/ldiscs

The first command lists all the TTY drivers currently registered in the kernel. Ours is now one of them. The second lists all the ldiscs currently registered in the kernel. Note bt_ldisc—that’s ours.

What Exactly Is a TTY?

One way to think of a TTY is as a subclass of a character driver. A TTY implements the same interface as a character driver and then some. In fact, you might think of a TTY as a character driver with an attached filter. The filter sits in the kernel between the TTY and an upper layer. This filter is called an ldisc, or “line discipline.”

So What’s an ldisc?

A line discipline (ldisc) monitors and even modifies the data stream that passes between an upper layer and the TTY. It might do things like look for special control characters in the data stream. It might even reformat the data stream into protocol packets of some kind or other.

One really important feature of the relationship between a TTY and its ldisc is that you can change the ldisc at runtime. In effect, you can swap filters. In the next section, I’ll show you how this affects the Bluetooth driver.

Building Driver Stacks in the Linux Kernel

Figure 6.1 is a simplified diagram of the default TTY driver configuration after you load the bt.o module. You see how both the bt and serial TTY drivers use the N_TTY ldisc as an adapter between themselves and the standard TTY I/O code? The N_TTY ldisc is suitable for console TTY drivers. It does things like scan for control characters in the byte stream. But an application can change any TTY driver’s line discipline by using a special ioctl call. For example, we could have an application change the serial driver’s line discipline to be bt_ldisc instead of N_TTY.

Guess what? That’s exactly how we make the Bluetooth driver talk to a Bluetooth card attached by a serial cable. Figure 6.2 shows a picture of this. The bt_ldisc in effect will route all data to and from the serial port through the Bluetooth driver. That’s where all the parsing and packet assembly will take place.

In summary, line disciplines are important because they allow user-space applications to stack TTY drivers in the kernel. Note that this is exactly how PPP works over a TTY—and therefore RFCOMM devices must be TTY drivers.

Investigating the Bluetooth Device Files

You may have noticed during the installation that at one point you had to create some files in the /dev directory. Take a look at them now by entering:

$ ls -l /dev/ttyBT*

These device files are your application’s interface to the Bluetooth driver. Notice that all the devices have the same major number but different minor numbers (if you’re not sure how to tell, then check the man page for ls). Having the same major number means that the same kernel driver implements them all. The different minor numbers represent different instances of an interface to the kernel driver.

There are two types of Bluetooth device files: data device files and control device files. Table 6.2 shows the main differences between them.

Using the RFCOMM TTY Drivers

The data device files are named /dev/ttyBT0 through /dev/ttyBT6. These are all instances of RFCOMM TTYs. Once they’re opened and connected, they behave exactly like serial ports, as we’ll see later. Only one process at a time can open any individual RFCOMM TTY. All the standard system calls which work over standard character drivers and all of the ioctls, which work over standard TTY drivers, also work over the RFCOMM TTY driver.

The minor number for the RFCOMM TTY’s has special significance to the Bluetooth driver. Each minor number corresponds to a line number used internally by the driver to index a connection session. Each possible RFCOMM or SDP connection, which the driver can make with a remote peer, is represented internally by a session. Since there are seven RFCOMM TTYs, there are seven session “objects” maintained by the driver.

The only trick to using the RFCOMM TTY device files is in understanding the concept of an RFCOMM session. Within the driver, each RFCOMM session has a state machine. The driver indexes sessions internally by a line number. When opening an RFCOMM device file, the line number comes from the minor number of the device file. When connecting to a remote service, you specify the local line number as one of the connection parameters. Figure 6.3 illustrates the state machine for a single session.

In Figure 6.3, you can see the three parameters that specify the state of a session are: whether or not the device file is open, whether or not the TTY is hung up, and whether or not an RFCOMM connection to a remote peer exists. The important points to take away from this are as follows:

One very interesting consequence is that one process can establish an RFCOMM connection on a session without opening its device file, and another process can then open the device file and transfer data across the connection.

Understanding the btd and btduser Applications

The btd application will probably be the most useful for you. The difference between btd and btduser is that btd is meant to work with the kernel mode Bluetooth driver, while btduser works with the user mode Bluetooth driver. Many people prefer btduser since it is less prone to lock up your system if things go badly. However, the OpenBT developers do not support it as well as btd.

For btd you have to install the Bluetooth kernel driver (i.e., insmod bt.o). For btduser, you don’t. Other than that, their usage is basically the same.

The btd application can take a number of different arguments on startup. An example follows. If you’re curious about other arguments besides the one I mention, then look in the sdp.c source file. At the top of the main() routine, you’ll see the argument parsing. From that, you can figure out what the other arguments to btd are. The README that comes with OpenBT talks about starting btd, but it is not always up-to-date. Remember, OpenBT is still early in its development, and often the source code is the best documentation.

Understanding the sdp_Server Application

The sdp_server application provides you with an SDP database server daemon. Once you’ve installed the Bluetooth driver, you can start this daemon and it will automatically receive and respond to SDP queries from remote devices.

If you start the daemon with no arguments, it will automatically use /etc/sdp.xml as the SDP database file and /tmp/sdp_sock as the source of SDP requests. The /tmp/sdp_sock file is a Unix socket created by the btduser application. You can specify a different XML file as the first argument to sdp_server and a different source device as the second argument. Note that if you provide one argument, you must provide the other as well. If you want to use the SDP server when the Bluetooth driver is in kernel mode, then you should specify /proc/sdp_srv as the source of SDP requests.

The following is an example of starting the sdp_daemon with command-line arguments:

$ sdp_daemon /tmp/my_sdp_database.xml /proc/sdp_srv &

Understanding the BluetoothPN Application

This application provides a GUI that displays the SDP database on a remote device. It provides some examples of how to make SDP requests and process their results.

 Two Linux PCs configured to use PPP; one will be the server and one the client.

 Both PCs are connected to Ericsson Bluetooth Developer kits via RS232 to /dev/ttyS0.

 The OpenBT Bluetooth driver is installed in both PCs kernels.

 There us an open terminal window with root permissions on each PC.

 The server should have the “local” and “nodetach” options specified in its /etc/ppp/options file (see man(8) pppd).

 The client should have the “local,” “nodetach,” and “noauth” options specified in its /etc/ppp/options file.

1. On the server:

    $ btd --server --physdev=/dev/ttyS0 --speed=57600 --modem=0

2. On the client:

    $ btd --client --physdev=/dev/ttyS0 --speed=57600 -modem=0

3. On the client, you will now see a menu of options. Select an HCI Inquiry for one device, with a maximum timeout of about five seconds:

    > inq 1 5

4. If the inquiry succeeds, the program will report the Bluetooth Device Address (BD ADDR) of the server’s Bluetooth card on the terminal. For example, it might return 11:22:33:44:55:66 (it’s unlikely, but this is just an example). Next, create an RFCOMM connection to server channel 2 of that device, using line O. When the server btd application detects the connection, it will spawn PPP and pass in /dev/ttyBTO on the command line as the TTY. The line 0 argument maps to /dev/ttyBT0 on the local device. When the client btd application spawns PPP, it will also pass /dev/ttyBT0 to the local PPP as the TTY. Here’s the command:

    > rf_conn 11:22:33:44:55:66 2 0

5. If the command succeeds, then after a few seconds you will see the connected message on the client’s terminal window. On the server, you should see PPP start up and wait for an incoming PPP connection. At this point, we’re ready to start PPP on the client. Here’s the command:

    > ppp

6. If the PPP connection succeeds, you should see a message like this on both the client and server side:

7. At this point, you can test the connection. First, on either the client or server, open a terminal window and use ifconfig to determine the IP address of the remote PPP connection. It should report the ppp connection similar to this:

8. Now, open another terminal window on the client and ping the remote IP.

    > ping 192.168.1.17

 You know the remote server channel number without doing an SDP discovery.

 You want to use PPP over RFCOMM, and not some other application.

Preparing the Serial Driver

The following example shows how to open the serial port and make it a raw TTY. When it’s raw, that means it won’t mess with our data as it moves between the Bluetooth driver and the serial port. If you don’t make it raw, it will try to filter the data stream looking for special characters. If you think this is confusing, just try using cat on /dev/ttyS0. It works great … for text files. Try it with a binary and you’ll probably hose your terminal settings. But we can fix this by using a raw TTY. The following code shows how to do this:

Whether or not you need hardware flow control depends on the Bluetooth hardware you’re using. Some products are okay with it, while some specifically tell you not to use it. The Ericsson hardware seems to work okay either way. Note that many embedded devices have custom UART hardware. Sometimes these don’t support the hardware lines necessary for hardware flow control. If you have trouble getting the Bluetooth driver to talk to the card, then find out whether or not this setting is correct for your hardware.

Observant readers will wonder if we need to fix the termios setting for the Bluetooth driver itself. After all, it’s a TTY driver. Won’t we have the same problem with binary data? Yes—once we start trying to read or write from it. But that’s fine at this point. It won’t affect any of the ioctl calls we’ll be doing. Later, when we want to transfer binary data, we’ll address this. If we just set the driver up for another application like PPP, then that application should be responsible for dealing with this (PPP does).

Stacking the Drivers

Now that the serial driver is ready, we can connect it to the Bluetooth driver. Remember that the Bluetooth stack registered its own line discipline with the kernel when we loaded the module. The way we stack the drivers is by telling the serial port to switch from using the N_TTY line discipline to the Bluetooth line discipline. That way, when the serial driver receives data, it will push it up into the Bluetooth stack, and when the Bluetooth stack wants to send data, it has a handle to the serial driver.

The N_BT constant uniquely identifies the Bluetooth line discipline among all other line disciplines registered in the kernel. This identifier is what tells the serial TTY to use the Bluetooth stack as its upper layer interface. It’s defined in btcommon.h—part of the OpenBT source tree.

The TIOCSETD ioctl replaces the serial port’s current line discipline with the one specified. It also causes the Bluetooth line discipline’s open() routine to be called, passing in the serial port’s TTY. This gives the Bluetooth stack a handle to the serial TTY driver so it can use it as the lower layer. At this point, Figure 6.2 shows our driver configuration in the kernel.

Starting Communication between the PC and the Card

Once the drivers are stacked, the host can start talking to the hardware. There are some specific things the Bluetooth stack needs to find out from the card before it does anything else. It also needs to do some internal initialization as well.

If you’re going to initialize the stack, you have to use the /dev/ttyBTC device (the control device). The Bluetooth data devices (for example, /dev/ttyBT0) won’t work. In fact, you can’t even open these other devices until the stack is initialized. This, and the fact that multiple processes can open /dev/ttyBTC at the same time, makes it unique. Note that closing /dev/ttyBTC is safe. The stack will remain initialized. To shut it down, we’ll use the BTSHUTDOWN ioctl. You’ll learn more on that in the section “Disconnecting” later in the chapter.

The BTINITSTACK ioctl tells the Bluetooth driver to initialize itself and begin talking to the Bluetooth hardware. It will query the hardware for things like buffer sizes and numbers, read the local BD_ADDR, and so forth. As an application writer, you don’t really need to worry about the details. There is one thing you should know, however: this ioctl call can return before initialization is complete. For this reason, it’s sometimes a good idea to pause your application before continuing.

Switching to a Higher Baud Rate

If we want the Bluetooth driver and the hardware to use a higher baud rate we can tell it to do so now. At 57600 baud, the bottleneck will be the serial connection between the host and the card. This doesn’t mean we’ll lose data. We just won’t be taking full advantage of what the radio can do. If we jack it up to 115200 baud, then we’re more in line with the maximum radio data rate of 723.2 Kbps, which is already pretty slow compared to currently extant wired media. Keep in mind that this only affects the baud rate between the host and the Bluetooth hardware. In other words, we’re not changing the radio characteristics of the card in any way.

The HCISETBAUDRATE ioctl will try to send a vendor-specific command to tell the hardware to change the baud rate. Keep in mind that the command to switch baud rates is vendor-specific. Some vendors might not provide this feature. This is an example of why it’s important for your application to check the return results of system calls. In this case, if the ioctl call fails, then presumably the card won’t change its baud rate. This could be because it has a fixed baud rate, or because it uses a different vendor-specific command, either way we’d better just leave the serial port baud rate alone or the Bluetooth driver will lose communication with the card.

Letting Other Bluetooth Devices Discover Us

By default, the Ericsson Bluetooth Development Kit hardware doesn’t respond to other device’s inquiries. This is okay, because we don’t really want other people trying to connect with us until we’re ready. The following example shows how to enable both scan and inquiry responses:

The HCIWRITESCANENABLE ioctl takes a bit mask parameter. Only the first two bits have meaning. Bit 0 corresponds to Page Scan, and bit 1 corresponds to Inquiry Scan. You set the bit to enable the corresponding scan type. To find out more about Page Scan and Inquiry Scan, consult the Bluetooth Core Specification. For now, just realize that other devices won’t see you if you don’t turn on scan enable.

Sending an HCI Inquiry

To find other neighboring devices use the HCIINQUIRY ioctl. This ioctl takes a parameter of type inquiry_results, which serves both as an in-param and an out-param. The btcommon.h header defines this structure.

The nbr_of_units field specifies the maximum number of responses, which the hardware should listen for before ending the Inquiry procedure. The valid range for this value is 0 through 255. But 0 means an unlimited number of responses! Not a good idea since you’ve only allocated a finite amount of space in which to receive responses.

The inq_time field specifies the time, in units of 1.28 seconds, which the hardware should allow for the Inquiry to finish. The hardware will terminate the Inquiry procedure if either it receives the maximum number of responses, or the said amount of time expires—whichever comes first. The valid range for this value is 0x01–0x30, or 1.28–61.44 seconds.

The bd_addr field marks the start of a block of memory set aside for the Inquiry responses. By default, there isn’t any space for responses. One way to make space is to allocate enough memory for the inquiry_results structure, plus some extra for the responses. It turns out that the driver will only store the BD ADDR from each response, so you’ll need to set aside 6 bytes per response. One way to do this is to wrap it with your own structure that has a static buffer, like this:

The inquiry response actually carries extra information, like the class of device responding. This information is not passed up the stack at the moment, but it’s worth being aware that it’s there, as in the future the driver may change to store more information. If that happens, of course, more memory would have to be allocated for responses.

The ioctl call will block until either the Inquiry completes, or an error occurs. Possible errors include timeouts waiting for the hardware to send the expected HCI commands. If the call is successful, then the inq argument contains information from any inquiry responses received. Note that the ioctl returns success even if no remote devices responded.

Upon successful return, the nbr_of_units field now indicates the actual number of responses received (this is less than or equal to the number you specified) and the bd_addr field contains the received BD ADDRs of remote devices.

 You cannot dynamically register a new service in the SDP database.

 Your application must know how to assemble SDP requests and parse SDP responses.

 Services cannot register themselves with the RFCOMM layer.

 You can statically add services to the SDP database, and for embedded developers this may work well enough.

 Your client applications will know how to discover and connect to services running on a stack, which correctly supports RFCOMM registration.

 OpenBT

Connecting to a Remote SDP Server

Before you can do a query, you need to establish an SDP connection with the remote device. Anytime we need to establish a connection, we’ll use the BTCONNECT ioctl call. This call takes a parameter of type bt_connection. The btcommon.h header defines this structure.

The bd field is the BD ADDR of the remote device you want to connect to. For instance, you can use one of the BD ADDRs discovered in your inquiry.

L2CAP uses a Protocol Service Multiplexor field (PSM) to uniquely identify an instance of a higher layer protocol using an L2CAP connection. For some protocols, this value is well-known (i.e., in the Core Specification), and for others you have to discover it. The Bluetooth Core Specification defines the PSM for SDP to be 1.

The id field is a combination of the PSM for the protocol instance you want to connect to: the line number and the SDP ID. The high 16 bits of the id field indicate the PSM. The next 8 bits of the id field specify the line or session number. Remember the session state machine in Figure 6.2? This value identifies one of those sessions. It also maps to the minor number of a Bluetooth TTY (/dev/ttyBT0, and so on). When we specify a line here, we’re telling the Bluetooth driver to use the session associated with one of the Bluetooth TTYs.

The lowest 8 bits represent the SDP connection ID. For the BTCONNECT call, these are not important. Later, when we look at the BT_SDP_REQUEST ioctl, we will see how these bits are used.

To make things easier on yourself, you should include the sdp.h header so you can use the CREATE_SDP_ID macro. This macro automatically fills in the PSM. The following example shows its usage:

The BTCONNECT ioctl blocks until the connection completes or an error occurs. It returns an SDP connection ID on success. This is a little out of the ordinary for a system call, which should normally return 0 on success!

Sending an SDP Request

After a successful BTCONNECT call, we can start sending SDP requests to a remote device. We’ll send SDP requests (and receive responses) by using the BT_SDP_REQUEST ioctl. This call takes a parameter of type bt_sdp_request. The header btcommon.h defines this structure.

The conID field has the same format as the id field of the bt_connect structure. Again, we’ll use the CREATE_SDP_ID macro, but this time, when we pass in the SDP index, it will be the value returned by the BTCONNECT ioctl.

The sdpCommand field is the actual SDP command. For example, the ServiceSearchRequest command is 0x02. See the SDP chapter of the Bluetooth Core Specification for other commands.

The pduPayload field is a buffer where we have to put the raw SDP protocol, which comprises our request. The driver will build the SDP packet header for us, but we have to provide the payload of the request in this buffer. Unfortunately, nobody has provided a nice library to build these requests for us. Yet. You can consult the Core Specification or other references to learn more about constructing your own payloads. But one thing you need to note: the SDP specification defines multibyte fields to be “big endian.” So, when you define these fields in your payload, you need to put the high bytes first.

The pduLength field indicates the number of bytes in our payload buffer. Note that we’re limited to 256 bytes.

The requestResponse field is a buffer where we’ll find the response to our request when the ioctl call returns (assuming we received a response).

The responseLength field tells us how many bytes we received in our response when the ioctl call returns. If this is zero, then it’s safe to assume we didn’t get the response.

Let’s look at an example of a service search request for our custom echo service:

Remember my warning about multibyte fields and endianness? Look at the Service Class UUID field in our example. We put the high byte before the low byte in our buffer. Likewise for the MaxServiceRecordCount field. Sometimes developers are tempted to define structs, which correspond to protocol packets so that they can fill out the struct and then copy it to the buffer (or cast the buffer to a struct of that type). Beware of doing this! If your application is running on a little-endian processor, then this will not work correctly for SDP. You will get the bytes backwards. The ugly but reliable technique in the previous example will work correctly regardless of the endianness of your host processor. Another alternative is to define or use existing macros that do safe byte-swapping conversions.

Processing an SDP Response

The BT_SDP_REQUEST ioctl call will block while the Bluetooth driver sends the request and waits for the response. If the ioctl succeeded, then the response will appear in the bt_sdp_request struct, which you passed in.

The responseLength field tells you how many bytes are in the requestResponse buffer. If this field is zero, then the Bluetooth driver did not receive any response before timing out.

The first byte of a well-formed response indicates the SDP status of the response. Zero means success; non-zero indicates an SDP error. Consult the SDP spec if you want your application to decode the error type. Remember: the ioctl call can succeed even when the SDP request fails.

If the number of ServiceRecords is zero, then the remote device does not support the service we were looking for. Otherwise, using the service handle, we can send more SDP requests to fetch back attributes of the matching ServiceRecords. The ultimate goal is to establish a connection, so we should send an AttributeRequest for the ProtocolDescriptorList next and parse the RFCOMM server channel out of the response. The purpose of this chapter is not to teach you how to parse SDP, so I’ll leave that as an exercise for the reader.

When your application is finished making requests, it should close the SDP connection by using the BTDISCONNECT ioctl call. That way, the remote server can free up any resources it has committed to servicing your connection. However, the current release of OpenBT appears to have a bug in it such that BTDISCONNECT does not work for SDP connections.

Adding a Service to the Local Database

The SDP service database is an XML file. Remember that we can use the sdp_server daemon to handle SDP queries from remote devices to our local database. To add a service, we edit an XML file and pass it as an argument when we start the sdp_server daemon.

Querying the Local Database

Currently there is no interface to query the local SDP database from within your application. If you want to do this, then you can look at how the sdp_server code invokes the XML parser and processes queries from remote devices.

Using a Data Device

So far, all of the examples have used /dev/ttyBTC as the device. Once we’re ready to actually begin transferring data across a session, we’ll need to open one of the data TTYs. Recall from our session state machine that a session must be in the opened/normal/connected state to transfer data. If you look back at Figure 6.2, you’ll see that it really doesn’t matter whether we establish the RFCOMM connection first or open the TTY first.

Opening a data device is trivial, but here’s the code in case you have any doubts about how to do it:

int bt_fd = open(“/dev/ttyBT0”, O_RDWR);

On success, the device is all yours. If the open fails and errno is EBUSY, then some other process already has it. In this case, you can just keep trying the other devices (e.g., /dev/ttyBT1) until you find one that’s available. Unfortunately, there isn’t really a cleaner way to tell if a device is already being used.

If the open fails and errno is EPERM, then the stack is not initialized. In this case, you can open the control device and use the INITSTACK ioctl call (see earlier) to initialize it and then try again.

Creating a Connection

The SDP transactions give you the parameters you need to know to establish a connection to a remote service. And, in fact, you’ve already seen the command to establish a connection: the BTCONNECT ioctl. We used it to establish an SDP connection. But this time, you’ll be connecting to a different protocol to access the service—which protocol depends on the particular service and what it’s ProtocolDescriptorList indicated.

Here’s an example of establishing an RFCOMM connection.

The CREATE_RFCOMM_ID macro is similar to the CREATE_SDP_ID macro. You can find it in the rfcomm.h header.

The line parameter should match the minor number of the TTY you intend to use for data transfers.

The server_channel parameter should match the value obtained from the ProtocolDescriptorList you get during the SDP session. See the SDP chapter of the Bluetooth Core Specification for an explanation.

Accepting a Connection

Remember the caveat about not being able to register services with RFCOMM? Well, that makes accepting a connection random luck. It could be done better, and maybe in the future it will be, so I’ll start by explaining how I believe connection acceptance should work. At the moment, the protocol stack has many compromises, and you’ll have to use it as is, so I’ll go on to explain how connection acceptance works now.

Example: Startup

In previous sections, we’ve seen examples of how to initialize the stack and to set it up over a lower TTY like the serial driver so that it can talk to hardware. These steps will always be necessary at some point. For an embedded solution, the Bluetooth hardware might be on board, interfacing with the CPU via a UART or some other bus. In these cases, you might have to provide your own TTY driver over a custom hardware interface. Remember, the Bluetooth driver relies on the ability to use a line discipline in order to communicate with the hardware driver. Only TTY driver’s use line disciplines, so the hardware driver must be a TTY.

But when should your stack manager start up the driver? It depends on the application. You can start it automatically when the application runs, or you can wait for a command from a User Interface (UI), or a signal from another process, and so on.

Probably the simplest thing to do on an embedded device is to start the stack on system bootup. You can do this by having the init process automatically start your stack manager from /etc/rc.local or whatever startup script you use for your configuration.

Example: Link Loss

There really isn’t any way for a central stack manager to detect a link loss. When a link with another device goes down, the Host Controller sends the host a sequence of disconnection event notices for each handle on the link. The Bluetooth driver processes these events by disconnecting all sessions on that link. Any processes using the TTYs for these sessions can detect a hang-up. But a central stack manager won’t necessarily get any kind of notification if it’s not using one of those TTYs.

Is this important? It could be if the stack manager kept local cached data about link status or peers. In that case, it would be nice to get notification so that it could clean the caches. But as it is, any active processes using the links for data will be notified. If a stack manager worked in the mode of establishing connections and then spawning applications to use them (this is how btd works with PPP), then it can determine when the process terminates on a hang-up using normal Linux process handling.

The following example illustrates this model.

The do_hci_inquiry() function and its friends would do what their names imply (the previous section illustrated code for implementing these kinds of functions). Once a connection is ready, the stack manager spawns a child process to use the connected TTY, then it waits for the child to exit. When the child exits, the stack manager makes sure the session is disconnected and then repeats the process.

If the link goes down at any point prior to the connection being made, one of the functions will fail and we’ll go back to try again. If the link goes down after the connection is made, the child process will exit when it detects the hung-up condition of the TTY (actually, this depends on the behavior of the child application, but most legacy applications that use TTYs will exit by default when they can’t use the TTY anymore). The do_disconnect is benign if the connection was already severed, but it makes sure the connection is cleaned up in case the child exited for a reason other than a TTY hang-up.

Note that a stack manager could handle a whole set of child applications like this, where each application is kept in a structure associating it with the relevant info needed to do SDP queries for the services it likes.

Example: User-Initiated and Automated Shutdown

If your stack management application has a user interface, then it can give the user the option of starting up or shutting down the driver. Alternatively, it might provide a means for other processes (like a power management service) to initiate a shutdown or startup via an IPC (InterProcess Communication) mechanism.

This example shows how a stack manager might install a signal handler to shut down or start up the stack based on requests from other processes.

This example assumes that if a user or another process wants to shut down the stack or bring it back up, then they will send the stack manager a SIGUSR1. Other forms of IPC might be more pertinent in different cases. The BTSHUTDOWN and BTINITSTACK ioctls take care of all the gritty details, shutting down connections, hanging up TTYs, flushing buffers, and so on.

Example: Idle Operation

Stack management applications can keep tabs on what other remote devices are in the area by doing periodic inquiries and keeping the results cached locally. You could provide an API for other applications to access this cache so that they don’t have to do their own inquiries. You could even keep a cache of remote SDP databases for devices in range.

This example shows how a stack manager might maintain a remote BD ADDR cache. You could extend this example to keep other information about remote devices in the local cache. It polls a local socket for requests from local processes to retrieve the cache. You extend this by providing a functional API to handle IPC with the stack manager daemon.

This is just a simple example. It uses the HCIINQUIRY command (see previous sections) with one of our wrapper structs for the inquiry results. It also has a buffer for keeping the results of HCI inquiries. Every so often it executes an HCI inquiry request to see what remote units are in the vicinity and puts their BD ADDRs in the cache.

The do_listen_for_cache_requests_with_timeout() could implement any form of IPC you like to field requests from other processes for the latest inquiry results. Every once in a while the process stops listening for requests and refreshes the cache.

The usefulness of something like this depends on how many processes are potentially doing their own HCI inquiries. But you could extend the idea to cover more expensive operations like searching remote SDP databases. Also, since we won’t automatically receive notice when another device modifies its SDP database, the process could periodically update its cache of another device’s SDP database.

The standard kernel source tree only recently accepted the Bluez Bluetooth stack, but it may not yet possess all the features some application developers require. It requires Linux 2.4.4 or greater.

IBM’s BlueDrekar is a nice-looking implementation distributed in binary form for x86 platforms running 2.2.x. Source is not freely available to the general public.

The OpenBT project is a not-as-nice open source project that works for most things an embedded developer would want. Source is available and has been used on x86, ARM9, ARM7, MIPS, and PowerPCs.

The OpenBT stack implements TTY drivers for RFCOMM, SDP, and stack control.

The Bluetooth driver must be stacked over a lower-layer hardware driver that implements a TTY.

Any legacy application that uses a TTY can use RFCOMM once another application sets up the underlying RFCOMM connection.

SDP, connection setup, and stack control are accomplished with ioctl calls.

No interface exists for SCO, or L2CAP, although ioctls are available to support most HCI commands.

The OpenBT source tree comes with some applications: btd/btduser, sdp_server, and BluetoothPN.

The difference between btd and btduser is that btd is meant to work with the kernel mode Bluetooth driver while btduser works with the user mode Bluetooth driver. Many people prefer btduser since it is less prone to lock up your system if things go badly. However, the OpenBT developers do not support it as well as btd.

The sdp_server application provides you with an SDP database server daemon. Once you’ve installed the Bluetooth driver, you can start this daemon and it will automatically receive and respond to SDP queries from remote devices.

This application provides a GUI that displays the SDP database on a remote device. It provides some examples of how to make SDP requests and process their results.

The quickest, most useful way to establish and exploit a Bluetooth connection from Linux is to use the standard GNU network applications over PPP. And the easiest way to do that is with the btd application.

An application manager must set up the driver stack over the hardware TTY and initialize the Bluetooth driver. This can be any application; the OpenBT source tree does not provide a general stack manager.

Client applications must obtain the Bluetooth Device address of the remote device and—for RFCOMM connections—the channel number of the remote service in order to establish a connection.

Once a connection is established, any application can use the TTY associated with the connection for data transfer.

The driver indicates a disconnection event with a hang-up of the associated TTY.

Use ioctl calls to control the device and get information about device status.

Use /proc/bt_status to get information about device status.

A stack manager must be able to deal with link loss and system shutdown requests. It should provide an interface for users as well as other processes like power management to signal shutdown requests.