FeasyHome SDK For Android

[中文]

SDK Resource Kit Download

[Download FeasyHome_SDK_1.0.1]

SDK Access Documents

Version	Revision	Date	Author
V1.0	Official release	2024/1/17	Chang Jigang

SDK usage background

• Using the BT671C module produced by Feasycom Company, with firmware version V9.7.3 and above

• Using stepless adjustable lighting fixtures with brightness and color temperature

• Using Android 12 and above systems

SDK Function Overview

Integrating this SDK into Android applications can quickly achieve Bluetooth Mesh network light control functions, which are roughly as follows:

• Realize fast and stable network entry and exit for devices

• Read the status of the lighting control equipment, including obtaining switch status, brightness value, and color temperature value

• Configure the lighting control equipment, including switch status setting, brightness value setting, and color temperature value setting

• Group management of devices, including grouping for light control and grouping for network disconnection

• Convenient home management functions

Understanding instance objects

Unnetworked devices

// Unnetworked devices
public class FMUnprovisionedDevice{
  private final BluetoothDevice device;
  private final ScanResult scanResult;
  private String name = "Unknown";
  private int rssi;
  private MeshBeacon beacon;
  private int deviceType = -1;
  private boolean isCheck = false;
}

Networked devices

// Networked devices
public class ExtendedNode {
  private long id = 0;
  private String node_uuid = null;
  private String node_name = null;
  private int node_address = 0;
  private int node_type = 1;
  private String mesh_uuid = null;
  private String node_light_state = "开启"; // “开启”、“关闭”
  private int node_brightness = 0;
  private int node_color_temperature = 0;
  private Room room = null;
  private boolean isCheck = false;
}

Group

// Group
public class ExtendedGroup {
  private long id = 0;
  private Integer group_address = null;
  private String group_name = null;
  private int group_type = 1;
  private String mesh_uuid = null;
  private int group_state = 0;
  private int brightness = 0;
  private int color_temperature = 0;
  private boolean isCheck = false;
}

Family

// Family
public class FMFamily {
  private long id = 0;
  private String mesh_uuid = null;
  private String mesh_name = null;
}

Quick Integration (Android)

Integrated SDK

• If you have not yet installed Android Studio, please visit the [Android official website]

Create Android project

• Create a new project in Android Studio

Place the aar library in the project libs directory

Configure the build.gradle file

• In the build. gradle file of the Android project, add the dependencies dependency library downloaded in the integration preparation

implementation fileTree(dir: "libs", include: ["*.aar"])
implementation "androidx.room:room-runtime:2.4.2"
annotationProcessor "androidx.room:room-compiler:2.4.2"
implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.0"
implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.0"
implementation "no.nordicsemi.android:log:2.3.0"
implementation "org.litepal.guolindev:core:3.2.3"
implementation "com.madgag.spongycastle:core:1.58.0.0"
implementation "com.madgag.spongycastle:prov:1.58.0.0"

Confusing configurations

• Configure the corresponding confusion configuration in the proguard rules. pro file

// Bugly
-dontwarn com.tencent.bugly.**
-keep public class com.tencent.bugly.**{*;}

// Litepal
-dontwarn org.litepal.**
-keep public class org.litepal.**{*;}

-keep public class com.feasycom.feasyhome.model.**{*;}

// AOP
-adaptclassstrings
-keepattributes InnerClasses, EnclosingMethod, Signature, *Annotation*

-keepnames @org.aspectj.lang.annotation.Aspect class * {
  public <methods>;
}

// OkHttp3
-keepattributes Signature
-keepattributes *Annotation*
-keep class okhttp3.** { *; }
-keep interface okhttp3.** { *; }
-dontwarn okhttp3.**
-dontwarn okio.**
-dontwarn org.conscrypt.**


-keepattributes *Annotation*
-keepclassmembers class * {
  @org.greenrobot.eventbus.Subscribe <methods>;
}
-keep enum org.greenrobot.eventbus.ThreadMode { *; }

// And if you use AsyncExecutor:
-keepclassmembers class * extends org.greenrobot.eventbus.util.ThrowableFailureEvent {
  <init>(java.lang.Throwable);
}

Initialize SDK

• In your application, you need to first grant permissions in the AndroidManifest.xml file. Please add the following code to your application manifest file:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission
  android:name="android.permission.BLUETOOTH_PRIVILEGED"
  tools:ignore="ProtectedPermissions" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-feature
  android:name="android.hardware.bluetooth_le"
  android:required="true" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

• You need to initialize the SDK in the main thread of the Application to ensure that all processes can be initialized. The example code is as follows:

public class AppApplication: LitePalApplication(){
  @Override fun onCreate(){
    super.onCreate();
    FMeshSDK.getInstance().init(this)
  }
}

Demo Run

• Please contact the sales personnel of Feiyitong to provide a Mesh demo version (BT671C, firmware V9.7.3 and above), and run the demo (FeasyHome) according to the “FeasyHome App User Manual”.

Interface Definition Document

Part 1: Device Joining the Network

• Start scanning for available non networked devices in the surrounding area

public interface ScanResultCallback {
  /// Callback every time a device is scanned
  void scannerResult(FMUnprovisionedDevice unprovisionedDevice);
}

/**
* TODO Start scanning for available non networked devices in the surrounding area
* @param currentFamily
* @param scanCallback
*/
public void beginScanUnprovisionedDevice(Family currentFamily, ScanResultCallback scanCallback)

• Stop scanning for available non networked devices in the surrounding area

/**
* TODO Stop scanning for available non networked devices in the surrounding area
*/
public void stopScanUnprovisionedDevice()

• Check if the array of non connected devices is a valid network accessible device

public interface DetectedCallback {
  /// Devices successfully detected
  void onDetectedDevice(String selectedDevice, List<FMUnprovisionedDevice> unprovisionedDevices);
  /// Detection failed
  void onDetectedFail(String error);

}

/**
* TODO  Check if the array of non connected devices is a valid network accessible device
* @param mSelectedDevice   Selected device
* @param detectedCallback  Detected callback
*/
public void checkValidDevices(List<FMUnprovisionedDevice> mSelectedDevice, DetectedCallback detectedCallback)

• Abandon network distribution for devices that have been detected as valid but not connected to the network

/**
* TODO Disconnect
* @param mac
*/
public void quitProvisioningCheckedValidDevices(String mac)

• Starting network distribution by detecting valid network accessible devices

public interface ProvisionCallback {
  /// Networking successful
  void onProvisionSuccess(ExtendedNode extendedNodeList, List<FMUnprovisionedDevice>                                            unprovisionedDevices);
  /// Networking failure
  void onProvisionFail();

}

/**
* TODO Network access equipment
* @param currentFamily      Current family
* @param mDetectedDevices   Detected devices
* @param provisionCallback  Provision callback
*/
public void beginProvisioningCheckedValidDevices(FMFamily currentFamily, List<FMUnprovisionedDevice> mDetectedDevices, ProvisionCallback provisionCallback)

Part 2: Equipment Management

• Get all devices in the current mesh network

/**
* TODO Get all devices in the current mesh network
* @param currentFamily Current family
* @return Return device array
*/
public List<ExtendedNode> getAllDeviceForCurrentFamily(FMFamily currentFamily)

• Change the name of the device

public interface UpdateNodeNameCallback {
  /// Name modification successful
  void updateNodeNameSuccess();
  /// Name modification failed
  void updateNodeNameFail();
}

/**
* TODO Change the name of the device
* @param newNodeName   New node name
* @param targetDevice  Target device
* @param updateNodeNameCallback Update node name callback
*/
public void updateDeviceName(String newNodeName, ExtendedNode targetDevice, UpdateNodeNameCallback updateNodeNameCallback)

• Reset device (device will be decommissioned and can be rescanned for networking)

public interface RestoreDeviceCallback {
  /// Device reset successful
  void onRestoreDeviceSuccess();
  /// Device reset failed
  void onRestoreDeviceFail(String error);
}

/**
* TODO Reset device (device will be decommissioned and can be rescanned for networking)
* @param currentFamily Current family
* @param targetDevice  Target device
* @param restoreDeviceCallback Restore device callback
*/
public void restoreDevice(FMFamily currentFamily, ExtendedNode targetDevice, RestoreDeviceCallback restoreDeviceCallback)

• Delete specified devices in the current home

/**
* TODO Delete specified devices in the current home
* @param currentFamily Current family
* @param targetDevice  Target device
* @return True deletion successful false deletion failed
*/
public boolean deleteDeviceForCurrentFamily(FMFamily currentFamily, ExtendedNode targetDevice)

• Get groups that specified devices can join

/**
* TODO Get groups that specified devices can join
* @param currentFamily Current family
* @param targetDevice  Target device
* @return Return group array
*/
public List<ExtendedGroup> getCanBeJoinGroupsForDevice(FMFamily currentFamily, ExtendedNode targetDevice)

• Get the groups that the specified device has joined

/**
* TODO Get the groups that the specified device has joined
* @param currentFamily Current family
* @param targetDevice  Target device
* @return Return group array
*/
public List<ExtendedGroup> getHaveJoinedGroupsForDevice(FMFamily currentFamily, ExtendedNode targetDevice)

• Control target devices to join groups

public interface JoinGroupCallback {
  /// Successfully joined the group
  void joinGroupSuccess();
  /// Joining group failed
  void joinGroupFail(String error);
}

/**
* TODO Control target devices to join groups
* @param targetDevice Target device
* @param targetGroup  Target Groups
* @param joinGroupCallback Join group callback
*/
public void deviceJoinGroup(ExtendedNode targetDevice, ExtendedGroup targetGroup, JoinGroupCallback joinGroupCallback)

• Control the target device to exit the group

public interface ExitGroupCallback {
  /// Successfully exited the group
  void exitGroupSuccess();
  /// Failed to exit group
  void exitGroupFail(String error);
}

/**
* TODO Control the target device to exit the group
* @param targetDevice Target device
* @param targetGroup  Target Groups
* @param exitGroupCallback Exit group callback
*/
public void deviceExitGroup(ExtendedNode targetDevice, ExtendedGroup targetGroup, ExitGroupCallback exitGroupCallback)

• Accessing lighting control devices (on/off)

public interface LightStateCallback {
  /// Successfully accessed the status of the light control device, returned to the on/off state
  void lightState(int src, boolean isOnOff);
  /// Failed to access the status of the lighting control device
  void lightStateFail(String error);

}

/**
* TODO  Accessing lighting control devices (on/off)
* @param targetDevice       Target light control equipment
* @param lightStateCallback True to turn on the lights, false to turn off the lights
*/
public void accessDeviceLightOnOffStatus(ExtendedNode targetDevice, LightStateCallback lightStateCallback)

• Accessing lighting control devices (brightness values)

public interface LightBrightnessCallback {
  /// Successfully accessed brightness of lighting control device, returned brightness value
  void lightBrightnessLevel(int src, int brightnessLevel);
  /// Access to brightness control device failed
  void lightBrightnessLevelFail(String error);
}

/**
* TODO Accessing lighting control devices (brightness values)
* @param targetDevice            Target light control equipment
* @param lightBrightnessCallback Brightness values range from 0 to 100
*/
public void accessDeviceLightLevel(ExtendedNode targetDevice, LightBrightnessCallback lightBrightnessCallback)

• Accessing lighting control devices (color temperature values)

public interface LightTemperatureCallback {
  /// Successfully accessed the color temperature value of the lighting control device, returned the color temperature value
  void lightTemperatureLevel(int src, int temperatureLevel);
  /// Access to color temperature of lighting control device failed
  void lightTemperatureLevelFail(String error);
}

/**
* TODO Accessing lighting control devices (color temperature values)
* @param targetDevice             Target light control equipment
* @param lightTemperatureCallback Color temperature values range from 0 to 100
*/
public void accessDeviceLightTemperature(ExtendedNode targetDevice, LightTemperatureCallback lightTemperatureCallback)

• Control light control equipment (on/off)

public interface LightStateCallback {
  /// Successfully controlled the status of the lighting control equipment and returned to the on/off state
  void lightState(int src, boolean isOnOff);
  /// Control lamp control device status failed
  void lightStateFail(String error);

}

/**
* TODO Control light control equipment (on/off)
* @param targetDevice Target light control equipment
* @param isOnOff On or off
*/
public void controlDeviceLightOnOff(ExtendedNode targetDevice, boolean isOnOff, LightStateCallback lightStateCallback)

• Control lighting control equipment (brightness value)

/**
* TODO Control lighting control equipment (brightness value)
* @param targetDevice          Target light control equipment
* @param targetBrightnessLevel Brightness values range from 0 to 100
*/
public void controlDeviceLightLevel(ExtendedNode targetDevice, int targetBrightnessLevel)

• Control lighting control equipment (color temperature value)

/**
* TODO control light control equipment (color temperature value)
* @param targetDevice           Target light control equipment
* @param targetBrightnessLevel  Brightness values range from 0 to 100
* @param targetTemperatureLevel Color temperature values range from 0 to 100
*/
public void controlDeviceLightTemperature(ExtendedNode targetDevice, int targetBrightnessLevel, int targetTemperatureLevel)

• Connecting proxy devices

/**
* TODO Connect to proxy node
* @param mCurrentFamily Current family
*/
public void connectProxyNode(FMFamily currentFamily)

Part 3: Group Management

• Get an array of groups in the current family

/**
* TODO Get an array of groups in the current family
* @param currentFamily Current family
* @return Returns the array of groups
*/
public List<ExtendedGroup> getGroupsForCurrentFamily(FMFamily currentFamily)

• Change group name

public interface UpdateGroupNameCallback {
  /// Successfully modified group name
  void updateGroupNameSuccess();
  /// Failed to modify group name
  void updateGroupNameFail();
}

/**
* TODO Change group name
* @param newGroupName New name
* @param targetGroup Target Groups
* @param updateGroupNameCallback Change group name callback
*/
public void modifyGroupName(String newGroupName, ExtendedGroup targetGroup, UpdateGroupNameCallback updateGroupNameCallback)

• One click withdrawal of group devices

/**
* TODO One click withdrawal of group devices
* @param currentFamily Current family
* @param extendedGroup Target Groups
*/
public void restoreAllDevicesForGroup(FMFamily currentFamily, ExtendedGroup targetGroup)

• Delete the specified group in the current family

/**
* TODO Delete the specified group in the current family
* @param currentFamily Current family
* @param targetGroup   Target Groups
* @Returns True - deletion successful, false - deletion failed
*/
public boolean removeGroupToCurrentFamily(FMFamily currentFamily, ExtendedGroup targetGroup)

• Create a Group in the current family

public interface CreateGroupCallback {
  /// Group creation successful
  void createGroupSuccess(ExtendedGroup extendedGroup);
  /// Group creation failed
  void createGroupFail(String error);
}

/**
* TODO Create a Group in the current family
* @param currentFamily       Current family
* @param newGroupName        New group name
* @param createGroupCallback Is the operation result successful? If it fails, return error information
*/
public void createGroupToCurrentFamily(FMFamily currentFamily, String newGroupName, CreateGroupCallback createGroupCallback)

• Get the devices that can be added to the specified group

/**
* TODO Get the devices that can be added to the specified group
* @param currentFamily Current family
* @param targetGroup   Target Groups
* @return Return devices that can be subscribed to
*/
public List<ExtendedNode> getCanBeAddtionDevicesForGroup(FMFamily currentFamily, ExtendedGroup targetGroup)

• Get a list of devices that have been added to the specified group

/**
* TODO Get a list of devices that have been added to the specified group
* @param currentFamily  Current family
* @param targetGroup    Target Groups
* @return Return to the list of added devices
*/
public List<ExtendedNode> getHaveAddedDevicesForGroup(FMFamily currentFamily, ExtendedGroup targetGroup)

• Control target group to add devices

/**
* TODO Control target group to add devices
* @param targetDevice      Target device
* @param targetGroup       Target Groups
* @param joinGroupCallback Join group callback
*/
public void groupAddDevice(ExtendedNode targetDevice, ExtendedGroup targetGroup, JoinGroupCallback joinGroupCallback)

• Control target group removal of devices

/**
* TODO Control target group removal of devices
* @param targetDevice      Target device
* @param targetGroup       Target Groups
* @param exitGroupCallback Remove group callback
*/
public void groupRemoveDevice(ExtendedNode targetDevice, ExtendedGroup targetGroup, ExitGroupCallback exitGroupCallback)

• Control group devices (on/off)

/**
* TODO Control group devices (on/off)
* @param targetGroup Target Groups
* @param onStatus    True to turn on the lights, false to turn off the lights
*/
public void controlGroupLightOnOff(ExtendedGroup targetGroup, boolean onStatus)

• Control group devices (brightness value)

/**
* TODO Control group devices (brightness value)
*
* @param targetGroup Target Groups
* @param targetLevel Brightness values range from 0 to 100
* @param temperatureLevel Color temperature values range from 0 to 100
*/
public void controlGroupLightLevel(ExtendedGroup targetGroup, int targetLevel, int temperatureLevel)

• Control group devices (color temperature values)

/**
* TODO Control group devices (color temperature values)
* @param targetGroup      Target Groups
* @param targetLevel      Brightness values range from 0 to 100
* @param temperatureLevel Color temperature values range from 0 to 100
*/
public void controlGroupLightTemperature(ExtendedGroup targetGroup, int targetLevel, int temperatureLevel)

Part 4: Family Management

• Query Family List

/**
* TODO Query Family List
* @return Return existing family list data, if there are no families, return null
*/
public List<FMFamily> queryAllFamilys()

• Query current family

/**
* TODO Query current family
* @return Return the current family object
*/
public FMFamily queryCurrentFamily()

• Modify the current family name

public interface UpdateFamilyNameCallback {
  /// Family name successfully modified
  void updateFamilyNameSuccess();
  /// Family name modification failed
  void updateFamilyNameFail(String error);
}

/**
* TODO Modify the current family name
* @param newName                  New family name
* @param updateFamilyNameCallback Is the operation result successful? If it fails, return error information
*/
public void modifyCurrentFamilyName(long familyId, String newName, UpdateFamilyNameCallback updateFamilyNameCallback)

• Delete Family

public interface DeleteFamilyCallback {
  /// Family deleted successfully
  void deleteFamilySuccess();
  /// Family deletion failed
  void deleteFamilyFail(String error);
}

/**
* TODO Delete Family
* @param currentFamily        Current family
* @param deleteFamilyCallback Is the operation result successful? If it fails, return error information
*/
public void deleteFamily(FMFamily currentFamily, DeleteFamilyCallback deleteFamilyCallback)

• Create a new family

public interface CreateFamilyCallback {
  /// Family created successfully
  void createFamilySuccess(FMFamily family);
  /// Family creation failed
  void createGroupFail(String error);
}

/**
* TODO Create a new family
* @param newFamilyName The name of the new family
* @param createFamilyCallback Create a home callback
*/
public void createFamily(String newFamilyName, CreateFamilyCallback createFamilyCallback)

• Switch current home

public interface SwitchFamilyCallback {
  /// Family switch successful
  void switchFamilySuccess();
  /// Family switching failed
  void switchFamilyFail(String error);
}

/**
* TODO Switch current home
* @param targetFamily         Target family to switch to
* @param switchFamilyCallback Is the operation result successful? If it fails, return error information
*/
public void switchCurrentFamily(FMFamily targetFamily, SwitchFamilyCallback switchFamilyCallback)

Attachment

Download PDF Version

Download PDF Version