ACS Bluetooth iOS/Mac OS X Library  1.0.0
 All Classes Files Functions Variables Typedefs Enumerator Properties
ACS Bluetooth iOS/Mac OS X Library Documentation

Introduction

This library provides classes and protocols for communicating with ACS Bluetooth readers on iOS (5.0 or above) and Mac OS X (10.7 or above).

To use the library on iOS, your app must include CoreBluetooth header file from iOS SDK and ACSBluetooth header file.

//
// MYViewController.m
//
#import "MYViewController.h"
#import <CoreBluetooth/CoreBluetooth.h>
@interface MYViewController () <CBCentralManagerDelegate, ABTBluetoothReaderManagerDelegate, ABTBluetoothReaderDelegate>
@end
@implementation MYViewController {
CBCentralManager *_centralManager;
CBPeripheral *_peripheral;
ABTBluetoothReaderManager *_bluetoothReaderManager;
ABTBluetoothReader *_bluetoothReader;
...
}
- (void)viewDidLoad
{
[super viewDidLoad];
// Do any additional setup after loading the view, typically from a nib.
...
_centralManager = [[CBCentralManager alloc] initWithDelegate:self queue:nil];
_bluetoothReaderManager = [[ABTBluetoothReaderManager alloc] init];
_bluetoothReaderManager.delegate = self;
...
}
...

To use the library on Mac OS X, your app must include IOBluetooth header file from Mac OS X SDK and ACSBluetooth header file.

//
// MYAppDelegate.m
//
#import "MYAppDelegate.h"
#import <IOBluetooth/IOBluetooth.h>
@interface ABDAppDelegate () <CBCentralManagerDelegate, ABTBluetoothReaderManagerDelegate, ABTBluetoothReaderDelegate>
@end
@implementation ABDAppDelegate {
CBCentralManager *_centralManager;
CBPeripheral *_peripheral;
ABTBluetoothReaderManager *_bluetoothReaderManager;
ABTBluetoothReader *_bluetoothReader;
...
}
- (void)applicationDidFinishLaunching:(NSNotification *)aNotification
{
// Insert code here to initialize your application
_centralManager = [[CBCentralManager alloc] initWithDelegate:self queue:nil];
_bluetoothReaderManager = [[ABTBluetoothReaderManager alloc] init];
_bluetoothReaderManager.delegate = self;
...
}
...

Your app must create CBCentralManager and ABTBluetoothReaderManager objects and then assign a delegate object to them. Therefore, your delegate object will receive the events from central manager and Bluetooth reader manager.

You must implement centralManagerDidUpdateState: method to check if Bluetooth low energy is supported and available to use.

- (void)centralManagerDidUpdateState:(CBCentralManager *)central {
// TODO: Check if Bluetooth low energy is supported and available to use.
...
}

Discovering peripherals

You can discover peripherals by calling scanForPeripheralsWithServices:options: method of the CBCentralManager class.

[_centralManager scanForPeripheralsWithServices:nil options:nil];

When the peripheral is discovered, the central manager calls centralManager:didDiscoverPeripheral:advertisementData:RSSI: method of its delegate object. You need to store the returned CBPeripheral object.

- (void)centralManager:(CBCentralManager *)central didDiscoverPeripheral:(CBPeripheral *)peripheral advertisementData:(NSDictionary *)advertisementData RSSI:(NSNumber *)RSSI {
// Store the peripheral.
_peripheral = peripheral;
}

When you have found the peripheral, you can stop the scanning for other devices to save the power.

[_centralManager stopScan];

Connecting to the peripheral

After finding the peripheral, you can connect it by calling connectPeripheral:options: method of the CBCentralManager class.

[_centralManager connectPeripheral:_peripheral options:nil];

If the connection is successful, the central manager will call centralManager:didConnectPeripheral: method of its delegate object. Otherwise, it will call centralManager:didFailToConnectPeripheral: method of its delegate object.

- (void)centralManager:(CBCentralManager *)central didConnectPeripheral:(CBPeripheral *)peripheral {
// Detect the Bluetooth reader.
[_bluetoothReaderManager detectReaderWithPeripheral:peripheral];
}
- (void)centralManager:(CBCentralManager *)central didFailToConnectPeripheral:(CBPeripheral *)peripheral error:(NSError *)error {
// TODO: Show the connection error.
// ...
}

Detecting the Bluetooth reader

After the peripheral is connected, you can detect the Bluetooth reader by calling detectReaderWithPeripheral: (ABTBluetoothReaderManager) method of the ABTBluetoothReaderManager class. The Bluetooth reader manager calls bluetoothReaderManager:didDetectReader:peripheral:error: (ABTBluetoothReaderManagerDelegate-p) method of its delegate object to return the result.

- (void)bluetoothReaderManager:(ABTBluetoothReaderManager *)bluetoothReaderManager didDetectReader:(ABTBluetoothReader *)reader peripheral:(CBPeripheral *)peripheral error:(NSError *)error {
if (error != nil) {
// TODO: Show the error.
// ...
} else {
// Store the Bluetooth reader.
_bluetoothReader = reader;
_bluetoothReader.delegate = self;
// Attach the peripheral to the Bluetooth reader.
[_bluetoothReader attachPeripheral:peripheral];
}
}

Attaching the peripheral

You can attach the peripheral by calling attachPeripheral: (ABTBluetoothReader) method of the ABTBluetoothReader class. The Bluetooth reader calls bluetoothReader:didAttachPeripheral:error: (ABTBluetoothReaderDelegate-p) method of its delegate object to return the result.

- (void)bluetoothReader:(ABTBluetoothReader *)bluetoothReader didAttachPeripheral:(CBPeripheral *)peripheral error:(NSError *)error {
// TODO: Show the error.
// ...
}

Detaching the peripheral

If you have finished the operation with the Bluetooth reader, you can detach the peripheral by calling detach (ABTBluetoothReader) method of the ABTBluetoothReader class.

[_bluetoothReader detach];

Disconnecting the peripheral

If your Bluetooth reader is no longer used, you can disconnect the peripheral by calling cancelPeripheralConnection: method of the CBCentralManager class.

[_centralManager cancelPeripheralConnection:_peripheral];

The central manager calls centralManager:didDisconnectPeripheral:error: of its delegate object.

- (void)centralManager:(CBCentralManager *)central didDisconnectPeripheral:(CBPeripheral *)peripheral error:(NSError *)error {
// TODO: Show the error.
// ...
}

Getting the device information

You can get the device information by calling getDeviceInfoWithType: (ABTBluetoothReader) method of ABTBluetoothReader class. If the device information is not supported, the method will returns NO.

[_bluetoothReader getDeviceInfoWithType:ABTBluetoothReaderDeviceInfoSystemId];
[_bluetoothReader getDeviceInfoWithType:ABTBluetoothReaderDeviceInfoModelNumberString];
[_bluetoothReader getDeviceInfoWithType:ABTBluetoothReaderDeviceInfoSerialNumberString];
[_bluetoothReader getDeviceInfoWithType:ABTBluetoothReaderDeviceInfoFirmwareRevisionString];
[_bluetoothReader getDeviceInfoWithType:ABTBluetoothReaderDeviceInfoHardwareRevisionString];
[_bluetoothReader getDeviceInfoWithType:ABTBluetoothReaderDeviceInfoManufacturerNameString];

The Bluetooth reader calls bluetoothReader:didReturnDeviceInfo:type:error: (ABTBluetoothReaderDelegate-p) method of its delegate object to return the device information.

- (void)bluetoothReader:(ABTBluetoothReader *)bluetoothReader didReturnDeviceInfo:(NSObject *)deviceInfo type:(ABTBluetoothReaderDeviceInfo)type error:(NSError *)error {
if (error != nil) {
// TODO: Show the error.
// ...
} else {
switch (type) {
// TODO: Show the system ID.
// ...
break;
// TODO: Show the model number.
// ...
break;
// TODO: Show the serial number.
// ...
break;
// TODO: Show the firmware revision.
// ...
break;
// TODO: Show the hardware revision.
// ...
break;
// TODO: Show the manufacturer name.
// ...
break;
default:
break;
}
}
}

Working with ACR3901U-S1 reader

If the ACR3901U-S1 reader is detected, the returned ABTBluetoothReader object will be an instance of ABTAcr3901us1Reader class. To invoke the method, you can cast it as ABTAcr3901us1Reader object.

if ([_bluetoothReader isKindOfClass:[ABTAcr3901us1Reader class]]) {
ABTAcr3901us1Reader *reader = (ABTAcr3901us1Reader *) _bluetoothReader;
// TODO: Invoke the method.
// ...
}

Getting the battery status

If the battery status is changed, the Bluetooth reader calls bluetoothReader:didChangeBatteryStatus:error: (ABTBluetoothReaderDelegate-p) method of its delegate object to return the battery status.

- (void)bluetoothReader:(ABTBluetoothReader *)bluetoothReader didChangeBatteryStatus:(ABTBluetoothReaderBatteryStatus)batteryStatus error:(NSError *)error {
// TODO: Process the battery status.
// ...
}

If you want to get the battery status again, you can call getBatteryStatus (ABTAcr3901us1Reader) method of ABTAcr3901us1Reader class.

[reader getBatteryStatus];

Working with ACR1255U-J1 reader

If the ACR1255U-J1 reader is detected, the returned ABTBluetoothReader object will be an instance of ABTAcr1255uj1Reader class. To invoke the method, you can cast it as ABTAcr1255uj1Reader object.

if ([_bluetoothReader isKindOfClass:[ABTAcr1255uj1Reader class]]) {
ABTAcr1255uj1Reader *reader = (ABTAcr1255uj1Reader *) _bluetoothReader;
// TODO: Invoke the method.
// ...
}

Getting the battery level

If the battery level is changed, the Bluetooth reader calls bluetoothReader:didChangeBatteryLevel:error: (ABTBluetoothReaderDelegate-p) method of its delegate object to return the battery level.

- (void)bluetoothReader:(ABTBluetoothReader *)bluetoothReader didChangeBatteryLevel:(NSUInteger)batteryLevel error:(NSError *)error {
// TODO: Process the battery level.
// ...
}

If you want to get the battery level again, you can call getBatteryLevel (ABTAcr1255uj1Reader) method of ABTAcr1255uj1Reader class.

[reader getBatteryLevel];

Authenticating the Bluetooth reader

Before performing the operation, you must authenticate the Bluetooth reader by calling authenticateWithMasterKey: (ABTBluetoothReader) method of ABTBluetoothReader class with the master key.

[reader authenticateWithMasterKey:_masterKey];

The Bluetooth reader calls bluetoothReader:didAuthenticateWithError: (ABTBluetoothReaderDelegate-p) method of its delegate object to return the authentication result.

- (void)bluetoothReader:(ABTBluetoothReader *)bluetoothReader didAuthenticateWithError:(NSError *)error {
// TODO: Show the error.
// ...
}

Powering on the card

If the Bluetooth reader is authenticated successfully, you can power on the card by calling powerOnCard (ABTBluetoothReader) method of ABTBluetoothReader class.

[_bluetoothReader powerOnCard];

The Bluetooth reader calls bluetoothReader:didReturnAtr:error: (ABTBluetoothReaderDelegate-p) method of its delegate object to return the ATR string.

- (void)bluetoothReader:(ABTBluetoothReader *)bluetoothReader didReturnAtr:(NSData *)atr error:(NSError *)error {
// TODO: Process the ATR string from the card.
// ...
}

Powering off the card

If the Bluetooth reader is authenticated successfully, you can power off the card by calling powerOffCard (ABTBluetoothReader) method of ABTBluetoothReader class.

[_bluetoothReader powerOffCard];

The Bluetooth reader calls bluetoothReader:didPowerOffCardWithError: (ABTBluetoothReaderDelegate-p) method of its delegate object to notify the result.

- (void)bluetoothReader:(ABTBluetoothReader *)bluetoothReader didPowerOffCardWithError:(NSError *)error {
// TODO: Show the error.
// ...
}

Getting the card status

If the Bluetooth reader is authenticated successfully, you can get the card status by calling getCardStatus (ABTBluetoothReader) method of ABTBluetoothReader class.

[_bluetoothReader getCardStatus];

The Bluetooth reader calls bluetoothReader:didReturnCardStatus:error: (ABTBluetoothReaderDelegate-p) method of its delegate object to return the card status.

- (void)bluetoothReader:(ABTBluetoothReader *)bluetoothReader didReturnCardStatus:(ABTBluetoothReaderCardStatus)cardStatus error:(NSError *)error {
// TODO: Process the card status.
// ...
}

If the card status is changed, the Bluetooth reader calls bluetoothReader:didChangeCardStatus:error: (ABTBluetoothReaderDelegate-p) method of its delegate object to return the card status.

- (void)bluetoothReader:(ABTBluetoothReader *)bluetoothReader didChangeCardStatus:(ABTBluetoothReaderCardStatus)cardStatus error:(NSError *)error {
// TODO: Process the card status.
// ...
}

Transmitting the APDU

If the Bluetooth reader is authenticated successfully, you can transmit the APDU to the card by calling transmitApdu: (ABTBluetoothReader) method of ABTBluetoothReader class.

[_bluetoothReader transmitApdu:_commandApdu];

The Bluetooth reader calls bluetoothReader:didReturnResponseApdu:error: (ABTBluetoothReaderDelegate-p) method of its delegate object to return the response APDU.

- (void)bluetoothReader:(ABTBluetoothReader *)bluetoothReader didReturnResponseApdu:(NSData *)apdu error:(NSError *)error {
// TODO: Process the response APDU.
// ...
}

Transmitting the escape command

If the Bluetooth reader is authenticated successfully, you can transmit the escape command by calling transmitEscapeCommand: (ABTBluetoothReader) method of ABTBluetoothReader class.

[_bluetoothReader transmitEscapeCommand:_escapeCommand];

The Bluetooth reader calls bluetoothReader:didReturnEscapeResponse:error: (ABTBluetoothReaderDelegate-p) method of its delegate object to return the escape response.

- (void)bluetoothReader:(ABTBluetoothReader *)bluetoothReader didReturnEscapeResponse:(NSData *)response error:(NSError *)error {
// TODO: Process the escape response.
// ...
}