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

Please 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. In order to interact with a BGX device, you will need an iOS device that supports BLE (iPhone 4s or better) and a signing certificate in order 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

In order to communicate with a BGX device, use the BGXpressScanner clas from BGXpress.framework to discovery BGX devices. You can adopt the BGXpressScanDelegate protocol and implement the -(void)deviceDiscovered:(BGXpressDevice *); method in order 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...), 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. In order to use this feature, contact xpres.nosp@m.s@si.nosp@m.labs..nosp@m.com for a DMS API Key. Note that this address is to be used to request secure tokens only. For technical support questions, please submit your question to https://www.silabs.com/support. When you receive this key, add it to the Info.plist file for your app under the key name DMS_API_KEY. BGXpress.framework will access it from this location.

The firmware update process consists of these steps:

  1. Determine the version of firmware loaded onto the BGX.
  2. Request a list of available firmware through DMS.
  3. Decide which firmware to load onto the BGX.
  4. Download the firmware image.
  5. Update the firmware on the BGX.

DMS

DMS (Device Management Service) is used to retrieve available firmware for BGX. There is a module built into BGXpress.framework that supports the operations of retrieving a list of the available firmware for your BGX and loading the firmware onto your mobile device.

DMS Key

In order to use DMS to obtain firmware updates using your app, you should obtain a DMS_API_KEY from Silicon Labs by emailing xpres.nosp@m.s@si.nosp@m.labs..nosp@m.com. Note that this address is to be used to request secure tokens only. For technical support questions, please submit your question to https://www.silabs.com/support. This key can be used by both your Android and iOS apps. It should however be specific to your company and/or product.

OTA Update

BGXpress.framework can be used to update the firmware on BGX devices using a firmware image retrieved through DMS. Your app can register to receive notifications about the progress of the OTA update process in order to display status/progress of the update to the user.