![]() |
Welcome to the IDBLUE iOS SDK documentation!
Below is sample code on how to initialize the IDBLUE iOS SDK. In this example, we show you how to create your own class, IDBlueApi, that inherits from IDBlueHfApi. You can use this class to communicate with IDBLUE devices.
The IDBlueHfApi takes care of all of the leg work of initializing the SDK. All you need to do is override a few methods and make a few calls into the IDBlueHfApi (and IDBlueCoreApi)! You should review IResponseHandler and ISessionHandler if you haven't already done so. If you ready, let's get started.
To start off, create a class called IDBlueApi that inherits from IDBlueHfApi, like so:
// IDBlueApi.h #import <Foundation/Foundation.h> #import "IDBlueHfApi.h" #import "iOSSession.h" // By sub-classing IDBlueHfApi, IDBlueApi is the only object from the IDBLUE // iOS SDK you need to instantiate. @interface IDBlueApi : IDBlueHfApi { iOSSession* _iosSession; } -(BOOL) openFirstIDBlueDevice; @end
The corresponding implementation file should look something like the following:
#import "IDBlueApi.h" @implementation IDBlueApi -(id) init { _iosSession = [[iOSSession alloc] init]; self = [super initWithSession: _iosSession]; if (self) { // Log the current version of the SDK we are using NSLog(@"%@", [self sdkVersion]); // add custom initialization here } return self; } -(BOOL) openFirstIDBlueDevice { return [_iosSession openFirstIDBlueDevice]; } @end
Now you're ready to start using the IDBLUE iOS SDK in your application. When you're application starts, create an instance of IDBlueApi
// Initializing the IDBLUE SDK is as simple as creating an instantiate of IDBlueApi
IDBlueApi* sdk = [[IDBlueApi alloc] init];
Before you can communicate with an IDBLUE device in your application, you need to open a session first. Since iPhone only supports one connected accessory at the moment, you can design your application to use the one and only IDBLUE device (if one is present). To do this, use the openFirstIDBlueDevice method of iOSSession, as follows:
if ([sdk openFirstIDBlueDevice]) { // onSessionOpened callback method will be called when the session is open } else { // A session could not be opened. Is IDBLUE paired with the iPhone? }
To get notifications of session events (such as session opened, session closed, etc.) you have 2 options:
Overriding the callback methods in IDBlueApi is the simpler of the 2. To do that, add the following code to IDBlueApi.m
// SessionHandler callback methods we are overriding -(void) onSessionOpened: (id) session { [super onSessionOpened:session]; NSLog(@"IDBLUE session opened"); } -(void) onSessionClosed: (id) session { [super onSessionClosed:session]; NSLog(@"IDBLUE session closed"); }
When using the IDBLUE iOS SDK, sessions should be managed as follows:
Now that we have the communication out of the way, lets turn our attention to sending commands to IDBLUE and handling responses.
The IDBLUE iOS SDK is designed asynchronously. That is, when you send a command to IDBLUE, the IDBLUE iOS SDK does not wait for a response. Applications are notified of responses via the IResponseHandler protocol. When a response is received from IDBLUE, all registered IResponseHandlers are notified of the response via the appropriate callback method.
Note that the IDBlueCoreApi is itself an ResponseHandler (an class that implements the IResponseHandler protocol). So when you want to listen for events from IDBLUE, it's as simple as overriding the ResponseHandler methods in your IDBlueApi class.
For example, suppose we want IDBLUE to scan for an RFID tag, and return back the tag identifier to our application. To do this, we would call readTagId. Several seconds later, one of 2 possible callback methods will be invoked: either readTagIdResponse or readTagIdFailed, depending on whether an RFID tag was read successfully or not. Here's the code to do that:
// IDBlueApi.h -(BOOL) getTagId; // IDBlueApi.m // Illustrates how to get IDBLUE to scan an RFID tag and give us back the tag id. // If IDBLUE finds a tag, the readTagIdResponse callback method will be invoked. // If no RFID tag was found or an error occurred, the readTagIdFailed callback // method will be invoked. -(BOOL) getTagId { SendStatus* status = [self readTagId:self]; if ([status successful]) { NSLog(@"get tag id command sent to IDBLUE"); return TRUE; } else { NSLog(@"failed to send get tag id command to IDBLUE"); return FALSE; } } // ResponseHandler callback methods we are overriding -(void) readTagIdResponse: (IDBlueCommand*) command withResponse: (ReadTagIdResponse*) response { [super readTagIdResponse:command withResponse:response]; RfidTag* tag = [response rfidTag]; NSString* tagId = [tag toString]; NSLog(@"Got tag id: %@", tagId); } -(void) readTagIdFailed: (IDBlueCommand*) command withResponse: (NackResponse*) response { [super readTagIdFailed:command withResponse:response]; NSLog(@"Get tag id failed"); }
An issue has been identified with storeNameAsync and storePinAsync which could cause a breakdown in communication between the IDBLUE iOS SDK and the IDBLUE device. This issue will be corrected in a forthcoming version of the IDBLUE firmware. Until such time, these methods should not be used.
Apple does not provide an iPhone Bluetooth SDK, and instead we are limited to using the External Accessory Framework. For developers used to the user experience of having direct access to the Bluetooth API, you will be disappointed with the External Accessory Framework.
There is no Bluetooth discovery API for the iPhone. Instead, the only thing you can do is request the list of connected accessories using the External Accessory Framework (the IDBLUE iOS SDK internally uses the External Accessory framework). If IDBLUE is not paired with the iPhone, you have know way of searching for it! This is not the typical user experience of Bluetooth applications, and is very different than allowing the user to search for IDBLUE devices in range.
Also, the External Accessory framework has the limitation that only one accessory can be connected at a time. This means to use multiple IDBLUE devices with your iPhone, you must first disconnect from the current IDBLUE device before connecting to the other IDBLUE device, using the Bluetooth Settings on the iPhone (Settings -> General -> Bluetooth).
IDBlueConnection has been renamed to IDBluesession (connectToIDBlue has been renamed to open and disconnectFromIDBlue has been renamed to close) to emphasise the fact that there is no direct Bluetooth connection.
In this release (behind the scenes) when you open a session to an IDBLUE device, the IDBLUE iOS SDK is continuously sending a heartbeat packet to the IDBLUE device every 3 seconds. If a response is not received within 5 seconds the onSessionLost callback method of IDBlueSessionDelegate will be invoked. If or when the IDBLUE iOS SDK starts receiving responses from IDBLUE after a session has been lost, the onSessionRestored callback method of IDBlueSessionDelegate will be invoked.
Old Name | New Name |
---|---|
IDBlueConnection | IDBlueSession |
iPhoneBtConnection | iOSSession |
IDBlueConnectionDelegate | IDBlueSessionDelegate |
The way the IDBLUE iOS SDK is initialized in this release has been changed. Previously, you had to create an instance of IDBlueConnection, create an instance of IDBlueCommandSender, and create a class that derives from IDBlueReceiverDelegate and add that to the IDBlueCommandSender. This has been simplified in this release - create a class that derives from IDBlueiOSSdk and instantiate it. The default init method of IDBlueiOSSdk will initialize everything you need to use the IDBLUE iOS SDK.