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

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 and declare the BGXpressService as an intent service to in your AndroidManifest.xml file.

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 .
   • BGXpressService.java
   • BusMode.java
2. Declare the BGXpressService in your AndroidManifest.xml file like this:

    <service
        android:name="com.silabs.bgxpress.BGXpressService"
        android:permission="android.permission.BIND_JOB_SERVICE"
        android:exported="true">
        <meta-data android:name="DMS_API_KEY" android:value="<DMS_API_KEY>"/>
    </service>
   

3. 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 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. Register BroadcastReceiver with the FIRMWARE_VERSIONS_AVAILABLE action added to its IntentFilter.
2. Call BGXpressService.startActionBGXGetFirmwareVersions(context: Context, partIdentifier: String) , where context is Android-platform dependent variable and partIdentifier is 8 character String identifying the type of BGX part.
3. Wait to receive an answer in BroadcastReceiver’s onReceive() method. Answer is delivered as StringExtra with “versions-available-json” name. Convert the received String to JsonArray.
4. Call 'BGXpressService.startActionBGXOtaFirmwareImage(Context context, String deviceAddress, String imagePath, int writeType, String password)' where:
   • context - Android-platform dependent variable,
   • deviceAddress - Address of the device,
   • imagePath - Path to firmware file, you can get it from JsonObjects included in JsonArray, which was received in 1st step (versions-available-json), by passing “file” identifier to given JsonObject,
   • writeType - (optional) BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT or WRITE_TYPE_NO_RESPONSE
   • password - The password to use for the OTA update if one is set.

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 .