Frequently Asked Questions / How do I initialize the IDBLUE iOS SDK?

NOTE: This is taken from the IDBLUE iOS SDK documentation. Please refer to the SDK documentation for more details.

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.

Create a class named 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 like:

#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 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:

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:

  • Override the session event callback methods in IDBlueApi
  • Create a separate class that implements the protocol ISessionHandler and register it with the IDBlueiOSSdk using addSessionDelegate

Overriding the callback methods in IDBlueApi is the simpler method. 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:

  • openFirstIDBlueDevice should be called when you application starts and when it resumes from the background
  • closeSession should be called when you application goes to the background and when it terminates
  • You can use the UIApplicationDelegate protocol to detect when your application resumes from the background, is going to the background and when it terminates.

Now that we have the communication completed, let’s turn our attention to sending commands to IDBLUE and handling responses.

The IDBLUE SDK is designed asynchronously. That is, when you send a command to IDBLUE, the IDBLUE 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: the IDBlueCoreApi is itself a ResponseHandler (a 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:

You want IDBLUE to scan for an RFID tag, and return back the tag identifier to our application. To do this you would call readTagId. Asynchronously, one of 2 possible callback methods will be invoked: either readTagIdResponse or readTagIdFailed, depending on whether an RFID tag was read successfully or not.

// 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");
}

Posted in: Apple iOS, Software and Development