BGXpress Service Usage

Using BGXpressService

Adding BGXpressService to your Android project

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

1. Add the files BGXpressService.java and BusMode.java into your Android app.
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" />
   

Setup Bluetooth in your main activty

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 acccess 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.

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 iamge 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