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 is
CBManagerStatePoweredOn
.
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.