BGXpress Framework Introduction

Introduction

The Silicon Labs BGX device provides a bridge between Bluetooth Low Energy (BLE) and Serial communication. The BGXpressService makes it easy to build an Android 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).

BGXpressService is designed to target SDK version 28. It requires a minimum SDK version 23.

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

To use the BGXpressService in your Android app, you will add the BGXpressService.java file to your android project, declare the BGXpressService as an intent service to in your AndroidManifest.xml file, and add your DMS_API_KEY to the manifest. If you don't have a DMS_API_KEY yet, supply an empty string and be aware that you won't be able to access the Silicon Labs DMS Server until you obtain a DMS_API_KEY.

Adding BGXpressService to your Android app

To use the BGXpressService in your Android app, follow these steps:

  1. Add the files BGXpressService.java and BusMode.java into your Android app. You can access these files through the Silicon Labs wireless-xpress github project.
  2. Declare the BGXpressService in your AndroidManifest.xml file like this:
     <service
         android:name=".BGXpressService"
         android:exported="false">
         <meta-data android:name="DMS_API_KEY" android:value="<YOUR DMS API KEY HERE>"/>
     </service>
    
  3. If you do not yet have a DMS_API_KEY, supply an empty string for now.
  4. Add the following declarations to your AndroidManifest.xml file:
     <uses-feature
         android:name="android.hardware.bluetooth_le"
         android:required="true" />
     <uses-permission android:name="android.permission.BLUETOOTH" />
     <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
     <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
     <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    

BGXEmptyProject

BGXEmptyProject provides you with a starting point for new development using the BGXpressService.

BGXCommander

In getting started with BGX, it may be useful to build, run, and examine the BGXCommander sample app. To open it, use Android Studio and choose "Open an Existing Android Studio Project" to open the directory "android/BGXCommander" in the wireless-xpress repository.

Understanding BGX

Discovery

In order to communicate with a BGX device, use the BGXpressService to discovery BGX devices. Create an IntentFilter and add the action BGX_SCAN_DEVICE_DISCOVERED. Use the IntentFilter to register a BroadcastReceiver and override the onReceive() method. Your receiver should check for the action BGX_SCAN_DEVICE_DISCOVERED and retrieve an SerializableExtra called "DeviceRecord". This value is a HashMap containing the keys: "name", "uuid", and "rssi". Most operations to be performed on a BGX will use the "uuid" value (address) as a parameter.

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, send an Intent with the Action ACTION_WRITE_BUS_MODE to the BGXpressService class with an extra called "busmode" containing the desired busMode value and with an extra called "DeviceAddress" containing the device address ("uuid" in the DeviceRecord). To detect changes to the BusMode, register to receive BroadcastIntents with the action BGX_MODE_STATE_CHANGE.

Serial Communication

Your Android app can send data to and receive data from any connected BGX device. To do write data, create an Intent with the action ACTION_WRITE_SERIAL_DATA assign the data to write in an extra called "value", the device uuid/address in an extra called "DeviceAddress" and set the class to BGXpressService and start the service. To receive data, register to receive BroadcastIntents with the action BGX_DATA_RECEIVED.

Firmware Update

You can use BGXpressService 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. This key is read from the app manifest. The BGXCommander sample is set to read this value from the environment, but you could also just directly specify it in the manifest file under the key "DMS_API_KEY".

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 Managemnt Service) is used to retrieve available firmware for BGX. There is a module built into BGXpressService that supports the operations of retriving a list of the available firmware for your BGX and loading the firmware onto your mobile device.

To retrieve the firmware list, you will create an Intent with the action ACTION_DMS_GET_VERSIONS. This intent will need to contain an extra "bgx_part-id" with the value you get from an extra (also "bgx-part-id") BGX_DEVICE_INFO broadcast intent and also a "DeviceAddress" extra. When this operations completes, a broadcast intent will be sent with the action DMS_VERSIONS_AVAILABLE. This contains a JSON list of available versions in an extra called "versions-available-json". This list

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

BGXpressService can be used to udpate the firmware on BGX devices using a firmware update retrieved through DMS. Your app can register a BroadcastReceiver to receive OTA_STATUS_MESSAGE Broadcast Intents from the BGXpressService.