FeasyMesh SDK For Android
SDK Resource Kit Download
SDK Access Documents
Description
FeasyMesh SDK is a leading software development tool that focuses on building powerful Mesh network applications. Its advanced feature set and easy-to-use interface enable developers to easily implement complex Mesh communication systems. Whether you are a beginner or an experienced developer, the Mesh SDK provides you with a flexible and efficient framework to help you achieve outstanding achievements in the Mesh networking field.
Permission
<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.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<!-- Bluetooth related permissions -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
To start using libraries in your own project, please refer to the following code snippet.
MeshManagerApi mMeshManagerApi = new MeshManagerApi(context);
mMeshManagerApi.setMeshManagerCallbacks(this);
mMeshManagerApi.setProvisioningStatusCallbacks(this);
mMeshManagerApi.setMeshStatusCallbacks(this);
mMeshManagerApi.loadMeshNetwork();
Follow the following code when sending and receiving data.
@Override
public void onDataReceived(final BluetoothDevice bluetoothDevice, final int mtu, final byte[] pdu) {
mMeshManagerApi.handleNotifications(mtu, pdu);
}
@Override
public void onDataSent(final BluetoothDevice device, final int mtu, final byte[] pdu) {
mMeshManagerApi.handleWriteCallbacks(mtu, pdu);
}
Node distribution network
Pre allocating nodes to the network can be completed in three steps,
1. Invoking Identify the nodes to be pre configured, where the devices will flash, vibrate, or emit beeps, depending on the predefined duration of 5 seconds of functionality. This is useful when pre configuring multiple nodes. Identify node calls
void identifyNode(@NonNull final UUID deviceUUID) throws IllegalArgumentException;
By passing the device uuid without pre configured grid nodes. or
void identifyNode(@NonNull final UUID deviceUUID, final int attentionTimer) throws IllegalArgumentException;
By passing the device uuid and required duration without pre configured grid nodes. 3. Based on the identified device functions, call one of the following functions to pre configure the node.
void startProvisioning(@NonNull final UnprovisionedMeshNode unprovisionedMeshNode) throws IllegalArgumentException;
Or
void startProvisioningWithStaticOOB(@NonNull final UnprovisionedMeshNode unprovisionedMeshNode) throws IllegalArgumentException;
Or
void startProvisioningWithOutputOOB(@NonNull final UnprovisionedMeshNode unprovisionedMeshNode, final OutputOOBAction oobAction) throws IllegalArgumentException;
Or
void startProvisioningWithInputOOB(@NonNull final UnprovisionedMeshNode unprovisionedMeshNode, @NonNull final InputOOBAction oobAction) throws IllegalArgumentException;
Use objects to edit grid network properties, such as network name, pre allocator and its properties (name address, TTL, and address range), network key, and application key. MeshNetowrk
The following is an example of how to send a generic OnOffSet message.
final GenericOnOffSet genericOnOffSet = new GenericOnOffSet(appKey, state,
new Random().nextInt(), transitionSteps, transitionStepResolution, delay);
mMeshManagerAPi.createMeshPdu(address, genericOnOffSet);
Configuration messages can also be sent the same way.
SDK API
Callbacks
MeshMngrApi
/**
* Sets the {@link MeshManagerCallbacks} listener
*
* @param callbacks callbacks
* @param callback
*/
void setMeshManagerCallbacks(@NonNull final MeshManagerCallbacks callbacks);
/**
* Sets the {@link MeshProvisioningStatusCallbacks} listener to return provisioning status callbacks.
*
* @param callbacks callbacks
* @param callback
*/
void setProvisioningStatusCallbacks(@NonNull final MeshProvisioningStatusCallbacks callbacks);
/**
* Sets the {@link MeshManagerCallbacks} listener to return mesh status callbacks.
*
* @param callbacks callbacks
* @param callback
*/
void setMeshStatusCallbacks(@NonNull final MeshStatusCallbacks callbacks);
/**
* Handles notifications received by the client.
* <p>
* This method will check if the library should wait for more data in case of a gatt layer segmentation.
* If its required the method will remove the segmentation bytes and reassemble the pdu together.
* </p>
*
* @param mtuSize GATT MTU size
* @param data PDU received by the client
*/
void handleNotifications(final int mtuSize, @NonNull final byte[] data);
/**
* Must be called to handle provisioning states
*
* @param mtuSize GATT MTU size
* @param data PDU received by the client
*/
void handleWriteCallbacks(final int mtuSize, @NonNull final byte[] data);
/**
* Identifies the node that is to be provisioned.
* <p>
* This method will send a provisioning invite to the connected peripheral. This will help users to identify a particular node before starting the provisioning process.
* This method must be invoked before calling {@link #startProvisioning(UnprovisionedMeshNode)}
* </p
*
* @param deviceUUID Device uuid of the unprovisioned mesh node. This could be obtain by calling {{@link #getMeshBeacon(byte[])}}
*/
void identifyNode(@NonNull final UUID deviceUUID) throws IllegalArgumentException;
/**
* Identifies the node that is to be provisioned.
* <p>
* This method will send a provisioning invite to the connected peripheral. This will help users to identify a particular node before starting the provisioning process.
* This method must be invoked before calling {@link #startProvisioning(UnprovisionedMeshNode)}
* </p
*
* @param deviceUUID Device uuid of the unprovisioned mesh node. This could be obtain by calling {{@link #getMeshBeacon(byte[])}}
* @param attentionTimer Attention timer in seconds
*/
void identifyNode(@NonNull final UUID deviceUUID, final int attentionTimer) throws IllegalArgumentException;
/**
* Starts provisioning an unprovisioned mesh node
* <p>
* This method will continue the provisioning process that was started by invoking {@link #identifyNode(UUID, int)}.
* </p>
*
* @param unprovisionedMeshNode {@link UnprovisionedMeshNode} node
*/
void startProvisioning(@NonNull final UnprovisionedMeshNode unprovisionedMeshNode) throws IllegalArgumentException;
/**
* Starts provisioning an unprovisioned mesh node with static oob
* <p>
* This method will continue the provisioning process that was started by invoking {@link #identifyNode(UUID, int)}.
* </p>
*
* @param unprovisionedMeshNode {@link UnprovisionedMeshNode} node
*/
void startProvisioningWithStaticOOB(@NonNull final UnprovisionedMeshNode unprovisionedMeshNode) throws IllegalArgumentException;
/**
* Starts provisioning an unprovisioned mesh node output oob
* <p>
* This method will continue the provisioning process that was started by invoking {@link #identifyNode(UUID, int)}.
* </p>
*
* @param unprovisionedMeshNode {@link UnprovisionedMeshNode} node
* @param oobAction selected {@link OutputOOBAction}
*/
void startProvisioningWithOutputOOB(@NonNull final UnprovisionedMeshNode unprovisionedMeshNode, final OutputOOBAction oobAction) throws IllegalArgumentException;
/**
* Starts provisioning an unprovisioned mesh node input OOB
* <p>
* This method will continue the provisioning process that was started by invoking {@link #identifyNode(UUID, int)}.
* </p>
*
* @param unprovisionedMeshNode {@link UnprovisionedMeshNode} node
* @param oobAction selected {@link InputOOBAction}
*/
void startProvisioningWithInputOOB(@NonNull final UnprovisionedMeshNode unprovisionedMeshNode, @NonNull final InputOOBAction oobAction) throws IllegalArgumentException;
/**
* Set the provisioning confirmation
*
* @param authentication confirmation pin
*/
void setProvisioningAuthentication(@NonNull final String authentication);
/**
* Returns the device uuid of an unprovisioned node
*
* @param serviceData service data in the adv packet
*/
@NonNull
UUID getDeviceUuid(@NonNull final byte[] serviceData) throws IllegalArgumentException;
/**
* Checks if the advertisement packet is a mesh beacon packet
*
* @param advertisementData data advertised by the mesh beacon
* @return true if its a mesh beacon packet or false otherwise
*/
boolean isMeshBeacon(@NonNull final byte[] advertisementData) throws IllegalArgumentException;
/**
* Returns the beacon information advertised by a mesh beaco packet
*
* @param advertisementData data advertised by the mesh beacon
* @return the data advertised by a beacon packet or null otherwise
*/
@Nullable
byte[] getMeshBeaconData(final byte[] advertisementData) throws IllegalArgumentException;
/**
* Returns a {@link UnprovisionedBeacon}, {@link SecureNetworkBeacon} based on the advertised service data
*
* @param beaconData beacon data advertised by the mesh beacon
*/
@Nullable
MeshBeacon getMeshBeacon(final byte[] beaconData);
/**
* Generate network id
*
* @return network id
*/
String generateNetworkId(@NonNull final byte[] networkKey);
/**
* Checks if the node identity matches
*
* @param meshNode mesh node to match with
* @param serviceData advertised service data
* @return true if the hashes match or false otherwise
*/
boolean nodeIdentityMatches(@NonNull final ProvisionedMeshNode meshNode, @NonNull final byte[] serviceData);
/**
* Checks if the node is advertising with Node Identity
*
* @param serviceData advertised service data
* @return returns true if the node is advertising with Node Identity or false otherwise
*/
boolean isAdvertisedWithNodeIdentity(@NonNull final byte[] serviceData);
/**
* Checks if the network ids match
*
* @param networkId network id of the mesh
* @param serviceData advertised service data
* @return returns true if the network ids match or false otherwise
*/
boolean networkIdMatches(@NonNull final String networkId, @NonNull final byte[] serviceData);
/**
* Returns the advertised hash
*
* @param serviceData advertised service data
* @return returns the advertised hash
*/
boolean isAdvertisingWithNetworkIdentity(@NonNull final byte[] serviceData);
/**
* Sends the specified mesh message specified within the {@link MeshMessage} object
*
* @param dst destination address
* @param meshMessage {@link MeshMessage} Mesh message containing the message opcode and message parameters
*/
void createMeshPdu(final int dst, @NonNull final MeshMessage meshMessage) throws IllegalArgumentException;
/**
* Loads the mesh network from the local database.
* <p>
* This will start an AsyncTask that will load the network from the database.
* {@link MeshManagerCallbacks#onNetworkLoaded(MeshNetwork) will return the mesh network
* </p>
*/
void loadMeshNetwork();
/**
* Returns an already loaded mesh network, make sure to call {@link #loadMeshNetwork()} before calling this
*
* @return {@link MeshNetwork}
*/
@Nullable
MeshNetwork getMeshNetwork();
/**
* Exports mesh network to a json String
*/
@Nullable
String exportMeshNetwork();
/**
* Starts an asynchronous task that imports a network from the mesh configuration db json
*
* @param uri path to the mesh configuration database json file.
*/
void importMeshNetwork(@NonNull final Uri uri);
/**
* Starts an asynchronous task that imports a network from the mesh configuration db json
*
* @param networkJson configuration database json.
*/
void importMeshNetworkJson(@NonNull final String networkJson);
/**
* Generates a random virtual address
*/
default UUID generateVirtualAddress() {
return UUID.randomUUID();
}
/**
* Start testing Sequence
*
* @param address destination address
*/
void testSequence(int address);
/**
* Stop testing Sequence
*/
void stopTestSequence();
/**
* Determine whether the Sequence is being tested
*/
boolean getTestSeq();
Mesh Provisioning Status Callbacks
/**
* Invoked when the provisioning state changed.
*
* @param meshNode {@link UnprovisionedMeshNode} unprovisioned node.
* @param state {@link ProvisioningState.State} each provisioning state.
* @param data data that was sent or received during each provisioning state.
*/
void onProvisioningStateChanged(final UnprovisionedMeshNode meshNode, final ProvisioningState.States state, final byte[] data);
/**
* Invoked when the provisioning state changed.
*
* @param meshNode {@link UnprovisionedMeshNode} unprovisioned node.
* @param state {@link ProvisioningState.State} each provisioning state.
* @param data data that was sent or received during each provisioning state.
*/
void onProvisioningFailed(final UnprovisionedMeshNode meshNode, final ProvisioningState.States state, final byte[] data);
/**
* Invoked when the provisioning state changed.
*
* @param meshNode {@link ProvisionedMeshNode} provisioned mesh node.
* @param state {@link ProvisioningState.State} each provisioning state.
* @param data data that was sent or received during each provisioning state.
*/
void onProvisioningCompleted(final ProvisionedMeshNode meshNode, final ProvisioningState.States state, final byte[] data);
Mesh Status Callbacks
/**
* Notifies if a transaction has failed
* <p>
* As of now this is only triggered if the incomplete timer has expired for a given segmented message.
* The incomplete timer will wait for a minimum of 10 seconds on receiving a segmented message.
* If all segments are not received during this period, that transaction shall be considered as failed.
* </p>
*
* @param dst Unique dst address of the device
* @param hasIncompleteTimerExpired Flag that notifies if the incomplete timer had expired
*/
void onTransactionFailed(final int dst, final boolean hasIncompleteTimerExpired);
/**
* Notifies if an unknown pdu was received
*
* @param src Address where the message originated from
* @param accessPayload Access payload of the message
*/
void onUnknownPduReceived(final int src, final byte[] accessPayload);
/**
* Notifies when a block acknowledgement has been processed
*
* <p>
* This callback is invoked after {@link MeshManagerCallbacks#onMeshPduCreated(byte[])} where a mesh pdu is created.
* </p>
*
* @param dst Destination address to which the block ack was sent
* @param message Control message containing the block acknowledgement
*/
void onBlockAcknowledgementProcessed(final int dst, @NonNull final ControlMessage message);
/**
* Notifies if a block acknowledgement was received
*
* @param src Source address from which the block ack was received
* @param message Control message containing the block acknowledgement
*/
void onBlockAcknowledgementReceived(final int src, @NonNull final ControlMessage message);
/**
* Callback to notify the mesh message has been processed to be sent to the bearer
*
* <p>
* This callback is invoked after {@link MeshManagerCallbacks#onMeshPduCreated(byte[])} where
* a mesh pdu is created and is ready to be sent.
* </p>
*
* @param dst Destination address to be sent
* @param meshMessage {@link MeshMessage} containing the message that was sent
*/
void onMeshMessageProcessed(final int dst, @NonNull final MeshMessage meshMessage);
/**
* Callback to notify that a mesh status message was received from the bearer
*
* @param src Source address where the message originated from
* @param meshMessage {@link MeshMessage} containing the message that was received
*/
void onMeshMessageReceived(final int src, @NonNull final MeshMessage meshMessage);
/**
* Callback to notify if the decryption failed of a received mesh message
*
* @param errorMessage Error message
*/
void onMessageDecryptionFailed(final String meshLayer, final String errorMessage);
Mesh Manager allbacks
/**
* Returns the network that was loaded
*
* @param meshNetwork{@link MeshNetwork that was loaded}
*/
void onNetworkLoaded(final MeshNetwork meshNetwork);
/**
* Returns the network that was updated
* <p>
* This callback is invoked for every message that was sent or received as it changes the contents of the network
* </p>
*
* @param meshNetwork{@link MeshNetwork that was loaded}
*/
void onNetworkUpdated(final MeshNetwork meshNetwork);
/**
* Callback that notifies in case the mesh network was unable to load
*
* @param error error
*/
void onNetworkLoadFailed(final String error);
/**
* Callbacks notifying the network was imported
*
* @param meshNetwork{@link MeshNetwork that was loaded}
*/
void onNetworkImported(final MeshNetwork meshNetwork);
/**
* Callback that notifies in case the mesh network was unable to imported
*
* @param error error
*/
void onNetworkImportFailed(final String error);
/**
* Send mesh pdu
*
* @param meshNode {@link UnprovisionedMeshNode}
* @param pdu mesh pdu to be sent
*/
void sendProvisioningPdu(final UnprovisionedMeshNode meshNode, final byte[] pdu);
/**
* Send mesh pdu
*
* @param pdu mesh pdu to be sent
*/
void onMeshPduCreated(final byte[] pdu);
/**
* Get mtu size supported by the peripheral node
* <p>
* This is used to get the supported mtu size from the ble module, so that the messages
* that are larger than the supported mtu size could be segmented
* </p>
*
* @return mtu size
*/
int getMtu();
Ble Manager Callbacks
/**
* Called when the Android device started connecting to given device.
* The {@link #onDeviceConnected(BluetoothDevice)} will be called when the device is connected,
* or {@link #onError(BluetoothDevice, String, int)} in case of error.
*
* @param device the device that got connected.
*/
void onDeviceConnecting(@NonNull final BluetoothDevice device);
/**
* Called when the device has been connected. This does not mean that the application may start
* communication.
* A service discovery will be handled automatically after this call. Service discovery
* may ends up with calling {@link #onServicesDiscovered(BluetoothDevice, boolean)} or
* {@link #onDeviceNotSupported(BluetoothDevice)} if required services have not been found.
*
* @param device the device that got connected.
*/
void onDeviceConnected(@NonNull final BluetoothDevice device);
/**
* Called when user initialized disconnection.
*
* @param device the device that gets disconnecting.
*/
void onDeviceDisconnecting(@NonNull final BluetoothDevice device);
/**
* Called when the device has disconnected (when the callback returned
* {@link BluetoothGattCallback#onConnectionStateChange(BluetoothGatt, int, int)} with state
* DISCONNECTED), but ONLY if the {@link BleManager#shouldAutoConnect()} method returned false
* for this device when it was connecting.
* Otherwise the {@link #onLinkLossOccurred(BluetoothDevice)} method will be called instead.
*
* @param device the device that got disconnected.
*/
void onDeviceDisconnected(@NonNull final BluetoothDevice device);
/**
* This callback is invoked when the Ble Manager lost connection to a device that has been
* connected with autoConnect option (see {@link BleManager#shouldAutoConnect()}.
* Otherwise a {@link #onDeviceDisconnected(BluetoothDevice)} method will be called on such
* event
*
* @param device the device that got disconnected due to a link loss.
*/
void onLinkLossOccurred(@NonNull final BluetoothDevice device);
/**
* Called when service discovery has finished and primary services has been found.
* This method is not called if the primary, mandatory services were not found during service
* discovery. For example in the Blood Pressure Monitor, a Blood Pressure service is a
* primary service and Intermediate Cuff Pressure service is a optional secondary service.
* Existence of battery service is not notified by this call.
* <p>
* After successful service discovery the service will initialize all services.
* The method will be called when the initialization
* is complete.
*
* @param device the device which services got disconnected.
* @param optionalServicesFound if <code>true</code> the secondary services were also found
* on the device.
*/
void onServicesDiscovered(@NonNull final BluetoothDevice device, final boolean optionalServicesFound);
/**
* Method called when all initialization requests has been completed.
*
* @param device the device that get ready.
*/
void onDeviceReady(@NonNull final BluetoothDevice device);
/**
* This method should return true if Battery Level notifications should be enabled on the
* target device. If there is no Battery Service, or the Battery Level characteristic does
* not have NOTIFY property, this method will not be called for this device.
* <p>
* This method may return true only if an activity is bound to the service (to display the
* information to the user), always (e.g. if critical battery level is reported using
* notifications) or never, if such information is not important or the manager wants to
* control Battery Level notifications on its own.
*
* @param device the target device.
* @return True to enabled battery level notifications after connecting to the device,
* false otherwise.
* @deprecated Use
* <pre>{@code
* setNotificationCallback(batteryLevelCharacteristic)
* .with(new BatteryLevelDataCallback() {
* onBatteryLevelChanged(int batteryLevel) {
* ...
* }
* });
* }</pre>
* in the {@link BleManager.BleManagerGattCallback#initialize() initialize(BluetoothDevice)}
* instead.
*/
@Deprecated
default boolean shouldEnableBatteryLevelNotifications(@NonNull final BluetoothDevice device) {
return false;
}
/**
* Called when battery value has been received from the device.
*
* @param device the device from which the battery value has changed.
* @param value the battery value in percent.
* @deprecated Use
* <pre>{@code
* setNotificationCallback(batteryLevelCharacteristic)
* .with(new BatteryLevelDataCallback() {
* onBatteryLevelChanged(int batteryLevel) {
* ...
* }
* });
* }</pre>
* in the {@link BleManager.BleManagerGattCallback#initialize() initialize(BluetoothDevice)}
* instead.
*/
@Deprecated
default void onBatteryValueReceived(@NonNull final BluetoothDevice device,
@IntRange(from = 0, to = 100) final int value) {
// do nothing
}
/**
* Called when an {@link BluetoothGatt#GATT_INSUFFICIENT_AUTHENTICATION} error occurred and the
* device bond state is {@link BluetoothDevice#BOND_NONE}.
*
* @param device the device that requires bonding.
*/
void onBondingRequired(@NonNull final BluetoothDevice device);
/**
* Called when the device has been successfully bonded.
*
* @param device the device that got bonded.
*/
void onBonded(@NonNull final BluetoothDevice device);
/**
* Called when the bond state has changed from {@link BluetoothDevice#BOND_BONDING} to
* {@link BluetoothDevice#BOND_NONE}.
*
* @param device the device that failed to bond.
*/
void onBondingFailed(@NonNull final BluetoothDevice device);
/**
* Called when a BLE error has occurred
*
* @param message the error message.
* @param errorCode the error code.
* @param device the device that caused an error.
*/
void onError(@NonNull final BluetoothDevice device,
@NonNull final String message, final int errorCode);
/**
* Called when service discovery has finished but the main services were not found on the device.
*
* @param device the device that failed to connect due to lack of required services.
*/
void onDeviceNotSupported(@NonNull final BluetoothDevice device);
/**
* The device address obtained after connecting the device successfully
*
* @param device address
*/
void onAddress(String address);