IDBLUE Application Development Quickstart Guide
Current IDBLUE Developer Toolkits are available on our Device Driver and Software page.
- Objective C for iOS (iPhone/iPad) 4.0 and higher.
- Microsoft .NET Compact Framework 2.0 and higher (Windows Mobile 5 – 6.5).
- Microsoft .NET Framwork 2.0 and higher (Windows XP, Vista, Windows 7).
- Eclipse IDE for Google Android 2.3 and higher
- For information on developing applications for iOS, please see Apple’s Developer Site
- An entry for “Supported External Accessory Protocol Strings” must be added to your project’s pList file, with a value of “com.idblue.r8” (do not include the quotation marks)
- The “External Accessory Framework” must be added to your application
- To add the IDBLUE Framework to your project, after extracting the supplied .zip archive, go to “add an existing framework” within XCode, and select the “Framework\IDBLUE.framework” subfolder. See XCode’s Linking to a Library or Framework article.
- If you intend on submitting your IDBLUE app to the App Store, Apple requires that you first register your app with us, otherwise it will be rejected. Please contact IDBLUE Support for more info.
- For information on developing applications for .NET, please see Microsoft’s MSDN Site
- Windows Phone 7 is not supported due to the lack of development access to Bluetooth.
- For Microsoft based devices, the following Bluetooth stacks are supported: Microsoft, Broadcomm.
- The SDK includes DLLs which provide the interface between the SDK and the Bluetooth stack, named “IDBlue.BT.*.dll” (* indicates the actual Bluetooth stack interface contained in that DLL). These DLLs should be included as items (not References) in your Visual Studio project, and should be deployed with your application.
- Note: there are 32 and 64 (name includes “x64”) bit versions of each, as they are platform specific.
SDK Architecture Overview
To help developers who may be working with a mix of mobile devices, the basic architecture is the same for multiple versions of the API.
As much as possible, properties of the IDBLUE device itself are prefixed with “get” and “set”, whereas RFID related functionality is prefixed with “read” and “write”.
The provided API will allow you to develop for both HF and UHF versions of IDBLUE. Properties and commands common to both HF and UHF are accessible in the IDBlueCoreApi class. If you use this class exclusively, you will be able to create a “hybrid” application that will seamlessly work with both HF and UHF devices interchangeably. These hybrid applications will be limited to a “read tag ID” only type of scenario (EPC ID is used for UHF), as this is the only actual RFID function available for both HF and UHF. However, since many applications simply use the tag ID for back end database lookups, this is extremely useful.
To allow for development of applications that makes use of HF or UHF specific functionality, the IDBlueCoreApi class is inherited by the IDBlueHfApi and IDBlueUhfApi classes. Look at the detailed API documentation for information on how to call the RFID protocol specific functions exposed by those classes.
You will notice that when you send a command to IDBLUE via one of the API classes mentioned above, the result of the command is not returned by the function call itself; instead, we use an asynchronous architecture so that your application does not have to wait for the communication to finish.
The iOS SDK is based on the common “Observer” design pattern, and requires that a class inheriting from ResponseHandler, or that implements IResponseHandler (or the HF/UHF specific versions thereof). This object will then be notified of the response from IDBLUE. For example, if you call the “readTagId” function belonging to the IDBlueCoreApi class, the “readTagIdResponse” function belonging to your class which inherits from ResponseHandler will get called, and the resulting tag ID will be available there. Note that there are separate response functions for successful and failed commands.
The API and Response Handler classes are connected via the well-known “Observer” design pattern; the API classes have an “addResponseHandler” function, which lets you tell it what object you wish to receive the responses.
In .NET, you may also use the familiar “+=” syntax to register for event notifications for the responses to your commands. The same event is called whether the command is successful or fails; the EventArgs object contains a “Successful” property to indicate such. For each command in the API, the included documentation will indicate the event used for the response under the “See Also” heading.
A “session” is the abstraction of the underlying communication link (either Bluetooth or USB) between the host device and IDBLUE, and is managed by the IDBlueSession class. An instance of this class is passed to the constructor of your IDBLUE API class, which provides the conduit for API messages to be sent and received.
For iPhone/iPad, IDBLUE must first be connected via the iOS Bluetooth settings screen before a session can be opened within the application, since it is not possible to connect/disconnect from within the application context. The session object has accessors to retrieve a list of connected Bluetooth accessories, filtered by the “com.idblue.r8” protocol string. Typically, though, there is only ever 1 connected accessory.
The observer pattern is again followed with sessions, with the ISessonHandler interface being implemented to receive session notifications so your app can provide feedback or initialize as appropriate.
The IDBlueSession class is more powerful in .NET, as it also lets you search for, and connect to/disconnect from Bluetooth devices. Since the protocol string filter cannot be used on this platform, you must rely on the Bluetooth device name when making connections.
Instead of using an ISessionHandler interface as in iOS, we again make use of .NET events for notifications.
Physical vs. Logical Connections
When IDBLUE is connected to a host, either by plugging into a USB port or opening a Bluetooth connection, it is considered to be “physically connected”. Once data starts flowing between IDBLUE and the host, it is then considered a “logical connection”. To start and terminate your application cleanly, there is an “enableChannel” function within the IDBlueCoreApi, taking in a true or false parameter as appropriate. If you exit your application without disabling the channel, or if your application abnormally terminates, it is possible for IDBLUE to still think that the channel is in place. At that point, you would have to either terminate the Bluetooth connection or unplug from USB. Proper use of the “enableChannel” command is vital for USB communication, as it is the only mechanism by which IDBLUE can discern whether it is plugged in simply for charging or for application communication.
IDBLUE Synchronous vs. Asynchronous Communication
Depending on how your IDBLUE device is configured, your application may ask for IDBLUE to perform an action (i.e. execute a “readTagId” function on the IDBlueBaseApi class), or the IDBLUE may send data unprompted as a result of the user pressing the Action Button on the device itself if the ConnectedMode property is set to “readTagId”. This is referred to as “synchronous” and “asynchronous” communication respectively. Regardless of whether IDBLUE was prompted or not, the same function in the ResponseHandler will be called (iOS) or event raised (.NET).
Note that when executing Synchronous commands, there is no UI shown on IDBLUE; it is up to the developer to use the “beginCommands” to show the typical ‘busy’ UI (front LED blue), and “endCommands” with either true or false to show the typical ‘success’ (front LED green) or ‘failed’ (front LED red) UI respectively.
One possible option for the ConnectedMode property is what is called “Reactive” mode. In this mode, when the user presses the Action button at the front of IDBLUE, instead of executing an RFID process the device instead notifies the application asynchronously that the user pressed the button, via the “buttonPressResponse” of the ResponseHandler class (iOS) or the ButtonPressEvent (.NET). At that time, the application can perform whatever action or set of actions necessary, bookended with “beginCommands” and “endCommands” as appropriate.
Useful Device Properties
Below is a subset of the available properties common to both IDBLUE HF & UHF (i.e. accessible via IDBlueCoreAPI) which many may find useful:
- Time – used to set the clock on board IDBLUE.
- Connected Mode and Disconnected Mode – control how IDBLUE behaves when connected to, or not connected to a host device.
- Continuous Scan Enabled – will cause IDBLUE to enter a scanning loop without the user having to keep the button pressed. Use in conjunction with the Continuous Scan Timeout (when to stop loop) and Duplicate Elimination Timeout (filter successive scans of same tag) properties.
- Action Button Enabled – can disable the Action Button on IDBLUE if you want to suppress asynchronous communication.
Note: call saveProperties if you want your property changes to survive a device reset. Use loadProperties if you want to undo your unsaved changes.