BGXpress Framework Usage
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:
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 is
After you have received this notification, call:
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
When you wish to stop scanning call:
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.
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.
To read the
BusMode, call the
-(BOOL)readBusMode;. This method will return YES if the
BusMode can be read. When it is read, the
-(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
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
- (void)stateChangedForDevice:(BGXDevice *)device; will be called.
Updating the firmware on a BGX device involves the following steps:
- Select the BGX you wish to update.
- Get a list of available firmware for the device.
- Retrieve the image of the firmware to be installed.
- 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
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
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
+ (NSString *)bgxPartInfoForDeviceID:(NSString *)device_uuid;
Updating a BGX using a firmware image
To update a BGX using a firmware image:
- Create an instance of
- Use KVO to observe changes to the properties you are interested in. This will usually be the
ota_stepproperty, and the
- (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.