BGXpress Framework Introduction

Introduction

The Silicon Labs BGX device provides a bridge between Bluetooth Low Energy (BLE) and Serial communication. BGXpress.framework makes it easy to write an iOS app that interacts with BGX. It supports discovery of BGX devices, connecting and disconnecting, setting and detecting the bus mode of the BGX, sending and receiving data, and OTA (Over The Air) Firmware Updates of the BGX accessed through the Silicon Labs DMS (Device Management Service).

Source Code and License

The BGX mobile libraries are licensed under a permissive open source license and can be found on GitHub.

https://github.com/SiliconLabs/wireless-xpress

Refer to the license file .

Getting Started

Adding BGXpress.framework to your iOS app

If you already have an existing iOS app and would like to add interoperation with a BGX to it, you can do so. First, 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.

BGXEmptyProject

BGXEmptyProject provides you with a starting point for new development using the BGXpress.framework. You can open it by locating the file BGXEmptyProject.xcworkspace and opening it with Xcode. Just like BGXCommander, this app requires a real device and a signing certificate from Apple to interact with BGXdevices.

BGXCommander

BGXCommander uses CocoaPods to get the latest versions of certain third party libraries. In order for it to build properly, you should install Cocoapods. Visit https://cocoapods.org for more information about installing CocoaPods.

To get started with BGXpress.framework, it may be useful to build, run, and examine the BGXCommander sample app. To open it, locate the file called BGXCommander.xcworkspace and open it using Xcode. Note that of this writing Apple does not support CoreBluetooth in the iOS Simulator. The BGXCommander app does run in the Simulator, but does not support connecting to a real BGX device. Instead it uses dummy devices to populate the device list. To interact with a BGX device, you will need an iOS device that supports BLE (iPhone 4s or better) and a signing certificate to build/run BGXCommander on your device. See http://developer.apple.com for details on how to obtain a signing certificate. While you can also get BGXCommander from the iOS App Store, building it yourself allows you to inspect the running code to see how it uses the BGXpress framework.

Understanding BGX

Discovery

To communicate with a BGX device, use the BGXpressScanner class from BGXpress.framework to discovery BGX devices. You can adopt the BGXpressScanDelegate protocol and implement the -(void)deviceDiscovered:(BGXpressDevice *); method to be notified when a BGXDevice is discovered.

BGXDevice

The BGXDevice class represents a BGX. You can use this class to perform various operations on the BGXDevice such as Connect, Disconnect, read, write, as well as checking its properties such as BusMode, identifier, etc. There are two delegate protocols that you can use. The BGXSerialDelegate protocol is used to read and write data and be notified about bus mode changes. The BGXDeviceDelegate protocol is used for detecting device level changes such as change to the connection state.

BusMode

BGX operates in one of three Bus Modes: STREAM, COMMAND, and REMOTE_COMMAND. In COMMAND mode, data that is sent to the BGX using the serial lines is interpreted by a command processor.

In REMOTE_COMMAND mode, data that is sent over Bluetooth stream service is interpreted by the Command API. In STREAM mode, a serial connection is made between serial lines of the BGX and the app using BGXpress.framework.

The command mode can be used to read and write properties of the BGX including characteristics of the serial interface (e.g., baud rate, flow control, and so on), Bluetooth device properties, and the BGX itself. See Bluetooth Xpress Command Reference for more information.

To change the BusMode, use the writeBusMode: method of BGXDevice . To detect changes to the Bus Mode, implement the busModeChanged:forDevice: method of BGXSerialDelegate .

Serial Communication

Your iOS app can send data to and receive data from a connected BGX device. To send data use the writeData: or writeString: methods of BGXDevice . The delegate method dataWrittenForDevice: in the BGXSerialDelegate will be called to indicate the data write operation is complete. When data is available, the dataRead:forDevice: method of BGXSerialDelegate will be called.

Firmware Update

You can use BGXpress.framework to detect when a new version of firmware is available for your BGX. BGX Commander includes signed, encrypted BGX firmware versions available for bootloading. The codebase provides a JSON file and a dictionary for retrieving the requested version.

The firmware update process consists of these steps:

  1. Determine the version of firmware you wish to bootload.
  2. Find this version of firmware within the following method: - (void)retrieveAvailableFirmwareVersions:(void (^)(NSError *, NSArray *))completionBlock; The NSArray contains NSDictionaries created firmware.json, after checking if appropriate files exist. Fields in the NSDictionary:
    • version
    • tag
    • size
    • description
    • file
  3. After the NSDictionary entry has been retried, find the image using the method below. NSString * firmwarePath = [self.bgx_ota_updater getPathOfFirmwareFileWithVersion:version]; Note: you must use the same instance of bgx_ota_updater, which was used to retrieve list of firmware.
  4. Update the firmware image on the BGX.