Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
IOIO Over Bluetooth
IOIO Over Bluetooth for Android
Starting at Bootloader V3.0 + App V3.10, IOIO can communicate with your Android device over Bluetooth connection. This is achieved simply by attaching a standard USB Bluetooth dongle to the board.
Not every possible dongle has been tested, and some are known not to work. However, most simple ones do work. Check this page for devices that have been reported to work.
An existing application code written to work over USB does not need to change to add Bluetooth support, if it is using the IOIOLib Application Framework. However, it will need to be re-built against the Bluetooth libraries according to the instructions below.
Note that Bluetooth is only supported on Android API level 7 ("2.1-update1") and higher.
If your IOIO is running old firmware that does not support Bluetooth, you can upgrade your firmware by following the instructions on this page.
This feature uses code from the btstack Open-Source Project. This is an excellent library, especially suited for embedded devices, which enabled delivery of this feature in a timely manner. Special thanks go to Matthias Ringwald, the owner of btstack, for his wonderful code and time spent on supporting this integration!
- On IOIO v1 boards, simply plug the dongle into the USB jack on the IOIO board.
- On IOIO-OTG boards, use the provided USB male-micro-A-to-female-A adapter cable. If you are using a non-standard adapter, the adapter may not correctly identify itself has "host side", so you might need to move the host mode switch on the board to the "force host" (H) position.
- Make sure the charge limiting potentiometer is all the way clockwise.
In order for an application to be able to identify your IOIO boards within range, they first need to be "paired" with your Android device. Pairing is a one-time process done per dongle. Once paired, your Android device is going to remember the specific dongle and will not require pairing again.
- Power your IOIO board and attach the Bluetooth dongle to it.
- On your Android device, go to Settings > Wireless & networks > Bluetooth settings menu. Make sure Bluetooth is enabled by checking the top box. Then hit "Scan for devices".
- You should see a device called
IOIO (xx:xx), where
xx:xxare the last 4 digits of your IOIO's address. If you have more than one IOIO, each one will have a different address, making it possible to distinguish between them. The address comes from the dongle and not from the IOIO, so if you swap two dongles, the addresses will go with the dongles and not with the IOIOs.
- Click the IOIO in order to pair. You will be asked for a PIN code. Enter 4545.
- Your IOIO is now paired, until you manually Unpair it (by long clicking the device from the same screen).
You will need to use IOIOLib V3.10 or higher (available from the Android Software column of the Downloads page). The IOIOLibAndroid library supports multiple connection channels in your application, but does not add Bluetooth functionality. In order to use Bluetooth, you need to also add the IOIOLibBT library to your application (from Eclipse: Project > Properties > Android > Add... > Choose IOIOLibBT after importing it to your workspace).
Then, you will need to add the BLUETOOTH permission to your application (edit your application's
AndroidManifest.xml file, in the "permissions" tab, add a
uses-permission and select android.permission.BLUETOOTH).
Establishing a Connection
Simply open the application built as explained above. You can leave the Android device connected over USB to your development PC, thus read logcat output in real-time, debug the application, etc. The connection process may take a few seconds.
If you have Android version less than 10 (2.3.3), you may be required to enter the PIN (4545) connection after every time the IOIO is powered on. You may want to change when the IOIO gets connected / disconnected in your application, or prevent your Android from sleeping in such cases.
- Multi-IOIO support has not been thoroughly tested. If problems are found, they will hopefully be addressed down the road. It is already known that when using more than one Bluetooth device simultaneously (as opposed to one Bluetooth and one ADB) there may be connection problems. Specifically, make sure your Android device is only paired to a single IOIO if you want problem-free connection. Otherwise, your application will try to establish a connection to every paired device and these attempts alone seem to be interfering with existing connections.
- The latency over Bluetooth is significantly higher than of wired connections (order of 10's of ms).
- The bandwidth (data rate) of Bluetooth is significantly lower than of wired connections (order of 10's of KB/sec). In practice, this means that bandwidth consuming features (e.g. Analog Input) may not work 100% smoothly. There is a plan to enable programmatic reduction of the analog sample rate in order to mitigate this limitation. Also, some dongles have been observed to exhibit lower bandwidths than others.
- Many cheap Bluetooth dongles have the same address. This means there is no way they can be used concurrently, with with a single host or with different hosts. The best workaround is to use dongles of different models.
- On some Android Devices there is a Bug in the Bluetooth Stack where you cannot discover the IOIO Device. The Description of the Problem you can find here. As a workaround there is an free Application on the Android Market named "Bluetooth Class Zero"
If you are having trouble with Bluetooth, here are some things you can do with your current hardware to fix the problem:
- Make sure the current-limiting potentiometer on the board is turned fully clockwise (no current limiting). Many dongles will misbehave when limiting their current.
- Unpair, restart the phone, pair again.
- Try pairing from your PC. You should get a serial port. Open a terminal on that port, see if you're getting a handshake message from the IOIO.
- Some dongles won't work with IOIO. For example if the dongle presents itself as a USB hub. See Supported Bluetooth Dongles.
- Some Android versions and devices won't work with IOIO over Blueooth. Check if the device supports SPP (Serial Port Profile) and check this list: Supported Devices.
- Some dongles work with one Android device but not with an other. Because of this, please add your tested dongle with all information to the Supported Bluetooth Dongles list.