BGXpress Framework Usage

Using BGXpress.framework

Adding BGXpress to your Xcode project

Add bgxpress.xcodeproj to your app's workspace file. Next, select your app in the Project Navigator in Xcode. Switch to Build Phases and add BGXpress to the list of target dependencies. Then add a new copy files build phase, choose Frameworks as the destination, and add BGXpress.framework to the build phase. This will allow BGXpress.framework to be built as needed and copied into your app bundle.

Including the bgxpress header file

In order to use the BGXpress.framework, you should include the following line:

#import <bgxpress/bgxpress.h>

Using the BGXpressManager class

The BGXpressManager class is used to interact with a BGX device. Create one of these objects in your application and store it in a place where it will be retained while your application is running. The BGXCommander app uses the AppDelegate class to store an instance of the BGXpressManager class. Your app should do this or something that is equivalent. We recommend against using it in a UIViewController instance because those objects may be created and destroyed during the lifecycle of your app.

self.bgxManager = [[BSXpressManager alloc] init];

Creating a BGXpressDelegate

Your application should supply an object conforming to the BGXpressDelegate protocol which has a lifecycle similar to the instance of BGXpressManager you create. The BGXCommander app uses the AppDelegate for this purpose. The file BGXpress.h declares this protocol. The various methods in this protocol are called in order to indicate changes to the Bluetooth state, ConnectionState , BusMode . It is called when devices are discovered, data is read or data is written.

&#64;interface MyDelegate : NSObject <BGXpressDelegate>

self.myDelegate = [[MyDelegate alloc] init];

self.bgxManager.delegate = self.myDelegate;

Device Discovery

To discover devices you must wait until the Bluetooth state is CBManagerStatePoweredOn . You can detect this by implementing the method -(void)bluetoothStateChanged:(CBManagerState)state in your BGXpressDelegate class. After you have received this notification, call:

[self.bgxManager startScan];

As BGX devices are discovered, the -(void)deviceDiscovered method is called. When this happens, you can access the list of devices using the devicesDiscovered property of your BGXpressManager instance.

When you wish to stop scanning call:

[self.bgxManager stopScan];

Note that if BGX devices are turned off or move out of range they are not automatically removed from the discoveredDevices array. When you call startScan, the discoveredDevices array is emptied of devices. One way to ensure that your list of devices is not stale is to periodically stop scanning and the scan again.

Connecting to a BGX

To connect to a specific BGX device, call the BGXpressManager method - (BOOL)connectToDevice:(NSString *)deviceName using the device name. The call will return YES if the device is in the list and the connectionState of the BGXpressManager is SCANNING or DISCONNECTED ; otherwise it will return NO meaning that no connection attempt will occur. This call is asynchronous. To detect when the connection occurs, the BGXpressDelegate for your BGXpressManager will be called using the method - (void)connectionStateChanged:(ConnectionState)newConnectionState; When this is called with the value of CONNECTED , the connection has finished.

Note that BGX devices only support one connection at a time when they are acting as a peripheral.

Detecting device changes

The BGXpressDelegate for your BGXpressManager will be called when certain events occur related to the connected device. For example, the method - (void)dataRead:(NSData *)newData is called when data is received by the BGX.

Read/Write Serial data

To write serial data to a connected BGX device, the BGXpressManager method

Bus Mode

To read the BusMode , call the BGXpressManager method - (BOOL)readBusMode; . This method will return YES if the BusMode can be read. When it is read, the BGXpressDelegate method - (void)busModeChanged:(BusMode)newBusMode will be called.

To change the BusMode , call the BGXpressManager method - (BOOL)writeBusMode:(BusMode)newBusMode; The call will return YES if the BusMode can be written. When the write has completed, the BGXpressDelegate delegate method - (void)busModeChanged:(BusMode)newBusMode will be called.

Disconnecting from a BGX

To disconnect from the currently connected BGX device, call the BGXpressManager method - (BOOL)disconnect; . This method returns YES if the disconnect operation can be performed (i.e. a device is connected or connecting). The call is asynchronous. When the disconnect is complete, your BGXpressDelegate method - (void)connectionStateChanged:(ConnectionState)newConnectionState; will be called.

Firmware Update

Updating the firmware on a BGX device involves the following steps:

1. Select the BGX you wish to update.
2. Get a list of available firmware for the device.
3. Retrieve the image of the firmware to be installed.
4. Install it on the BGX.

Get available firmware using DMS

To get a list of available firmware, first use the unique device id for the BGX to create an instance of bgx_dms :

self.bgx_dms = [[ bgx_dms alloc] initWithBGXUniqueDeviceID: self.bgxpressManager.device_unique_id];

Then call the method

`- (void)retrieveAvailableVersions:(void (^)(NSError *, NSArray *))completionBlock;`

to get the available firmware for the BGX.

The completion block will be called with an array of NSDictionary objects representing firmware versions. Each NSDictionary will contain a version (NSString), a tag (NSString), and a size (NSNumber).

Note that this operation requires the DMS server to be reachable by your iOS device. When the DMS server becomes rechable or unreachable, the notification DMSServerReachabilityChangedNotificationName will be sent with an object of an NSNumber containing a boolean. YES indicates reachable; NO indicates not reachable. You can register to receive this notification using the default NSNotificationCenter. You may receive this notication anytime after you create an instance of bgx_dms . Therefore, you should register for the notification before creating a bgx_dms instance.

Get firmware image using DMS

To retrieve a specific firmware image, use the

`- (void)loadFirmwareVersion:(NSString *)version completion:(void (^)(NSError *, NSString * firmware_path))completionBlock;`

method. The completion routine will be called with the absolute path to the file containing the firmware image.

You can use the same image to update the firmware on more than one BGX provided they are have the same part id. To determine the part id, use the bgx_dms method

+ (NSString *)bgxPartInfoForDeviceID:(NSString *)device_uuid;

Updating a BGX using a firmware image

To update a BGX using a firmware image:

1. Create an instance of BGX_OTA_Updater .
2. Use KVO to observe changes to the properties you are interested in. This will usually be the operationInProgress property, the ota_step property, and the upload_progress property.
3. Call - (void)updateFirmwareWithImageAtPath:(NSString *)path2FWImage withVersion:(NSString *)version .

The simplest way to detect that the firmware update has finished is that the operationsInProgress property has the value ota_firmware_update_complete . The value of ota_step will be ota_step_end when the update has completed without error.