BGXpress Service Usage

Using BGXpressService

Adding BGXpressService to your Android project

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

  1. In Android Studio, choose "Import Module". As of this writing this is in a submenu under "File->New".
  2. Choose the path for the module called "bgxpress". The module is located under the "BGXCommander" folder. This will copy the module into your project.
  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.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" />

Set up Bluetooth in your main activity

In the onCreate method of the main activity of your app, you will need to perform the following operations:

  1. Verify the system supports Bluetooth Low Energy: getPackageManager().hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE)
  2. Request permission to access device location (this is required in order to use BLE): requestPermissions(new String[]{Manifest.permission.ACCESS_COARSE_LOCATION}, PERMISSION_REQUEST_COARSE_LOCATION);
  3. Start the BGXpressService: startService(new Intent(this, BGXpressService.class));

You should register a BroadcastReceiver to receive broadcast intents for the following: BGXpressService.BGX_SCAN_DEVICE_DISCOVERED , BGXpressService.BGX_CONNECTION_STATUS_CHANGE , and BGXpressService.BGX_SCAN_MODE_CHANGE .

Do not scan for devices until onRequestPermissionsResult is called by the operating system to grant permission to access the device location.

In your onResume() method if you have been granted permission to access the device location and BluetoothAdapter.getDefaultAdapter() is not null, check to see if the default adapter is enabled by calling BluetoothAdapter.getDefaultAdapter().isEnabled() . If it is not enabled then create an Intent for BluetoothAdapter.ACTION_REQUEST_ENABLE and start an activity wth this Intent.

Device Discovery

When three conditions have been met: you determine the system supports Bluetooth Low Energy, onRequestPermissionsResult was called indicating you were granted permission to use the device location, and the default Bluetooth adapter is enabled, then you can scan for BGX devices by calling: 

BGXpressService.startActionStartScan(Context)

You will receive broadcast intents in your broadcast receiver with the action BGXpressService.BGX_SCAN_DEVICE_DISCOVERED as devices are discovered. This intent will contain an Extra which is a HashMap<String, String> containing the keys name , uuid , and rssi . The name key is the device name, the uuid key is the device uuid which you will use to connect to the device, and rssi contains the signal strength of the device.

Connecting to a BGX

To connect to a device, call BGXpressService.startActionBGXConnect(context, deviceUUID) where deviceUUID is the uuid you were given in the HashMap for the device. The app will receive broadcast intents of type BGXpressService.BGX_CONNECTION_STATUS_CHANGE as the connection occurs.

When the bgx-connection-status extra inside the BGXpressService.BGX_CONNECTION_STATUS_CHANGE Intent is CONNECTED , the device is connected.

Detecting device Changes

You should register to receive broadcast intents for the following actions:

Action Purpose Extras
BGXpressService.BGX_MODE_STATE_CHANGE Indicates BusMode has been read or has changed busmode
BGXpressService.BGX_DATA_RECEIVED Indicates data has been received data
BGXpressService.BGX_DEVICE_INFO Contains information about the BGX which is needed for DMS/OTA bgx-device-uuid, bgx-part-id

Read/Write Serial data

When data is received from a connected BGX, the BGXpressService will send a broadcast intent of type BGXpressService.BGX_DATA_RECEIVED containing the data. To write data to the connected BGX, send a BGXpressService.ACTION_WRITE_SERIAL_DATA Intent like this: 

Intent writeIntent = new Intent(BGXpressService.ACTION_WRITE_SERIAL_DATA);
writeIntent.putExtra("value", text2send);
writeIntent.setClass(mContext, BGXpressService.class);
startService(writeIntent);

Bus Mode

To change the BusMode, use the following method to send an Intent to BGXpressService: 

Intent intent = new Intent(BGXpressService.ACTION_WRITE_BUS_MODE);
intent.setClass(this, BGXpressService.class);
intent.putExtra("busmode", busMode);
startService(intent);

Changes to the BusMode will be indicated by receiving a broadcast intent with the action BGXpressService.BGX_MODE_STATE_CHANGE containing the extra busmode .

Disconnecting from a BGX

To disconnect from the connected BGX: 

Intent intent = new Intent(BGXpressService.ACTION_BGX_DISCONNECT);
intent.setClass(mContext, BGXpressService.class);
startService(intent);

When the BGX is disconnected, you will receive a broadcast Intent with the action BGXpressService.BGX_CONNECTION_STATUS_CHANGE where the bgx-connection-status will have the value DISCONNECTED.

Firmware Update

Updating the firmware on a BGX device involves the following steps:

  1. Select the BGX you wish to update.
  2. Get a list of available firmware for the device.
  3. Retrieve the image of the firmware to be installed.
  4. Install it on the BGX.

Get available firmware using DMS

To request the list of available firmware, send the following Intent: 

Intent intent = new Intent(BGXpressService.ACTION_DMS_GET_VERSIONS);
intent.setClass(this, BGXpressService.class);
intent.putExtra("bgx-part-id", mBGXPartID);
startService(intent);

When the list has been retrieved you will receive a broadcast intent with the action BGXpressService.DMS_VERSIONS_AVAILABLE which contains the list in the form of JSON under the extra versions-available-json . The JSON will parse into an array containing firmware version records with the following keys:

key type
version string
tag string (may be empty)
size int (number of bytes)

Get firmware image using DMS

To request a specific version of firmware be loaded, the following Intent should be sent:

Intent intent = new Intent(BGXpressService.ACTION_DMS_REQUEST_VERSION); 

intent.putExtra("bgx-part-id", bgx_part_id); // This is the part ID that was provided in the BGXpressService.BGX_DEVICE_INFO intent as the extra *bgx-partd-id*
intent.putExtra("dms-version", dms_version); // This is the DMS version provided in the *version* field of the JSON record.

intent.setClass(mContext, BGXpressService.class);

When the firmware image is loaded onto your mobile device, you will receive a broadcast intent with the action BGXpressService.DMS_VERSION_LOADED containing an extra called file_path .

Updating a BGX using a firmware image

To install a firmware image onto the connected BGX, send the following Intent: 

Intent updateIntent = new Intent(mContext, BGXpressService.class);
updateIntent.setAction(ACTION_OTA_WITH_IMAGE);
updateIntent.putExtra("image_path", firmwareImageFilePath);
startService(updateIntent);

As the update installs, you will receive a series of broadcast intents with the action BGXpressService.OTA_STATUS_MESSAGE with the following Extras:

Extra Type Default Value Meaning
ota_failed boolean false If this value is true, it means that the OTA failed.
ota_status OTA_STATUS n/a This is an enum indicating the status of the OTA. The values are described in the table below.
bytes_sent int -1 Indicates the number of bytes that has been uploaded to the BGX device. This is only present when the OTA status is Installing.
Canceling an OTA Update

To cancel an OTA Update in progress, send the following Intent: 

Intent intent = new Intent();
intent.setAction(BGXpressService.ACTION_OTA_CANCEL);
intent.setClass(mContext, BGXpressService.class);
startService(intent);
OTA_Status Values
OTA_Status Value Meaning
Invalid Should never see this. It indicates an error has occurred.
Idle No OTA is happening
Downloading The firmware image is being downloaded through DMS
Installing The firmware image is being sent to the BGX device
Finishing The firmware image has been written and the BGX is being commanded to load it
Finished The BGX has acknowledged the command to load the firmware. The BGX is rebooting
UserCanceled The intent ACTION_OTA_CACNCEL has been received and the OTA operation is being canceled