BGXpressService

The Silicon Labs BGX device provides a bridge between Bluetooth Low Energy (BLE) and Serial communication. More...

Classes

class  com.silabs.bgxpress.BGXpressService
 An intent service which is used to control and communicate with a BGX device. More...
 

Detailed Description

The Silicon Labs BGX device provides a bridge between Bluetooth Low Energy (BLE) and Serial communication.

BGXpressService is an Android Intent Service which makes it easier to write an Android app which interacts with BGX. It supports discovery of BGX devices, connecting and disconnecting, setting and detecting changes to the bus mode of the BGX, sending and receiving serial data, and OTA (Over The Air) Firmware Updates of the BGX accessed through the Silicon Labs DMS (Device Management Service).

Remarks
BGXpressService is designed to target Android SDK 27 and supports a minimum SDK version 23.
BGXpressService is currently designed for connecting to one BGX at a time.

Class Documentation

◆ com::silabs::bgxpress::BGXpressService

class com::silabs::bgxpress::BGXpressService

An intent service which is used to control and communicate with a BGX device.

Inherits IntentService.

Public Member Functions

BGXpressService ()
 
void onCreate ()
 
void onDestroy ()
 

Static Public Member Functions

static void startActionStartScan (Context context)
 Starts this service to perform action Start Scan. More...
 
static void startActionStopScan (Context context)
 Starts this service to perform action Stop Scan. More...
 
static void startActionBGXConnect (Context context, String deviceAddress)
 startActionBGXConnect More...
 
static void startActionBGXCancelConnect (Context context, String deviceAddress)
 startActionBGXCancelConnect More...
 
static void startActionBGXDisconnect (Context context, String deviceAddress)
 startActionBGXDisconnect More...
 
static void getBGXDeviceInfo (Context context, String deviceAddress)
 getBGXDeviceInfo More...
 
static boolean setBGXAcknowledgedWrites (String deviceAddress, boolean acknowledgedWrites)
 
static boolean setBGXAcknowledgedReads (String deviceAddress, boolean acknowledgedReads)
 
static BGX_CONNECTION_STATUS getBGXDeviceConnectionStatus (String deviceAddress)
 
static Integer getBGXBootloaderVersion (String deviceAddress)
 getBGXBootloaderVersion More...
 
static String getFirmwareRevision (String deviceAddress)
 getFirmwareRevision More...
 

Static Public Attributes

static final String ACTION_START_SCAN
 The BGXpressService receives this intent and it begins scanning. More...
 
static final String ACTION_STOP_SCAN
 The BGXpressService receives this intent and it stops scanning. More...
 
static final String ACTION_BGX_CONNECT
 This is sent to cause the BGXpressService to connect to a BGX. More...
 
static final String ACTION_BGX_DISCONNECT
 This is sent to cause the BGXpressService to disconnect from a connected BGX. More...
 
static final String ACTION_BGX_CANCEL_CONNECTION
 Attempt to cancel an in-progress connection operation. More...
 
static final String ACTION_READ_BUS_MODE
 Reads the bus mode. More...
 
static final String ACTION_WRITE_BUS_MODE
 Writes the bus mode. More...
 
static final String ACTION_WRITE_SERIAL_DATA
 Writes data to the BGX. More...
 
static final String ACTION_WRITE_SERIAL_BIN_DATA
 Writes byte data to the BGX. More...
 
static final String ACTION_DMS_GET_VERSIONS
 Gets the firmware versions available from DMS. More...
 
static final String ACTION_DMS_REQUEST_VERSION
 This request causes the specified DMS version to be loaded onto the phone. More...
 
static final String ACTION_OTA_WITH_IMAGE
 Extras: image_path - String - path to the image file. More...
 
static final String ACTION_OTA_CANCEL
 Attempts to cancel an OTA operation in progress. More...
 
static final String BGX_CONNECTION_STATUS_CHANGE
 Extras: bgx-connection-status - a value from the BGX_CONNECTION_STATUS enum which is the new status. More...
 
static final String BGX_MODE_STATE_CHANGE
 Broadcast Intent which indicates a state change in the bgxss mode. More...
 
static final String BUS_MODE_ERROR_PASSWORD_REQUIRED
 This intent is sent when a password is required to change the bus mode to remote command mode. More...
 
static final String BGX_DATA_RECEIVED
 Extras: data - String - contains the data that was received from the BGX. More...
 
static final String BGX_SCAN_MODE_CHANGE
 This change is sent when scanning begins or ends. More...
 
static final String BGX_MTU_CHANGE
 BGX_MTU_CHANGE. More...
 
static final String BGX_SCAN_DEVICE_DISCOVERED
 This is sent as a broadcast intent when a BGX device is discovered during scanning. More...
 
static final String DMS_VERSION_LOADED
 Notification that a specific version has been loaded and is attached to the intent as "file_path". More...
 
static final String OTA_STATUS_MESSAGE
 This contains the following extras: ota_failed : boolean. More...
 
static final String BGX_INVALID_GATT_HANDLES
 Notification message that is sent when invalid GATT handles are detected. More...
 
static final String BGX_DEVICE_INFO
 This is sent when connection state becomes connected for the device. More...
 
static final String BGX_CONNECTION_ERROR
 This is sent when the BGXConnectionState moves from Connecting to Disconnecting due to an error. More...
 
static final String DMS_VERSIONS_AVAILABLE
 Broadcast intent sent when the list of versions is retrieved from DMS. More...
 
static Handler mHandler
 

Protected Member Functions

void onHandleIntent (Intent intent)
 

Constructor & Destructor Documentation

◆ BGXpressService()

com.silabs.bgxpress.BGXpressService.BGXpressService ( )
inline

Member Function Documentation

◆ onCreate()

void com.silabs.bgxpress.BGXpressService.onCreate ( )
inline

◆ onDestroy()

void com.silabs.bgxpress.BGXpressService.onDestroy ( )
inline

◆ startActionStartScan()

static void com.silabs.bgxpress.BGXpressService.startActionStartScan ( Context  context)
inlinestatic

Starts this service to perform action Start Scan.

If the service is already performing a task this action will be queued.

Parameters
contextInterface to global information about an Android application environment.
See also
IntentService

◆ startActionStopScan()

static void com.silabs.bgxpress.BGXpressService.startActionStopScan ( Context  context)
inlinestatic

Starts this service to perform action Stop Scan.

If the service is already performing a task this action will be queued.

Parameters
contextInterface to global information about an Android application environment.
See also
IntentService

◆ startActionBGXConnect()

static void com.silabs.bgxpress.BGXpressService.startActionBGXConnect ( Context  context,
String  deviceAddress 
)
inlinestatic

startActionBGXConnect

Attempt to connect to the specified device. The process of the connection can be tracked by receiving a series of BGX_CONNECTION_STATUS_CHANGE intents.

Parameters
contextInterface to global information about an Android application environment.
deviceAddressthe Bluetooth address of the device to which to connect.

◆ startActionBGXCancelConnect()

static void com.silabs.bgxpress.BGXpressService.startActionBGXCancelConnect ( Context  context,
String  deviceAddress 
)
inlinestatic

startActionBGXCancelConnect

Attempt to cancel an in-progress connection operation.

Parameters
contextInterface to global information about an Android application environment.
deviceAddressThe Bluetooth address of the device to which to cancel the connection in progress.

◆ startActionBGXDisconnect()

static void com.silabs.bgxpress.BGXpressService.startActionBGXDisconnect ( Context  context,
String  deviceAddress 
)
inlinestatic

startActionBGXDisconnect

Disconnect a BGX Device.

Parameters
contextInterface to global information about an Android application environment.
deviceAddressthe Bluetooth address of the device to which you wish to connect.

◆ getBGXDeviceInfo()

static void com.silabs.bgxpress.BGXpressService.getBGXDeviceInfo ( Context  context,
String  deviceAddress 
)
inlinestatic

getBGXDeviceInfo

Starts an operation to get the device info which is the part id and the device uuid.

Parameters
contextInterface to global information about an Android application environment.
deviceAddressThe device to which the operation pertains.

◆ setBGXAcknowledgedWrites()

static boolean com.silabs.bgxpress.BGXpressService.setBGXAcknowledgedWrites ( String  deviceAddress,
boolean  acknowledgedWrites 
)
inlinestatic

◆ setBGXAcknowledgedReads()

static boolean com.silabs.bgxpress.BGXpressService.setBGXAcknowledgedReads ( String  deviceAddress,
boolean  acknowledgedReads 
)
inlinestatic

◆ getBGXDeviceConnectionStatus()

static BGX_CONNECTION_STATUS com.silabs.bgxpress.BGXpressService.getBGXDeviceConnectionStatus ( String  deviceAddress)
inlinestatic

◆ getBGXBootloaderVersion()

static Integer com.silabs.bgxpress.BGXpressService.getBGXBootloaderVersion ( String  deviceAddress)
inlinestatic

getBGXBootloaderVersion

Gets the BGXBootloader version if possible to do so. This value is available only after the device is connected.

Parameters
deviceAddressAddress of the device to retrieve the bootloader version
Returns
-1 on error, or the bootloader version (a positive integer).

◆ getFirmwareRevision()

static String com.silabs.bgxpress.BGXpressService.getFirmwareRevision ( String  deviceAddress)
inlinestatic

getFirmwareRevision

Parameters
deviceAddressAddress of the device to retrieve the firmware revision
Returns
String containing the firmware version if available, otherwise NULL.

◆ onHandleIntent()

void com.silabs.bgxpress.BGXpressService.onHandleIntent ( Intent  intent)
inlineprotected

Member Data Documentation

◆ ACTION_START_SCAN

final String com.silabs.bgxpress.BGXpressService.ACTION_START_SCAN
static

The BGXpressService receives this intent and it begins scanning.

There is no need to directly send this. You can call startActionStartScan() instead.

◆ ACTION_STOP_SCAN

final String com.silabs.bgxpress.BGXpressService.ACTION_STOP_SCAN
static

The BGXpressService receives this intent and it stops scanning.

There is no need to directly send this. You can call startActionStopScan() instead.

◆ ACTION_BGX_CONNECT

final String com.silabs.bgxpress.BGXpressService.ACTION_BGX_CONNECT
static

This is sent to cause the BGXpressService to connect to a BGX.

Extras:

DeviceAddress - String - The bluetooth address of the device to which to connect.

There is no need to directly send this. You can call startActionBGXConnect() using the device address instead.

◆ ACTION_BGX_DISCONNECT

final String com.silabs.bgxpress.BGXpressService.ACTION_BGX_DISCONNECT
static

This is sent to cause the BGXpressService to disconnect from a connected BGX.

◆ ACTION_BGX_CANCEL_CONNECTION

final String com.silabs.bgxpress.BGXpressService.ACTION_BGX_CANCEL_CONNECTION
static

Attempt to cancel an in-progress connection operation.

There is no need to call this directly. Use startActionBGXCancelConnect() instead.

◆ ACTION_READ_BUS_MODE

final String com.silabs.bgxpress.BGXpressService.ACTION_READ_BUS_MODE
static

Reads the bus mode.

When the read operation completes, a broadcast intent will be sent with the action BGX_MODE_STATE_CHANGE.

◆ ACTION_WRITE_BUS_MODE

final String com.silabs.bgxpress.BGXpressService.ACTION_WRITE_BUS_MODE
static

Writes the bus mode.

The service will not send a notification to indicate that it succeeded at this time.

Extras: busmode - int - one of the values from BusMode: STREAM_MODE, LOCAL_COMMAND_MODE, or REMOTE_COMMAND_MODE. DeviceAddress - String the address of the device on which to set the bus mode. password - String - If supplied, this value will be used as the password for REMOTE_COMMAND_MODE

◆ ACTION_WRITE_SERIAL_DATA

final String com.silabs.bgxpress.BGXpressService.ACTION_WRITE_SERIAL_DATA
static

Writes data to the BGX.

value - String - the data to be written.

◆ ACTION_WRITE_SERIAL_BIN_DATA

final String com.silabs.bgxpress.BGXpressService.ACTION_WRITE_SERIAL_BIN_DATA
static

Writes byte data to the BGX.

value - byte [] - the byte array to be written.

◆ ACTION_DMS_GET_VERSIONS

final String com.silabs.bgxpress.BGXpressService.ACTION_DMS_GET_VERSIONS
static

Gets the firmware versions available from DMS.

Either bgx-part-id or bgx-part-identifier (preferred) must be specified. bgx-part-identifier is used if both are specified.

Extras: bgx-part-id - An enum value from BGXPartID. Preserved for compatibility. bgx-part-identifier - an 8 character string identifying the type of BGX (preferred).

◆ ACTION_DMS_REQUEST_VERSION

final String com.silabs.bgxpress.BGXpressService.ACTION_DMS_REQUEST_VERSION
static

This request causes the specified DMS version to be loaded onto the phone.

When finished, the broadcast intent DMS_VERSION_LOADED is sent. Either bgx-part-id or bgx-part-identifier (preferred) must be specified. bgx-part-identifier is used if both are specified.

Extras: bgx-part-id - BGXPartID - Optional one of the following values: BGX13S or BGX13P (Preserved for compatibility) bgx-part-identifier - String - an 8 character string identifying the kind of BGX (Preferred) dms-version - String - the DMS version number you want to retrieve.

◆ ACTION_OTA_WITH_IMAGE

final String com.silabs.bgxpress.BGXpressService.ACTION_OTA_WITH_IMAGE
static

Extras: image_path - String - path to the image file.

You could get this from a DMS_VERSION_LOADED broadcast intent. DeviceAddress - String - The address of the device to update. password - String - the password to use for the OTA update if one is set.

◆ ACTION_OTA_CANCEL

final String com.silabs.bgxpress.BGXpressService.ACTION_OTA_CANCEL
static

Attempts to cancel an OTA operation in progress.

If the cancellation is successful you will get an OTA_STATUS_MESSAGE where the ota_status is UserCanceled

◆ BGX_CONNECTION_STATUS_CHANGE

final String com.silabs.bgxpress.BGXpressService.BGX_CONNECTION_STATUS_CHANGE
static

Extras: bgx-connection-status - a value from the BGX_CONNECTION_STATUS enum which is the new status.

device - a BluetoothDevice (not present for DISCONNECTED). DeviceAddress - address of the BGX.

◆ BGX_MODE_STATE_CHANGE

final String com.silabs.bgxpress.BGXpressService.BGX_MODE_STATE_CHANGE
static

Broadcast Intent which indicates a state change in the bgxss mode.

Extras: busmode - int - one of the values from BusMode: STREAM_MODE, LOCAL_COMMAND_MODE, or REMOTE_COMMAND_MODE.

◆ BUS_MODE_ERROR_PASSWORD_REQUIRED

final String com.silabs.bgxpress.BGXpressService.BUS_MODE_ERROR_PASSWORD_REQUIRED
static

This intent is sent when a password is required to change the bus mode to remote command mode.

This contains the following extras: DeviceAddress : the address of the device.

◆ BGX_DATA_RECEIVED

final String com.silabs.bgxpress.BGXpressService.BGX_DATA_RECEIVED
static

Extras: data - String - contains the data that was received from the BGX.

DeviceAddress - string - the address of the BGX that received data.

◆ BGX_SCAN_MODE_CHANGE

final String com.silabs.bgxpress.BGXpressService.BGX_SCAN_MODE_CHANGE
static

This change is sent when scanning begins or ends.

It has one extra.

isscanning - boolean - indicates whether scanning is happening.

◆ BGX_MTU_CHANGE

final String com.silabs.bgxpress.BGXpressService.BGX_MTU_CHANGE
static

BGX_MTU_CHANGE.

Parameters
deviceAddressdevice address
statusoperation status
mtuthe new mtu size

◆ BGX_SCAN_DEVICE_DISCOVERED

final String com.silabs.bgxpress.BGXpressService.BGX_SCAN_DEVICE_DISCOVERED
static

This is sent as a broadcast intent when a BGX device is discovered during scanning.

Parameters
DeviceRecorda HashMap containing information about the device that was discovered. The HashMap contains the following keys: name - Device name uuid - Device address rssi - the device's current RSSI.

◆ DMS_VERSION_LOADED

final String com.silabs.bgxpress.BGXpressService.DMS_VERSION_LOADED
static

Notification that a specific version has been loaded and is attached to the intent as "file_path".

file_path - string of the path to the file containing the version.

◆ OTA_STATUS_MESSAGE

final String com.silabs.bgxpress.BGXpressService.OTA_STATUS_MESSAGE
static

This contains the following extras: ota_failed : boolean.

True means it failed. Use false as the default. ota_status : OTA_Status enum. Tells the current status of the OTA. Use Invalid as the default. bytes_sent : int - number of bytes transfered in the firmware image. Not always present.

◆ BGX_INVALID_GATT_HANDLES

final String com.silabs.bgxpress.BGXpressService.BGX_INVALID_GATT_HANDLES
static

Notification message that is sent when invalid GATT handles are detected.

Invalid GATT handles result in operations failing to work correctly. Invalid GATT handles occur as a result of a firmware update that adds or removes Bluetooth characteristics and/or services to the BGX when you have an existing bond on your Android device. To fix this condition, you would need to go to the Bluetooth Settings on your Android device, select the BGX, and choose "Forget". The next time you connect, the bond will be reestablished. This broadcast intent will be sent when the BGXpressService is unable to read a valid part id or when it is unable to read a valid firmware version. Your app should respond to this broadcast intent by showing the user a message explaining the situation and telling them how to recover from it.

This broadcast intent contains the following extras: DeviceAddress: String - The address of the BGX device. DeviceName: String - The name of the BGX device.

◆ BGX_DEVICE_INFO

final String com.silabs.bgxpress.BGXpressService.BGX_DEVICE_INFO
static

This is sent when connection state becomes connected for the device.

param: bgx-device-uuid - a String param: bgx-part-id - a BGXPartID param: bgx-part-identifier - an 8 character String that identifies the type of BGX.

◆ BGX_CONNECTION_ERROR

final String com.silabs.bgxpress.BGXpressService.BGX_CONNECTION_ERROR
static

This is sent when the BGXConnectionState moves from Connecting to Disconnecting due to an error.

param: status - a GATT Status value as returned by the Android GATT API.

◆ DMS_VERSIONS_AVAILABLE

final String com.silabs.bgxpress.BGXpressService.DMS_VERSIONS_AVAILABLE
static

Broadcast intent sent when the list of versions is retrieved from DMS.

Extras: versions-available-json - String - Contains JSON response from DMS with the list of firmware versions available.

◆ mHandler

Handler com.silabs.bgxpress.BGXpressService.mHandler
static