My favorites | Sign in
Logo
Project hosting will be READ-ONLY Wednesday at 8am PST due to brief network maintenance.
             
Search
for
Updated Jan 17, 2010 by matthias.ringwald
Labels: Featured
GettingStarted  
How to get a grip on the BTstack

Introduction

Although in an early stage, the BTstack can already used to create connections to other devices using the L2CAP protocol. This allows for example to receive keypress events from an Bluetooth keyboard or movement data from a WiiMote.

On this page, we provide a quick walk-through to run example/test.c on an iPhone 3G(S) or iPod touch 2G/3G and connect to a WiiMote, while displaying acceleration and button reports. See below for iPhone simulator usage.

Requirements

Steps to get BTstack example running on the iPhone

  1. get the BTstack project from the Google code SVN:
  2. svn checkout http://btstack.googlecode.com/svn/trunk/ btstack
  3. cd into the btstack folder
  4. cd btstack
  5. If you have pkg-config from MacPorts
  6. in bootstrap.sh: change aclocal to aclocal -I /opt/local/share/aclocal
  7. If you don't have iPhone SDK 2.0 installed
  8. in configure.in: change the SDK_VERSION variable to the SDK you want to use/have. BTstack works with all versions.
  9. run the bootstrap helper
  10. ./bootstrap.sh
  11. configure BTstack for the iPhone
  12. ./configure --target=iphone
  13. If you get an error that mentions "PKG_CHECK_MODULES", then aclocal did not pick up pkg-config installation. Try to fix it or remove lines 41-58 (incl.) of configure.in and re-run the ./bootstrap and configure again.
  14. in example/test.c, find the line with the hard-coded value for the MAC address of the WiiMote and enter yours. Mine has the address 00:19:1d:90:44:68
  15. build it
  16. make
  17. copy the BTdaemon, the client client library and the example test to your iPhone. Replace 192.168.3.102 with the IP address of your device
  18. scp src/BTdaemon src/libBTstack.dylib example/test mobile@192.168.3.102:.
  19. ssh into your device
  20. ssh mobile@192.168.3.102
  21. copy the client library into /usr/local/lib
  22.  su
     cp libBTstack.dylib /usr/local/lib
     exit
  23. make sure Bluetooth is turned OFF in the Settings.app
  24. run the BTdaemon
  25. ./BTdaemon
  26. ssh into your device again
  27. ssh mobile@192.168.3.102
  28. run the test
  29. ./test
  30. check the output in both sesssions. If everything works, the app will prompt you to make your WiiMote discoverable by pressing the buttons 1 and 2 together. Shortly after that you should get continuous accelerometer readings. You can press the Home button to quit the test app.

Shortcut: Install the BTstack package via Cydia. Only copy the test app to the iPjone. BTdaemon is started automatically by launchd.

Important: My WLAN often breaks down when using Bluetooth. When logged in via SSH this looks like the app would not work or hang, when in reality the WLAN is just not working properly. Check the WLAN icon in the status bar. After the introduction of Internet tethering, I highly recommend to connect the iPhone via USB and use this connection for SSH. When using USB Tethering, my machine receives the IP address 192.168.20.3, and the iPhone can be accessed at 192.168.20.1.

Details

In main, the BTstack is opened and packet handlers are registered before the BTstack is asked to boot with the btstack_set_power_mode command. All commands to control the BTstack are send asynchronously with the bt_send_cmd. Finally the run_loop is executed. From there on, the rest of the test app runs as a finite state machine which processes events received from the BTstack. Be aware that error handling is barely performed. :)

Anyway, the different steps of the program are visible in the event handler. First, it reacts to the successful startup of the BTstack and set the local Bluetooth name. Then, pairing is enabled/disabled with the hci_write_authentication_enable HCI command, which is caused by the command complete event of the hci_hci_write_local_name. Again, a command complete event will trigger the next action. Now, the BTstack is asked to open an L2CAP channel to the hard-coded WiiMote at PSM 0x13 (HID Interrupt) where reports from the HID device are received. Upon success, a second channel for PSM 0x11 (HID Control) is opened. This channel is necessary to enable the reporting of acceleration readings and send the command to set LEDs which also stops the LEDs from blinking. Finally, we're ready to receive HID status reports. See the HID and the WiiMote documentation for more details on this.

As this event handler shows, everything is event-triggered. After sending a command to the BTdaemon, which in turn sends it to the Bluetooth chipset, we wait for the corresponding event to continue with our application. Instead of writing this single even handler, it is much better to follow the concept of finite state machines. Based on our current state, an event such as HCI events, triggers the next action and the transition to another state. For more insight inton finite state machine, I highly recommend the book by Miro Samek.

Develop BTstack apps in the iPhone Simulator

To develop iPhone apps on the Mac, you need a serial Bluetooth module like the Ericsson ROK Tester connected over a USB-to-Serial adapter, as theHCI_USB_Transport does not work yet. With such a setup, you can configure BTstack for running on the Mac host, not the iPhone as described above. You also have to specify the UART device, see ./configure --help

For testing you run BTdaemon in one terminal before starting your app in the simulator. The app will then connect to the BTdaemon over the local unix domain socket.

References

Help

If you really want to try the example app on your iPhone, but didn't get it to work although you've followed the instructions here, or, if you'd like to use Bluetooth in your own application (whatever OS/HW), please join the BTstack Developer Forum.


Comment by matthias.ringwald, Nov 08, 2009

Cydia packages are out: iPhoneInstallationViaCydia

Comment by matthias.ringwald, Nov 19, 2009

BTstack is an alternative to Apple's on the iPhone. No support for the Headphone or the A2DP protocol yet. Even then, integrating it into the OS will be tricky.

Comment by max.wagn...@yahoo.de, Dec 05, 2009

I'm probably missing something incredibly stupid, but I can't get the WiiMote? example to compile. I've been planning to add WiiMote? support to an app I'm working on, but for that I first need to get the WiiMote? demo to work as I want it before adding this capability into my app. I've been able to build the non-CocoaTouch? version of BTstack, but as soon as I try to do something with XCode, it fails to recognize or find anything under the format of <btstack/someHeader.h>. It's probably just some stupid mistake I made, but could you offer your advice?

Comment by matthias.ringwald, Dec 05, 2009

if you'd like to use Bluetooth in your own application (whatever OS/HW), please join the BTstack Developer Forum. either install the headers in /usr/include or set the "header search path" in XCode to the btsack/include/ directory

Comment by fopina, Dec 07, 2009

I'm really hoping we can see a demo of RFCOMM working with those SE Bluetooth Watches soon! That'd rock!

Comment by matthias.ringwald, Dec 21, 2009
Comment by pmatteucci, Jan 24, 2010

Hi guys. I'm got a bicycle with an array of sensors and a bluetooth module. It would be great if I could get this sending serial info to an iPod Touch. I discovered that the Bluetooth module in the iPod/iPhone is severely locked up by apple. Is this the solution? Using the BTstack, can I talk to any bluetooth device? Thanks!

Comment by matthias.ringwald, Jan 28, 2010

yes, you can.

Comment by e.malvat...@itacasw.it, Jan 29, 2010

Hi guys, I'm interesting to implemet in my application bluetooth using BTstack,Where I can find an example on using it with Xcode? I try with example in BTstack project but don't work.Can someone say me where I can found it? or where I can found documentation on using BTstack?

Comment by gwenhael.goavec, Jan 29, 2010

Hi, I wish to create a graphic appplication with bluetooth support but I don't see how to do this. run_loop_execute seem blocking the application. I use a linux box, consequently I'm not able to compiling xcodeproj app (like WiiMoteOpenGLDemo). How to use btstack for a graphic app with a linux box. Thank you very much

Comment by matthias.ringwald, Jan 29, 2010

hi guys. join the dev group. ... either you write your app in an event driven way, by this your app gets caled by the run loop, or you could use an extra pthread for BTstack and use its intet-thread communication for signaling/data delivery.

Comment by ahadjeres, Jan 31, 2010

how to get a hyperterminal working on the iphone and use btstack

Comment by gaoguilong, Jan 31, 2010

Hi, I wish to create a printer appplication with bluetooth support but I don't see how to do this. How to use btstack?

Comment by gaoguilong, Jan 31, 2010

Line Location bt_control_iphone.m:42: error: ../config.h: No such file or directory Line Location daemon.c:41: error: ../config.h: No such file or directory Line Location daemon.c:103: warning: unused variable 'handle' Line Location hci.c:47: error: ../include/btstack/version.h: No such file or directory Line Location hci.c:514: error: 'BTSTACK_MAJOR' undeclared (first use in this function) Line Location hci.c:515: error: 'BTSTACK_MINOR' undeclared (first use in this function) Line Location hci.c:516: error: 'BTSTACK_REVISION' undeclared (first use in this function) Line Location platform_iphone.c:40: error: ../config.h: No such file or directory Line Location run_loop.c:44: error: ../config.h: No such file or directory Line Location socket_connection.c:45: error: ../config.h: No such file or directory

Comment by matthias.ringwald, Feb 01, 2010

gaoguilomg: please follow the instruction on this side to compile BTstack

Comment by matthias.ringwald, Feb 01, 2010

ahadjeres: can you explain what exactly you'd like to do?

Comment by gaoguilong, Feb 01, 2010

thank you ,I follow the instruction, but I want to develop in Xcode,how to start?

Comment by matthias.ringwald, Feb 01, 2010

gaoguilomg: please follow the instruction on this page to compile BTstack. and then try using Xcode. You will have to set the include and libs used correctly.

Comment by gaoguilong, Feb 02, 2010

Thank you

Comment by jaljupp, Feb 02, 2010

How to run this application ..... ? what is libBTstack.dylib ?

Comment by matthias.ringwald, Feb 02 (6 days ago)

which app? libBTstack.dylib is the client library an app uses to access Bluetooth services, check out Architecture

Comment by nickbiznz, Feb 02 (6 days ago)

I'm really new to this, please excuse me if my questions are so noobie :( In the requirements: - The autotools is already in Mac OS X leopard 10.5.5 right ? so i dont need to install it. if not, where to find it. - pkg-config: I dont know how to install it. You said about get it from MacPorts?, but I search on the site, can't find it anywhere :( Correct me if I'm wrong. What I understand is I need to compile the btstack to get the libBTstack.dylib and copy it to my usr/local/lib and then also copy all the file in the "include" fold (.h files) to my xcode project then I'm good to go ?

Comment by cao_...@yahoo.com, Feb 03 (5 days ago)

Ok, I got the them all compiled. Have btstack package installed from cydia. I copied the test file and the rfcomm to my iphone. But they didn't run, all I got was "Killed" in the console. Anyone know how to fix this ?

Comment by andiLiu, Feb 04 (5 days ago)

The guida miss one step ldid -S BTdaemon ldid -S test If you don't execute this , you just get "Killed" output.

Comment by matthias.ringwald, Feb 04 (5 days ago)

hi. thanks for helping out. if you configure for iPhone and build with the Makefiles, ldid is automatically called on the executables.

Comment by andiLiu, Feb 04 (5 days ago)

also , I need run the BTdaemon and test use root role.

Comment by nickbiznz, Feb 05 (3 days ago)

Thanks, I got it running :)

Comment by jaleelpp, Today (8 hours ago)

in the above tutorial i covered first 7 steps . but . 1) in step 8 can i using any bluetooth device, like nokia phone and so on. instead of WiiMote? , how i get ip address of a bluetooth phone, to connect with this. 2) when i build " make " by staying in btstack i am geting one error. ie make1?: execvp: ./get_version.sh: Permission denied make1?: libBTstack.dylib? Error 127 make: all-recursive? Error 1

how to rectify this error. ?

thanks and regards

Comment by matthias.ringwald, Today (2 hours ago)

jaleelpp: you can use inquiry command installed by the BTstack Cydia package. It will report remote baseband addresses (similar to MACs) and remote names. For the permission error, try "chmod +x get_version.sh" to make it executable.


Sign in to add a comment
Hosted by Google Code