BlueNRG Mesh Android API guide for Mesh over Bluetooth … · Figure 2. Android project structure...

IntroductionThe Mesh over Bluetooth low energy (MoBLE) software is a stack of network protocols for Android®-based handheld andembedded devices (nodes) with Bluetooth low energy on-board. These nodes can be arranged in a Mesh network overBluetooth low energy to create distributed control systems for applications like smart home systems.

Figure 1. Mesh network over Bluetooth low energy

BlueNRG Mesh Android API guide for Mesh over Bluetooth low energy

UM2290

User manual

UM2290 - Rev 1 - February 2018For further information contact your local STMicroelectronics sales office.

www.st.com

1 Features of the BLE Mesh library

• Create a new network or load existing networks• Start network processing• Enumerate unprovisioned nodes• Add unprovisioned nodes to network• Send custom commands (Read/Write) to Mesh nodes• Send group commands• Save and restore network configurations• Configure nodes for additional requirements• Advise to start receiving callbacks• Unadvise to stop receiving callbacks• Stop network processing

UM2290Features of the BLE Mesh library

UM2290 - Rev 1 page 2/29

2 Include library in Android application project

Follow the procedure below to include the library in the Android application project. The project structure is astandard Android project in which you create a new project and include Bluetooth low energy Mesh library to startdeveloping Mesh applications.

Step 1. Create a new directory for the library under the directory where the Android project is locatedStep 2. Copy library (.aar) file in the new directoryStep 3. Add these lines in the build.gradle of the app module after the Android tag

repositories { flatDir { dirs '<path to the MobleLibrary-release.aar>' }}

Step 4. Add library dependency in the build.gradle of the app module in the first line of the dependency tag

compile(name:'MobileLibrary-release', ext:'aar')

Step 5. If present, remove any ndk paths in the local.properties file of the Android project.

UM2290Include library in Android application project

UM2290 - Rev 1 page 3/29

Android Studio sometimes appends an ndk path in the local.properties file while building the project;this causes the application to crash.

UM2290Include library in Android application project

UM2290 - Rev 1 page 4/29

3 BlueNRG Mesh library guidelines

3.1 Network operation

3.1.1 Initialization API - Mesh network operationsmobleNetwork.createNetwork(...) creates new mesh network• Address of Android smartphone is specified in parameters• Network and application keys are generated randomly and not provided via MoBLE API• Nodes provisioned to other (existing) mesh networks are not accessible in newly created mesh network• Only one mesh network can work with the MoBLE stack at a time

mobleNetwork.backupNetwork(...) saves mesh network configuration into stream• Mesh network may be backed up any time

mobleNetwork.restoreNetwork(...) restores mesh network from its configuration saved in stream• Configuration of one mesh network shall not be restored into several Android smartphones in one time

3.1.2 Allowable Mesh network operations after API initializationCreate / restore• UserApplication.onCreate()• MainActivity.onCreate()• Any onClick() callback executed manually

Backup• When mesh network configuration is changed

3.1.3 Allowable Mesh network operations after app creationNetwork is started• Messages are transmitted to Bluetooth mesh network• Messages are received from Bluetooth mesh network• Provisioned and unprovisioned nodes are detected in range of the Android device

Network is stopped• Messages are not transmitted to Bluetooth mesh network• Messages are not received from Bluetooth mesh network• Provisioned and unprovisioned nodes within range of Android device are not detected

When network is created or restored, its processing is stopped• Call mobleNetwork.start(...) to start network processing• Call mobleNetwork.stop(...) to stop network processing

3.1.4 Provisioning API - IntroductionClass mobleSettings is designed to provision unprovisioned devices within Android device range• Call mobleNetwork.getSettings() to obtain instance of mobleSettings class

mobleSettings.provision(...) starts provisioning process• Provisioning process is asynchronous• Application shall implement interface mobleSettings.capabilitiesListener to confirm that proper

Unprovisioned device is chosen for provisioning• Application may implement interface mobleSettings.provisionerStateChanged to track current step of

provisioning process

UM2290BlueNRG Mesh library guidelines

UM2290 - Rev 1 page 5/29

• Application may implement interface mobleSettings.onProvisionComplete to track completion of provisioningprocess: success or failure

mobleSettings.cancel() stops provisioning process• If interface mobleSettings.onProvisionComplete is implemented then it is called back with failure or success

status

3.1.5 Nodes Enumeration APIDevices enumeration takes time• MoBLE stack scans for incoming reports and provides collection of detected devices

Enumeration API• Start devices enumeration (class mobleNetwork)• Future<DeviceCollection> enumerateDevices()

– Collection of devices in range is provided as instance of DeviceCollection• Check if device with known bdaddr is in range (class DeviceCollection)

– Device getDevice(bdaddr)• Get subset of devices in range according filtering rules (class DeviceCollection)

– Collection<Device> getDevices(int filter, Collection<String> dataBase)◦ BLE_ALL - all Bluetooth LE devices in range◦ BLE_MESH_ALL - all Bluetooth mesh devices◦ BLE_MESH_CONFIGURED - provisioned Bluetooth mesh devices◦ BLE_MESH_UNCONFIGURED - unprovisioned Bluetooth mesh devices◦ BLE_MESH_UNKNOWN - provisioned Bluetooth mesh devices with bdaddr not present in

collection provided in argument dataBase◦ BLE_NO_MESH - Bluetooth LE devices but not Bluetooth mesh devices

3.2 Project Structure

3.2.1 Project foldersgradle (folder and related files) - Gradle automated build systemkeys - folder with release keys that is used to sign the release APKres - graphical and textual resources (images, layouts, menus, strings, etc.) of demo applicationsrc - folder with source code files written in Java language

3.2.2 Temporary compilation foldersbuild - folder with intermediate Java files and compiled demo application

UM2290Project Structure

UM2290 - Rev 1 page 6/29

Figure 2. Android project structure

3.3 Project compilation: Android StudioStep 1. Run Android StudioStep 2. Click starting menu item “Open an existing Android Studio project”Step 3. Select folder of project that need to be compiled:

– MobleControllerDemoStep 4. Open Gradle tasks viewStep 5. Clean temporary files

– Click Gradle tree item “Tasks → build → clean”Step 6. Compile (for MobleLibrary)

– Click Gradle tree item “Tasks → build → assembleRelease”Step 7. Compile (for MobleControllerDemo)

– Check that MobleLibrary is already compiled– Click Gradle tree item “Tasks → build → assembleRelease” for release compilation– Click Gradle tree item “Tasks → build → assembleDebug” for debug compilation

Step 8. Run (for MobleControllerDemo)– Connect Android-based device which will be used for demo application running– Click menu item “Run → Run ‘MobleControllerDemo’”– Accept application installation on Android-based device

3.4 Project Compilation: command lineStep 1. Open command prompt in the folder of project that need to be compiledStep 2. Clean temporary files

– Execute build script:– “gradlew.bat clean”

Step 3. Compile (for MobleLibrary)– Execute build script:– “gradlew.bat assembleRelease”

UM2290Project compilation: Android Studio

UM2290 - Rev 1 page 7/29

Step 4. Compile (for MobleControllerDemo)– Check whether the MobleLibrary is already present in the dir path– Execute build script:– “gradlew.bat assembleRelease” for release compilation– “gradlew.bat assembleDebug” for debug compilation

Step 5. Install application (for MobleControllerDemo)– Open folder with apk-file– Run adb:

◦ “adb.exe install MobleControllerDemo-release.apk” or◦ “adb.exe install MobleControllerDemo-debug.apk”

Step 6. If application is installed already and adb fails to update it then use key ‘-r’ with adb:“adb.exe install -r MobleControllerDemo-release.apk”

UM2290Project Compilation: command line

UM2290 - Rev 1 page 8/29

4 APIs

4.1 How to use APIsStep 1. Create a new mesh network to search for available BLE Mesh devices.

To create a new network, use createNetwork(). Once the network is created, its processing can bestarted or stopped with the start() and stop() APIs.

Step 2. Get the list of unprovisioned devices using enumerateDevices().To provision a target device, use provision() API. API provision can be invoked through an instance ofmobleSettings.

Step 3. Call provision method from the instance of mobleSettings.On completion of provisioning, onProvisionComplete callback is called where determination of devicetype(Sensor,Lighting,Temperature) is performed by DeviceDeterminationCallback. Finally, register thedevice to subscriptionListener.

Step 4. Once the targeted device is provisioned with the Android device, different APIs can be used to sendread and write commands.– For Lighting Device Node: For toggling light: call API setRemoteData() with an instance of

mobleNetwork.

– For reading device type: call API readRemoteData() with an instance of mobleNetwork.

RELATED LINKS 5.7 Toggle light for lighting device type on page 12

5.8 Read device type on page 13

6.1 Create network on page 16

6.2 Start network on page 16

6.3 Stop network on page 16

6.9 Enumerate devices on page 18

6.12 Provision on page 19

6.11 Get settings on page 19

6.13 Set remote data on page 20

6.14 Read remote data on page 20

UM2290APIs

UM2290 - Rev 1 page 9/29

5 Code snippets and examples

5.1 Create NetworkCreate a new network with createNetwork() API

mNetwork = mobleNetwork.createNetwork(address);

Note: The default value of the address is 1, which is the ID set for the Android device at the time of createNetwork.Pass this address to createNetwork to create a new mesh network:

mNetwork = mobleNetwork.createNetwork(androidAddress);

All subsequent nodes will be assigned a unicast device address starting from 2 as a mobleAddress object usingthe deviceAddress method.

RELATED LINKS 6.1 Create network on page 16

5.2 Start NetworkStart the MoBLE stack with start() API.

mobleStatus start() { mobleStatus res = mConfiguration.getNetwork().start(this); if (res.failed()) { return res; } mConfiguration.getNetwork().advise(mCallback); return mobleStatus.SUCCESS;}

RELATED LINKS 6.2 Start network on page 16

5.3 Stop NetworkStop the MoBLE stack with stop() API.

mobleStatus stop() { if (mConfiguration != null) { mConfiguration.getNetwork().unadvise(mCallback); return mConfiguration.getNetwork().stop(); } else { trace("Network does not exist"); return mobleStatus.FALSE; }}

UM2290Code snippets and examples

UM2290 - Rev 1 page 10/29

RELATED LINKS 6.3 Stop network on page 16

5.4 Advise(callback)Register a callback with advise() API

((UserApplication) getApplication()).mConfiguration.getNetwork().advise(mOnDeviceAppearedCallback);((UserApplication) getApplication()).mConfiguration.getNetwork().advise(mProxyConnectionEventCallback);((UserApplication) getApplication()).mConfiguration.getNetwork().advise(onDeviceRssiChangedCallback);((UserApplication) getApplication()).mConfiguration.getNetwork().advise(onNetworkStatusChanged);

RELATED LINKS 6.7 Advise on page 18

5.5 Unadvise(callback)For Deregistering a callbackDeregister a callback with unadvise() API

((UserApplication) activity.getApplication()).mConfiguration.getNetwork().unadvise(activity.mOnDeviceAppearedCallback);((UserApplication) activity.getApplication()).mConfiguration.getNetwork().unadvise(activity.onNetworkStatusChanged);

RELATED LINKS 6.8 Unadvise on page 18

5.6 ProvisioningThe duration of identify state of unprovisioned node.

Public static final int PROVISIONING_IDENTIFY_DURATION = 10;

Invoking of createNetwork() API with an instance of settings

mSettings = ((UserApplication)getApplication()).mConfiguration.getNetwork().getSettings();if (!checkConfiguration() || (null == mAutoAddress)) { mProgress.hide(); makeToast("Network does not exist. Please create network"); UserApplication.trace("Network does not exists");}else { mProvisioningInProgress = true; mSettings.provision(MainActivity.this, mAutoAddress, mAutoDevice.getAddress(), PROVISIONING_IDENTIFY_DURATION,

UM2290Advise(callback)

UM2290 - Rev 1 page 11/29

mProvisionCallback, mCapabilitiesLstnr, mProvisionerStateChanged,COMPLETION_DELAY);}

Callback will be called while provisioning is under process.

private final mobleSettings.onProvisionComplete mProvisionCallback = new mobleSettings.onProvisionComplete() { @Override public void onCompleted(byte status) { mProvisioningInProgress = false; if (status == mobleProvisioningStatus.SUCCESS) { provisioningStep++; mProvisionerStateChanged.onStateChanged(provisioningStep + 1, ""); ((UserApplication) getApplication()).mConfiguration.getNetwork().advise(mDeviceDeterminationCallback); mCookies = ((UserApplication) getApplication()).mConfiguration.getNetwork().getApplication().readRemoteData(mAutoDevice.getAddress(), Nucleo.APPLI_CMD_DEVICE_TYPE, 1, true); } else if (status == mobleProvisioningStatus.CANCEL) { } else { makeToast("Unable to configure " + mAutoAddress + ". Please check if device powered and try again"); UserApplication.trace("Unable to configure " + mAutoAddress); updateRequest(false); } }};

Callback will be called whenever new capabilities are found.

mobleSettings.capabilitiesListener mCapabilitiesLstnr = new mobleSettings.capabilitiesListener() { @Override public void onCapabilitiesReceived(mobleSettings.Identifier identifier) { mIdentifyDialog.createDialog(identifier); }};

Callback will be called whenever provisioner state changes

private final mobleSettings.provisionerStateChanged mProvisionerStateChanged = new mobleSettings.provisionerStateChanged() { @Override public void onStateChanged(final int state, final String label) { provisioningStep = state; runOnUiThread(new Runnable() { @Override public void run() { mProgress.setProgress(state + 1, "Provisioning: \n" + label); } }); }};

RELATED LINKS 6.12 Provision on page 19

5.7 Toggle light for lighting device typeSetting data on remote device by using setRemoteData() API

UM2290Toggle light for lighting device type

UM2290 - Rev 1 page 12/29

mobleNetwork network = ((UserApplication) activity.getApplication()).mConfiguration.getNetwork();network.getApplication().setRemoteData(address, Nucleo.APPLI_CMD_TOGGLE, 1, new byte[]{0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08},false);

RELATED LINKS 4.1 How to use APIs on page 9

6.13 Set remote data on page 20

5.8 Read device typeRead data from remote device with readRemoteData() API.

network.getApplication().readRemoteData(mAutoDevice.getAddress(), Nucleo. APPLI_CMD_DEVICE_TYPE, 1, true);

Note: Device Types are configured in the Device Firmware


6.14 Read remote data on page 20

5.9 Device RSSI changedThis is used to display the RSSI values of the Mesh nodes. The application signals RSSI change events.Advising to onDeviceRssiChanged() callback

((UserApplication) getApplication()).mConfiguration.getNetwork().advise(onDeviceRssiChangedCallback);

onDeviceRssiChanged() callback implementation

private final defaultAppCallback onDeviceRssiChangedCallback = new defaultAppCallback(){ @Override public void onDeviceRssiChanged(String bt_addr, int mRssi) { super.onDeviceRssiChanged(bt_addr, mRssi); Message msg = Message.obtain(); msg.obj = new Object[] {bt_addr, mRssi}; msg.what = MSG_UPDATE_RSSI; mHandler.sendMessage(msg); }};

Populating new RSSI values on GUI

void refreshRssi(String bt_addr, int mRssi){ if(mData != null) { for (Map map : mData){ if (map.get("address") != null) { if (map.get("address").equals(bt_addr)) { map.put("rssi", mRssi); } }

UM2290Read device type

UM2290 - Rev 1 page 13/29

} mRssiAdapter.notifyDataSetChanged(); }}

RELATED LINKS 7.4 onDeviceRSSIChanged on page 22

5.10 Network in Range APIThis API is used to detect whether the provisioner is in the range of provisioned or unprovisioned devices.The application shall advise the onNetworkStatusChanged event.Advising to onNetworkStatusChanged callback

((UserApplication) getApplication()).mConfiguration.getNetwork().advise(onNetworkStatusChanged);

onNetworkStatusChanged callback implementation

private final defaultAppCallback onNetworkStatusChanged = new defaultAppCallback(){ @Override public void inRange(boolean prevStatus, boolean newStatus) { super.inRange(prevStatus, newStatus); Message msg = Message.obtain(); msg.obj = new Object[] {prevStatus, newStatus}; msg.what = MSG_UPDATE_NETWORK_STATUS; mHandler.sendMessage(msg); }};

5.11 AutoConfigureBlueNRG Mesh Android API guide for Mesh over Bluetooth low energy - Code snippets and examples -Autoconfigure

boolean autoConfigure() { mSettings = ((UserApplication)getApplication()).mConfiguration.getNetwork().getSettings(); if (!checkConfiguration() || (null == mAutoAddress)) { mProgress.hide(); makeToast("Network does not exist. Please create network"); UserApplication.trace("Network does not exists"); } else { mProvisioningInProgress = true; mSettings.provision(MainActivity.this, mAutoAddress, mAutoDevice.getAddress(), PROVISIONING_IDENTIFY_DURATION, mProvisionCallback, mCapabilitiesLstnr, mProvisionerStateChanged,COMPLETION_DELAY); } return true;}

UM2290Network in Range API

UM2290 - Rev 1 page 14/29

5.12 TroubleshootingCreating/Loading configuration file• Creating a file requires WRITE_EXTERNAL_STORAGE permission in manifest. If you receive a security

exception during file writes, ensure the application has the necessary permissions.• To load or save the configuration file, the file streams require application context. Ensure that the application

is registered (the class extending Application class) in the manifest.

Exception: Unable to invoke virtual method• Usually occurs while invoking an API with a new application reference. Do not make a new reference. Use

getApplication() and type cast it to the child class.

Exception: Activity is not assignable to android.app.Activity• The class should extend the Application class. Application cannot make UI changes; it requires an Activity.• The child class should be registered by extending Application class in the manifest file.

Exception: Thread not able to update UI• This exception occurs when a non UI thread tries to update the UI component of the activity. Use the handler

to manage UI updates.

Exception: Security: coarse or fine location permission required.• Permission for location is only required for Android 6 (SDK version 23) and above. To solve this issue, set

the application targetSdkVersion to 22 or below (21 is recommended) in the build.gradle app module.

Exception: Illegal argument• The app may sometimes crash due to an old configuration of a device which need to be deleted. Go to

Settings → Application → Select the app → Clear Cache & Data → uninstall, then reinstall the app.

UM2290Troubleshooting

UM2290 - Rev 1 page 15/29

6 BLE Mesh Android APIs

6.1 Create network

public static mobleNetwork createNetwork (mobleAddress address)

Creates a new network with given address.Returns• mobleNetwork → Reference to the object.

Parameters• address → mobleAddress: local address of device. (For smartphone it is = 1, for nodes it is 2, 3, 4…)

Prerequisites• configuration → Configuration: an instance of configuration must be initialized.


5.1 Create Network on page 10

6.2 Start network

mobleStatus start (Context context)

Starts network or functioning of BlueNRG Mesh Stack.Returns• mobleStatus → Reference to the object.

Parameters• Context → Context of application.

Prerequisites• Configuration → Configuration: an instance of configuration must be initialized.• mobleNetwork → mobleNetwork: an instance of network must be created.


5.2 Start Network on page 10

6.3 Stop network

mobleStatus stop()

Stops notifying user application callbacks with MoBLE stack events.Returns• mobleStatus → Reference to the object.


UM2290BLE Mesh Android APIs

UM2290 - Rev 1 page 16/29


5.3 Stop Network on page 10

6.4 Backup network

public mobleStatus backupNetwork(OutputStream ostm)

Construct a new mobleAddress object for device address.Returns• mobleStatus → Status of operation.

Parameters• Ostm → OutputStream: output stream to write configuration to.


RELATED LINKS 8.2 Network backup on page 24

6.5 Restore network

Public static mobleNetwork restoreNetwork(InputStream istm)

Loads configuration from input stream in which it was saved previously.Returns• mobleNetwork → Reference to the object.

Parameters• istm → IntputStream: input stream to load configuration from.


Exception• throws → IOException

RELATED LINKS 8.3 Network restore on page 24

6.6 Device address

public static mobleAddress deviceAddress(int address)

Construct a new mobleAddress object for device address.Returns• mobleAddress → Created Object.

Parameters

UM2290Backup network

UM2290 - Rev 1 page 17/29

• address → int: device network address.

Prerequisites• configuration → Configuration: an instance of configuration must be initialized.

6.7 Advise

void advise (Callback callback)

Starts notifying user application callbacks with BlueNRG Mesh stack events.Returns• Void → Void

Parameters• Callback → Callbacks


RELATED LINKS 5.4 Advise(callback) on page 11

6.8 Unadvise

void unadvise (Callback callback)

Stops notifying user application callbacks with MoBLE stack events.Returns• Void → Void

Parameters• callback → Callbacks

Prerequisites• configuration → Configuration: an instance of configuration must be initialized.• mobleNetwork → mobleNetwork: an instance of network must be created.

RELATED LINKS 5.5 Unadvise(callback) on page 11

6.9 Enumerate devices

Future<DeviceCollection> enumerateDevices()

Initiates devices enumeration. Enumeration may require some time therefore result is provided as object.Returns• Future<DeviceCollection>Returns object with collection of enumerated devices.


UM2290Advise

UM2290 - Rev 1 page 18/29


6.10 Get devices

Collection<Devices> getDevices(int filter, Collection<String> database)

Returns• Collection → Returns collection of devices.

Parameters• Filterint → bit mask from flags.• database → Collection<String> database of mac addresses of BLE devices.


6.11 Get settings

mobleSettings getSettings()

Get settings object for device provisioning.Returns• mobleSettings → Returns reference to the object.



6.12 Provision

boolean provision (Context context, String address, final mobleAddress, int identifyDuration, onProvisionComplete statusListener, final capabilitiesListener cListener, final provisionerStateChanged psc,int completionDelay)

Provision target device. Callback methods will be called after configuration is written.Returns• boolean → Returns true, if provisioning has started. False otherwise.

Parameters• context → Context: object of AppComponentInterface.• address → String: MAC address of targer device.• moble → mobleAddress: assigned MoBLE address.• identify → identifyDuration: The duration of identify state of unprovisioned node.• status → statusListener: provisioning status listener.• capabilities → capabilitiesLstnr: capabilities listener.• Pcs → provisionerStateChanged: provisioning states changing listener.

UM2290Get devices

UM2290 - Rev 1 page 19/29

Prerequisites• configuration → Configuration: an instance of configuration must be initialized.• mobleNetwork → mobleNetwork: an instance of network must be initialized.• mobleSettings → mobleSettings: an instance of mobleSettings must be initialized.

Note: All the parameters must be initialized before invoking the API. No parameter should be null.


5.6 Provisioning on page 11

6.13 Set remote data

Object setRemoteData(mobleAdress peer, int address, int count, byte[] data, boolean with_response)

Sets remote data to the given destination address. User is responsible for serializing data into buffer. Callback iscalled on remote device.Returns• Object → Returns command identifier if with_response is true.

Parameters• Peer → mobleAddress: destination address. May be set to broadcast data.• address → int: starting address of data range in address space.• count → int: number of data elements starting from address to be sent.• DataByte[]: data buffer• with_response → boolean: true if response is requested to the command, false otherwise.

Prerequisites• configuration → Configuration: an instance of configuration must be initialized.• mobleNetwork → mobleNetwork: an instance of network must be initialized.

Note: All the parameters must be initialized before invoking the API. No parameter should be null.Callback• VoidOnWriteLocalData (…)


5.7 Toggle light for lighting device type on page 12

6.14 Read remote data

Object readRemoteData(mobleAdress peer, int address, int count, boolean with_response)

Requests remote data from the given destination address.Returns• Object → Returns command identifier if with_response is true.

Parameters• Peer → mobleAddress: destination address. May be set to broadcast data.• Address → int: starting address of data range in address space.

UM2290Set remote data

UM2290 - Rev 1 page 20/29

• Count → int: number of data elements starting from address to be sent.• with_response → boolean: true if response is requested to the command, false otherwise.

Prerequisites• Configuration → Configuration: an instance of configuration must be initialized.• mobleNetwork → mobleNetwork: an instance of network must be initialized.

Note: All the parameters must be initialized before invoking the API. No parameter should be null.Callback• voidOnReadLocalData (…)


5.8 Read device type on page 13

UM2290Read remote data

UM2290 - Rev 1 page 21/29

7 Callbacks

7.1 onResponse

void onResponse(mobleAddress peer, Object cookies, byte status, byte[] data)

Returns• void → void

Parameters• peer → mobleAddress: address of device which has sent the command.• cookies → Object: identifier of the command which was sent in the past and response to which is received.• status → byte: status of the command.• data → Byte[]: data buffer appended to the response.

Command Status• 0 → STATUS_SUCCESS, command is succeeded.• 1 → STATUS_FAIL_COMMAND, command failed because it contains illegal opcode.• 2 → STATUS_FAIL_ADDRESS, command failed because it contains illegal address.• 3 → STATUS_FAIL_VALUE, command failed because it contains illegal data value.• 4 → STATUS_FAIL_DEVICE, command is failed because destination device has failed its processing.• 5 → STATUS_FAIL_TIMEOUT, command failed because response on the command was not received. This

status code never returned. It is added to the list because it is generated by application if response is notreceived.

• 6 → STATUS_GATT_SENT, command is sent to GATT bridge. This status code is returned when commandwith requested response is passed to GATT bridge. It is expected that application can start waiting after thatmoment.

7.2 onProxyConnectionEvent

void onProxyConnectionEvent (boolean process. String proxyAddress)

Called if trying to connect proxy. Do not perform any transaction when proxy connection procedure is in progress.Returns• void → Void

Parameters• process → boolean: true if connection in process, false if connection procedure is not active.• proxy → AddressString: address of proxy.

7.3 onDeviceAppeared

void onDeviceAppeared (String bt_addr)

Called if detected unconfigured MOBLE device.Returns• Void → void

Parameters• Bt_addr → String: Bluetooth address.

UM2290Callbacks

UM2290 - Rev 1 page 22/29

7.4 onDeviceRSSIChanged

void onDeviceRssiChanged (String bt_addr, int mRssi)

Called if device’s RSSI value changed.Returns• void → void

Parameters• Bt_addr → String: Bluetooth address.• mRssi → int: RSSI value.

RELATED LINKS 5.9 Device RSSI changed on page 13

7.5 inRange

void inRange (boolean prevStatus, boolean newStatus)

Called if smart phone is in the range of Mesh network or not. Section 5.10 Network in Range APIReturns• void → Void

Parameters• prevStatus → boolean: previous status of the network.• newStatus → boolean: new status of the network.

UM2290onDeviceRSSIChanged

UM2290 - Rev 1 page 23/29

8 Device configuration

Devices are divided into four types:• 0x0000ffff → Unknown device type. This is the device type of an unprovisioned node.• 0 → Bulb• 1 → Accelerometer• 2 → Thermometer

A device must have the following data:• String: name (Device name) e.g., Device 01, Device 02,etc• mobleAddress: address (Device address) e.g., 0002,0003,etc.• int: deviceType (Device type) 0(light)

All this data are members of the DeviceEntry class.The configuration file contains this data in a map (key and value pair), where the key is mac address of the device(string format) and value is an instance of DeviceEntry.

8.1 Configuration fileThe configuration file is used to restore a previously created network.If, for example, you close the App after provisioning a BLE device and did not unprovision the device, then theconfiguration file of that network with the BLE devices can be restored whenever the App is reopened. Thisconfiguration file can be even shared over cloud or manually to a new Provisioner(Smart Phone) to load theexisting network.

8.2 Network backupTo make a backup of an already established network, backupNetwork() API can be used.

RELATED LINKS 6.4 Backup network on page 17

8.3 Network restoreTo restore a network which was established previously, restoreNetwork() API can be used.

RELATED LINKS 6.5 Restore network on page 17

UM2290Device configuration

UM2290 - Rev 1 page 24/29

A Licensing and other information• Developer-friendly license terms• Initial BlueNRG-Mesh is built over Motorola’s Mesh Over Bluetooth Low Energy (MoBLE) technology. The

present solution is developed and maintained for both Mesh library and Applications solely bySTMicroelectronics.

UM2290Licensing and other information

UM2290 - Rev 1 page 25/29

Revision history

Table 1. Document revision history

Date Version Changes

01-Feb-2018 1 Initial release.

UM2290

UM2290 - Rev 1 page 26/29

Contents

1 Features of the BLE Mesh library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2

2 Include library in Android application project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

3 BlueNRG Mesh library guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

3.1 Network operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.1.1 Initialization API - Mesh network operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.1.2 Allowable Mesh network operations after API initialization . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.1.3 Allowable Mesh network operations after app creation. . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.1.4 Provisioning API - Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3.1.5 Nodes Enumeration API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.2 Project Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.2.1 Project folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.2.2 Temporary compilation folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.3 Project compilation: Android Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3.4 Project Compilation: command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

4 APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

4.1 How to use APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

5 Code snippets and examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

5.1 Create Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

5.2 Start Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

5.3 Stop Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

5.4 Advise(callback) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

5.5 Unadvise(callback). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

5.6 Provisioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

5.7 Toggle light for lighting device type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

5.8 Read device type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

5.9 Device RSSI changed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

5.10 Network in Range API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5.11 AutoConfigure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5.12 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

UM2290Contents

UM2290 - Rev 1 page 27/29

6 BLE Mesh Android APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

6.1 Create network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6.2 Start network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6.3 Stop network. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6.4 Backup network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6.5 Restore network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6.6 Device address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6.7 Advise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6.8 Unadvise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6.9 Enumerate devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6.10 Get devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6.11 Get settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6.12 Provision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6.13 Set remote data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6.14 Read remote data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

7 Callbacks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22

7.1 onResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

7.2 onProxyConnectionEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

7.3 onDeviceAppeared . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

7.4 onDeviceRSSIChanged . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

7.5 inRange. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

8 Device configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

8.1 Configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

8.2 Network backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

8.3 Network restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

A Licensing and other information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26

UM2290Contents

UM2290 - Rev 1 page 28/29

IMPORTANT NOTICE – PLEASE READ CAREFULLY

STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to STproducts and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. STproducts are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgement.

Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design ofPurchasers’ products.

No license, express or implied, to any intellectual property right is granted by ST herein.

Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.

ST and the ST logo are trademarks of ST. All other product or service names are the property of their respective owners.

Information in this document supersedes and replaces information previously supplied in any prior versions of this document.

© 2018 STMicroelectronics – All rights reserved

UM2290

UM2290 - Rev 1 page 29/29

BlueNRG Mesh Android API guide for Mesh over Bluetooth … · Figure 2. Android project structure...

Documents

Transcript of BlueNRG Mesh Android API guide for Mesh over Bluetooth … · Figure 2. Android project structure...