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>

Device Discovery

Create an instance of BGXpressScanner and setup a delegate for it:

self.bgxScanner = [[BGXpressScanner alloc] init];
self.bgxScanner.delegate = self;`

The BGXpressScanDelegate protocol has three methods. The bluetoothStateChanged: method will inform you about state changes of CoreBluetooth. To discover devices you must wait until the Bluetooth state isCBManagerStatePoweredOn.

After you have received this notification, call:

[self.bgxManager startScan];

As BGX devices are discovered, the -(void)deviceDiscovered method of the BGXpressScanDelegate protocol is called. The device that was discovered is passed as a parameter and you can access the complete list of devices using the devicesDiscovered property of your BGXpressScanner 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 that are in the disconnected state.

One way to ensure that your list of devices is not stale is to periodically stop scanning and the scan again.

BGXDevice class

The BGXDevice class contains a set of properties for the device and methods for performing actions on the device.

The class has two delegates: a deviceDelegate and a serialDelegate. The BGXDeviceDelegate protocol contains methods for detecting state changes, connection timeout, and changes to the RSSI for the device.

The BGXSerialDelegate has methods used to detect changes to the busMode, as well as methods to detect events when data has been read or written.

- (void)busModeChanged:(BusMode)newBusMode forDevice:(BGXDevice *)device;
- (void)dataRead:(NSData *)newData forDevice:(BGXDevice *)device;
- (void)dataWrittenForDevice:(BGXDevice *)device;

Connecting to a BGX and detecting state changes

To connect to a specific BGX device, call connect method on the BGXDevice object. The connection occurs asynchronously so you must detect a state change on the device object. This can be done using the BGXDeviceDelegate method - (void)stateChangedForDevice:(BGXDevice *)device, of alternatively you could use KVO to observe changes to the deviceState property of the BGXDevice.

Read/Write Serial data

To write serial data to a connected BGX device, use the writeString: or writeData: methods. When the write is complete, the dataWrittenForDevice: method of the BGXSerialDelegate is called.

Bus Mode

To read the BusMode, call the BGXDevice 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 BGXDeviceDelegate delegate method

  • (void)busModeChanged:(BusMode)newBusMode forDevice:(BGXDevice *)device will be called.

Alternatively, you could use KVO to observe changes to the busMode property.

Disconnecting from a BGX

To disconnect from the currently connected BGX device, call the BGXDevice 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 BGXDeviceDelegate method

  • (void)stateChangedForDevice:(BGXDevice *)device; 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.selectedBGXDevice.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 reachable 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 notification 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 method:

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

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.