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:
- 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 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:
- Create an instance of
BGX_OTA_Updater
. - Use KVO to observe changes to the properties you are interested in. This will usually be the
operationInProgress
property, theota_step
property, and theupload_progress
property. - 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.