Table of Contents
BlueScripts is a program for the scripting of Bluetooth ASCII messages to Bluetooth radios via an Android phone and an XML file. It is open source.
BlueScripts allows the user to automate sending messages to Bluetooth radios for embedded system projects without the need to input the messages on a terminal application or write a separate Android program.
The program looks for BlueScripts.xml in the root directory. This file is parsed for “scripts”. Each script contains “actions” which are targeted at a single Bluetooth MAC address. Each “action” is message/address pair.
Each script creates a clickable item in the scrolling menu that will execute the script's actions on click. Replies are outputted in a log area.
Details of use and example
Many embedded system applications need simple message communications between two devices of a repetitive nature. Good examples are any remote control application. These types of of applications can be implemented using a Bluetooth terminal program. There are several good examples of this type of program on the Android Market, including BlueTerm and SENA Bluetooth Terminal. The later contains more features than the former. Both are currently free and the former is open source.
BlueScripts is based on the BluetoothChat example program provided by Google. Its main advantage over a terminal is automation of repetitive commands using a simple menu system. It issues a series of ASCII messages to Bluetooth MAC addresses as defined in BlueScripts.xml. This file should be in the root of the SD card directory on the phone. BlueScripts uses this file to create the menu of available scripts at start up.
The basic format of the BlueScripts.xml file is:
<doc> <script> <name>Script Name</name> <action> <address>00:11:22:33:44:55</address> <message>some ASCII message</message> </action> <action>...</action> </script> <script>...</script> ... </doc>
Each Script must have a name. This appears in the ListView of clickable items that makes up the main interface of BlueScripts. You may have as many scripts as you wish.
Each Script can have as many actions you wish (but has to have at least one), an action is just one thing to do. At present the only action type is the message action.
Each Action must have a target MAC address (the MAC address of the remote Bluetooth radio) and one message. If you want to send more than one message to the same MAC use multiple actions. You may have as many actions as you want inside a script.
An example valid XML file would be:
<doc> <script> <name>Say Hello</name> <action> <address>00:11:22:33:44:55</address> <message>Hello SSP Radio</message> </action> </script> </doc>
Example of use
We have created a complete example of how to use BlueScripts with an embedded project called BlueZigbee, it is the example shown in the video.
This project uses an Eridani Development Board, a Digi Zigbee API mode radio, and a Bluetooth SSP UART radio module to implement phone controlled electric outlets.
Complete details on this project can be found at here.
Source Code and notes
This program is open source released under the Apache license.
The program is a modified version of the BluetoothChat example program. The principle changes are that:
- The UUID is changed to the generic UUID of SPP devices
- BlueScripts does not listen for incoming Bluetooth connections (more secure)
- There is code to parce the XML file added
- A workaround for some phone/bluetooth modules is added when service discovery protocol fails (SDP)
- For a reply to be printed in the log area it must end the ASCII EOT character (0x04)
The code provided here is as is and may be easier or harder to modify than the BluetoothChat example code. To allow the BluetoothChat example to connect to a standard SPP Bluetooth radio you simply need to change the UUID string to: 00001101-0000-1000-8000-00805F9B34FB.
BlueScripts has only been tested with an HTC Desire HD (Inspire 4G variety), and 3 bluetooth radios:
- Sparkfun BlueSMiRF Silver (no longer available, based on Phillips BGB203 chip)
- MDFly RF-BT0417C Bluetooth radio (based on CSR BC417; $10 from MDFly, ~$6.50 on eBay for similar modules: “bluetooth ttl”)
- Roving Networks RN-42 radio ($15-17 Available at Digikey, Mouser, Sparkfun, etc.)
The way of connecting as done in BluetoothChat works as is for the first two modules on the HTC Desire HD, however for the Roving Networks RN-42 module it fails. In particular the BluetoothSocket.connect() method fails during service discovery protocol (SDP). The RN-42 supports SDP and functions both under Linux and Window bluetooth stacks connecting to SPP, however it fails with under Android 2.2.1 on the Desire HD.
Similar failures are noted elsewhere, in particular here: http://stackoverflow.com/questions/3397071/android-bluetooth-service-discovery-failed-exception
The method described in the thread above solves the issue, but as I don't fully understand the issue it is only used when the normal method fails (as a fall back). As a result if the radio fails to connect for any reason, the fall back method is tried before giving up.
This allows BlueScripts to work with RN-4x modules in release 0.52.
If you have found a bug in BlueScripts please add it to the bugs page.
This software is currently Beta quality so there are likely bugs. We will add confirmed bugs to this page as we confirm them from the user editable bugs page.