MinewSensor ToF Kit Instruction document

This SDK only supports the Bluetooth sensor devices from Minew. The SDK helps developers to handle everything between the phone and the sensor, including: scanning the device, broadcasting data, connecting to the device, writing data to the device, receiving data from the device, etc.

Preliminary work

Overall framework: MSD01BleManager is the device management class, which is always a single instance when the app is running. MSD01Model is the device instance class, this suite generates an instance for each device, which is used after scanning and connecting, and contains device broadcast data inside, which will be updated during scanning as the device keeps broadcasting.

MSD01BleManager：Device management class that scans the surrounding msd01 devices and can connect them, verify them, etc.；

MSD01Model：Example of an msd01 sensor device acquired during scanning, inherited from BaseBleDeviceEntity

Import to project

1. Development Environment

   The minimum sdk support is Android 7.0, corresponding to API Level 24. set minSdkVersion to 24 or above in build.gradle of the module.

   android {
   
       defaultConfig {
           applicationId "com.xxx.xxx"
           minSdkVersion 24
       }
   }
   

2. Add jar to the module's libs folder and add the following statement to the build.gradle of the module (add the dependency directly)：

   implementation files('libs/lib_ble_base.jar')
   implementation files('libs/lib_ble_msd01.jar')
   implementation files('libs/lib_ble_nl.jar')
   implementation files('libs/lib_ble_v3.jar')
   api 'org.lucee:bcprov-jdk15on:1.52.0'
   

   Or right-click the jar file and select Add as Library to add it to the current module.

   Add the configuration to the.so library file in the App directory build.gradle

   android {
       defaultConfig {
     
           ndk {
               abiFilters 'armeabi-v7a','arm64-v8a','x86','x86_64'
           }
   
       }
       sourceSets {
           main {
               jniLibs.srcDirs = ['libs']
           }
       }
   }
   

3. The following permissions are required in AndroidManifest.xml, and if targetSdkVersion is greater than 23, you need to do permission management to get the permissions.

       <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" tools:node="replace" />
       <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" tools:node="replace" />
       <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
       <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
       <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
       <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
       <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
       <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
   
       <uses-permission android:name="android.permission.READ_MEDIA_AUDIO"/>
       <uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
       <uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
       <uses-permission android:name="android.permission.READ_MEDIA_VISUAL_USER_SELECTED"/>
       <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
           android:maxSdkVersion="32" />
       <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
           android:maxSdkVersion="32"
           />
   
   

​

Use

The sdk is divided into three phases: scanning, connecting, and reading and writing.

Scanning section

Start scanning

For Android 6.0 and above systems, when performing BLE scanning, you need to apply for Bluetooth permission and turn on the positioning switch before proceeding.

To enable Bluetooth scanning, you need to turn on Bluetooth first. If you scan without turning on Bluetooth, the APP will crash. You can use BLETool.checkBluetooth(this) to determine whether Bluetooth is turned on. If it is not turned on, you can turn on Bluetooth first.

MSD01BleManager mBleManager = 	MSD01BleManager.getInstance();
switch (BLETool.checkBluetooth(this)){
    case BLE_NOT_SUPPORT:
        Toast.makeText(this, "Not Support BLE", Toast.LENGTH_SHORT).show();
        break;
    case BLUETOOTH_ON:
		//Set the scan time to 5 minutes. The default scan time of SDK is 5 minutes.
		mBleManager.startScan(this, 5 * 60 * 1000, new OnScanDevicesResultListener<MST03Entity>() {

            @Override
            public void onScanResult(List<MSD01Model> list) {
                
            }

            @Override
            public void onStopScan(List<MSD01Model> list) {

            }

        });
        
        break;
    case BLUETOOTH_OFF:
        Intent enableIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE);
        startActivityForResult(enableIntent, 4);
        break;
}

The SDK does not process the Bluetooth scanning duration internally, but scanning is a power-consuming operation. The SDK stops scanning after 5 minutes by default. If you still need to continue scanning, you can provide a timer or refresh operation to continue calling the scanning method to continue scanning the device.。

Retrieve data

During the scan, the APP is able to get a part of the current data of the device through the sdk. The data of the device is obtained through MSD01Model as shown below, which is stored in the broadcast frame object.

The sdk provides BaseBleDeviceEntity as the base class of MSD01Model to store the public data of the sensor device as shown in the following table.

Name	Type	Description
macAddress	String	device mac
name	String	Device name
rssi	int	Signal strength

The BaseBleDeviceEntity also keeps a Map, which is used internally to store the device broadcast data frames it acquires during a scan, and can be retrieved as follows

MSD01Model module;
if(module.deviceType == DeviceType.MSD01_TOF){
    // ToF ranging sensor type
}else if(module.deviceType == DeviceType.MSD01_OCCUPY){
    // Occupancy sensor type
}


DeviceInformationFrame deviceInforFrame = (DeviceInformationFrame)module.getMinewFrame(FrameType.DEVICE_INFORMATION_FRAME);
CombinationFrame combinationFrame = (CombinationFrame) module.getMinewFrame(FrameType.INDUSTRIAL_HT_FRAME);
if (deviceInforFrame != null) {
    //Device mac address
    String macAddress = deviceInforFrame.getMacAddress();
    //Percentage of power
    int battery = deviceInforFrame.getBattery();
    //firmware version
    String firmwareVersion = deviceInforFrame.getFirmwareVersion();
}

ToFFrame toFFrame = (ToFFrame) module.getMinewFrame(FrameType.TOF_FRAME);
if (toFFrame != null) {
	int serialNumber = toFFrame.getSerialNumber();//serial number
    int distance = toFFrame.getDistance();//Measure distance value，Unit millimeter is invalid=65535 
    int lowBattery = toFFrame.getLowBattery();//Low battery alarm signal
    int occupy = toFFrame.getOccupy();//Occupation judgment
    int infraredTrigger = toFFrame.getInfraredTrigger();//Infrared trigger signal
    int dismantle = toFFrame.getDismantle();//tamper-proof alarm signal
    int occupyNumber = toFFrame.getOccupyNumber();//Occupation frequency serial number
    int dismantleNumber = toFFrame.getDismantleNumber();//tamper-proof alarm serial number
}

There are 2 types of adv frames for Msd01 device。

1. Device information frame

   • DeviceInformationFrame

     Name	Type	Description
     frameVersion	int	device type
     firmwareVersion	String	Firmware Version
     batteryLevel	int	Battery Level Percentage
     macAddress	String	firmware mac
     peripheralSupportInfo	PeripheralSupportInfo	Description of peripheral support

2. ToF frame

   • ToFFrame

     Name	Type	Description
     serialNumber	int	The serial number is used to indicate the number of times the trigger has been activated, incrementing each time the trigger is activated (counting starts from 0 and resets to 0 after reaching 255)
     distance	int	Measure distance value, unit in millimeters. Invalid=65535
     lowBattery	int	Low battery alarm signal—0 indicates normal, 1 indicates low battery
     occupy	int	Occupancy Judgment — 0 indicates idle, 1 indicates occupied
     infraredTrigger	int	Infrared trigger signal -0 indicates not triggered, 1 indicates triggered
     dismantle	int	tamper-proof alarm signal -0 indicates normal, 1 indicates tamper-proof alarm
     occupyNumber	int	Occupation frequency sequence number: used to indicate the number of occupancy triggers, which increases automatically each time triggered (counting from 0, up to 255, and counting again from zero after exceeding 255)
     dismantleNumber	int	tamper-proof alarm serial number: used to indicate the number of times the tamper-proof alarm is triggered, and it increases automatically each time it is triggered (counting from 0, up to 255, and counting again from zero after exceeding 255)

Connections

It is usually necessary to stop scanning before connecting. sdk provides methods to connect and disconnect.。

MSD01BleManager mBleManager = 	MSD01BleManager.getInstance();

//Stop scanning
mBleManager.stopScan(context);
//Setting the device secret key
String key="minewtech1234567";
mBleManager.setSecretKey(key);
//Connection, module for the device to be connected 
MSD01Model module;
mBleManager.connect(context,module);
//Disconnect. macAddress is the device mac
mBleManager.disConnect(macAddress);

Note: Before connecting the device, please confirm whether the device is scanned, if no device broadcast is scanned and the connection method is called, the connection will fail.

After calling connect(), there will be a status listener in sdk for the connection process.

//Setting the listener
mBleManager.setOnConnStateListener(new OnConnStateListener() {
    
    /*
     * Status callbacks during connection
     *
     * @param macAddress      device mac
     * @param connectionState status
     */
    @Override
    public void onUpdateConnState(String address, BleConnectionState state) {
        switch (state) {
            case Disconnect:
				//Connection failure or device disconnection will be called back, active disconnection will not call back the .
                break;
            case EnterAuthenticatePassword:
                //Enter the SecretKey
				String key="minewtech1234567";
				mBleManager.setSecretKey(macAddress,key);
                mBleManager.authenticateV3Password(msd01Model)
                break;
            case Connecting:
				//This state will be called back after calling connect()
                break;
            case Connected:
                //The initial connection was successful, as a transition phase, but not really successful at this point.
                break;
            case AuthenticateFail:
				//Key verification failed.
                break;
            case AuthenticateSuccess:
				//Key verification successful.
                break;
            case ConnectComplete:
				//Connection is complete, the device is now ready for read and write operations.
                break;
            default:
                break;
        }
    }
});

During the connection process, sdk will return multiple connection states to the app, which the app needs to handle properly.

• BleConnectionState.Connecting，BleConnectionState.Connected: Connecting the device in, do not do time-consuming operations in this state, because at this time in the connected device discovery service, and send authentication data, etc.。
• BleConnectionState.EnterAuthenticatePassword: The device needs to prompt the user to enter the connection secret key, pass in the password entered by the user through the setSecretKey method of Msd01BleManager, and then call the authenticateV3Password method of Msd01BleManager for authentication.
• BleConnectionState.ConnectComplete: The sensor device is successfully connected at this point, and can perform read and write operations, such as configuring advparameters, sensor configuration, reading historical data, etc.。
• BleConnectionState.AuthenticateFail：The secret key is verified during the authentication process. If the entered secret key is incorrect, this state will be called back and the device will actively disconnect.
• BleConnectionState.AuthenticateSuccess：The secret key is verified during the authentication process. If the entered secret key is correct, this status will be called back.
• BleConnectionState.Disconnect: The callback will be made if the connection fails or the device is disconnected.

Reading and writing

The read and write APIs are as follows.：

	/**
     * connected device
     * @param context context
     * @param module device module
     */
	void connect(Context context, MSD01Model module);

   /**
     * connected device
     * @param context context
     * @param macAddress device macAddress
     */
    void connect(Context context, String macAddress);

    /**
     * Set connection secretKey
     * @param macAddress macAddress
     * @param secretKey  secretKey
     */
	void setSecretKey(String macAddress, String secretKey);

    /**
     * authentication
     * @param module device module
     */
    void authenticateV3Password(MSD01Model module);

    /**
     * Disconnect
     * @param macAddress device macAddress
     */
	void disConnect(String macAddress)
        
    /**
     * Restore factory settings
     *
     * @param macAddress macAddress
     * @param listener
     */
     void reset(String macAddress, OnModifyConfigurationListener listener);

    /**
     * Shut down
     * @param macAddress macAddress
     * @param listener
     */
    void powerOff(String macAddress, OnModifyConfigurationListener listener);

    /**
     * Set time (timing)
     * @param macAddress macAddress
     * @param timestamp Current timestamp of the system， The unit is second
     * @param listener
     */
	void setSyncTime(String macAddress, long timestamp, OnModifyConfigurationListener listener);
        
    /**
     * Upgrade file verification
     * @param macAddress macAddress
     * @param zipFilePath OTA File storage path
     * @param dfuProductIdTypes  Product Type Matching List
     */
	boolean verifyOtaFile(String macAddress, String zipFilePath, List<String> dfuProductIdTypes);

	//dfuProductIdTypes：
        // MSD01Model module : The device object that has already been connected
        if(module.deviceType.productID.equals("0024")){
            dfuProductIdTypes.add("MSD01-001-DT00")
        }else if(module.deviceType.productID.equals("0025")){
            dfuProductIdTypes.add("MSD01-002-DT00")
        }

    /**
     * Firmware update
     * @param macAddress macAddress
     * @param isLinkUpgrade   Is it a link upgrade
     * @param dfuTarget dfuTarget = 0
     * @param upgradeData : Upgrade package data bytes from read OTA file
     * @param listener
     */
	void firmwareUpgrade(String macAddress, boolean isLinkUpgrade, int dfuTarget, byte[] upgradeData, OnFirmwareUpgradeListener listener);

    /**
     * Query device version information
     * @param macAddress macAddress
     * @param listener
     */
	void queryDeviceFirmwareInfo(String macAddress, OnQueryResultListener<FirmwareVersionModel> listener);

    /**
     * Query the status of device switches
     * @param macAddress macAddress
     * @param listener
     */
	void queryOptionSwitch(String macAddress, OnQueryResultListener<List<OptionSwitchConfig>> listener);
	OptionSwitchConfig{
        int type;// Type: Light effect of 5, data storage of 6
    	int optionStatus;// Status: 1 is open, otherwise it is closed
    }

    /**
     * Set the light effect switch
     * @param macAddress macAddress
     * @param optionValue  ：1 is on, 0 is off
     * @param listener
     */
	void setLightOptionSwitch(String macAddress, int optionValue, OnModifyConfigurationListener listener);

    /**
     * Set data storage switch
     * @param macAddress macAddress
     * @param optionValue  ：1 is on, 0 is off
     * @param listener
     */
	void setDataStoreOptionSwitch(String macAddress, int optionValue, OnModifyConfigurationListener listener);

    /**
     * Query broadcast parameters
     * @param macAddress macAddress
     * @param slot  ：0 - DeviceInfoFrame，1 - ToFFrame
     * @param listener
     */
	void queryAdvParametersConfiguration(String macAddress, int slot, OnQueryResultListener<AdvParametersConfig> listener);
	AdvParametersConfig{
        int slotNumber;// The channel number of this frame
        String frameType;// Frame Type
        int advertisingInterval;// advertising Interval
        int txPower;// txPower
        int alwaysAdvertising;// this frame is always Advertising
    }

	/**
     * Set adv parameters
     * @param macAddress macAddress
     * @param frameType ：AdvParametersConfig.frameType —— default configure the queryAdvParametersViguration method to query and obtain the current frame type value
     * @param slotNumber  ：AdvParametersConfig.slotNumber —— default configure the queryAdvParametersViguration method to query and obtain the current frame channel value
     * @param advertisingInterval  ：advertising Interval 500ms ~ 10000ms
     * @param isAlwaysAdv  ：if enable continuous broadcasting —— default configure the queryAdvParametersViguration method to query whether the current frame obtained has enabled continuous broadcast values
     * @param txPower  ：txPower -40 -20 -16 -12 -8 -4 0 4 dBm
     * @param listener
     */
	void setAdvParametersConfiguration(String macAddress, String frameType, int slotNumber, int advertisingInterval,int isAlwaysAdv, int txPower, OnModifyConfigurationListener listener);

	/**
     * Query ToF ranging parameters
     * @param macAddress macAddress
     * @param listener
     */
    void queryToFConfiguration(String macAddress, OnQueryResultListener<ToFConfiguration> listener);

	ToFConfiguration{
        int threshold = 0;//Distance alarm threshold, unit: millimeters (mm). When the distance measurement mode is selected as the standard mode of 2.5m, the occupancy threshold can be set within the range of 20mm~2400mm. When the distance measurement mode is selected as 5.0m, the occupancy threshold can be set within the range of 20mm~4900mm
   		int interval = 0;//The distance interval for periodic distance measurement, unit: seconds (s), default interval: 1 minute; Range: 10s~43200s (12h)
    	int distanceMode = 0;//Distance measurement mode, 0: maximum distance 2400 standard mode, 1: maximum distance 4900 remote mode
    	int occupationTime = 0;//Duration of occupancy: After successful distance measurement in PIR mode, the duration of one occupancy state is measured in seconds (s), with a default duration of 1 minute; Range: 10s~1800s (30min)
    	int distanceTimes = Integer.MIN_VALUE;//The number of times TOF collects data during a complete distance measurement The higher the frequency, the higher the accuracy, and the longer the distance measurement time. The higher the corresponding power consumption; Range: 1~10 times, default times: 10 times
        //1. High precision gear: 10Hz [High] —— distanceTimes = 10
        //2. Standard ranging gear: 3Hz [Medium] —— distanceTimes = 3
        //3. Low power ranging gear: 1Hz [Low] —— distanceTimes = 1
    	int pirRangeInterval = Integer.MIN_VALUE;//PIR cycle ranging interval, unit: minutes (min), default interval: 1 minute; Range: 1min~60min
    	int periodicRangingInThePir = Integer.MIN_VALUE;//Periodic distance measurement switch in PIR mode distance measurement; 1: Turn on cycle distance measurement in PIR mode, 0: Turn off cycle distance measurement in PIR mode Default state: 0, closed state
    }


	/**
     * Set ToF ranging parameters
     * @param macAddress macAddress
     
     * @param threshold ：Distance alarm threshold, unit: millimeters (mm). When the standard mode is selected as 2.5m for distance measurement mode, the occupancy threshold can be set within the range of 20mm~2400mm. When the distance measurement mode is selected as 5.0m for distance measurement mode, the occupancy threshold can be set within the range of 20mm~4900mm. If the value is not need change, configure the default value obtained by querying from the queryToFConfiguration method
     
     * @param interval  ：The distance interval for periodic distance measurement, unit: seconds (s), default interval: 1 minute; Range: 10s~43200s (12h), if value is not need change, configure the default value obtained by querying from the queryToFConfiguration method
     
     * @param distanceModel  ：Distance measurement mode, 0: maximum distance 2400 standard mode, 1: maximum distance 4900 remote mode, the maximum distance mode that the device can measure. If value is not need change, configure the default value obtained by querying from the queryToFConfiguration method
     
     * @param occupationTime  ：Duration of occupancy: After successful distance measurement in PIR mode, the duration of one occupancy state is measured in seconds (s), with a default duration of 1 minute; Range: 10s~1800s (30min), if value is not need change, configure the default value obtained by querying from the queryToFConfiguration method
     
     * @param distanceTimes  ：The number of times TOF collects data during a complete distance measurement The higher the frequency, the higher the accuracy, and the longer the distance measurement time. The higher the corresponding power consumption; Range: 1~10 times, default times: 10 times，if value is not need change, configure the default value obtained by querying from the queryToFConfiguration method
        //1. High precision gear: 10Hz [High] —— distanceTimes = 10
        //2. Standard ranging gear: 3Hz [Medium] —— distanceTimes = 3
        //3. Low power ranging gear: 1Hz [Low] —— distanceTimes = 1
     
     * @param pirRangeInterval ：PIR cycle ranging interval, unit: minutes (min), default interval: 1 minute; Range: 1min~60min，if value is not need change, configure the default value obtained by querying from the queryToFConfiguration method
     
     * @param periodicRangingInThePir ：Periodic distance measurement switch in PIR mode distance measurement; 1: Turn on cycle distance measurement in PIR mode, 0: Turn off cycle distance measurement in PIR mode Default state: 0, closed state，if value is not need change, configure the default value obtained by querying from the queryToFConfiguration method
     
     * @param listener
     */
	void setToFParameters(String macAddress, int threshold, int interval, int distanceModel, int occupationTime, int distanceTimes, int pirRangeInterval, int periodicRangingInThePir, OnModifyConfigurationListener listener);

    /**
     * query History Data
     * @param macAddress macAddress
     * @param rules Historical data retrieval rules, 0 represents retrieving all data, 1 represents retrieving data from a certain time period, when rules==0, both startTime and endTime do not need to be passed, and 0 is passed by default
     * @param startTime Starting timestamp unit: seconds
     * @param endTime End timestamp unit: seconds
     * @param systemTime Real time timestamp unit: seconds
     * @param listener
     */
	void queryHistoryData(String macAddress, int rules, long startTime, long endTime, long systemTime, OnQueryResultListener<HistoryToFData> listener);

Reading and writing：

4. Query device version information。

   MSD01BleManager mBleManager = 	MSD01BleManager.getInstance();
   
   mBleManager.queryDeviceFirmwareInfo(macAddress,new OnQueryResultListener<FirmwareVersionModel>() {
               @Override
               public void OnQueryResult(boolean b, FirmwareVersionModel firmwareVersionModel) {
   				//b true query succeeds, false query fails ,firmwareVersionModel=null。
                   Toast.makeText(context,"Query Result:"+b,Toast.LENGTH_LONG).show();
                   if(b){
                       List<VersionInfo> versionInfoList = firmwareVersionModel.getVersionInfoList();
                       String firmwareName = versionInfoList.get(0).getFirmwareName();
                       int firmwareType = versionInfoList.get(0).getFirmwareType();
                       String firmwareVersion = versionInfoList.get(0).getFirmwareVersion();
                   }
               }
           });
   

5. Query historical data

       /**
        * query History Data
        *
        * @param macAddress macAddress
        * @param rules rules Historical data retrieval rules, 0 represents retrieving all data, 1 represents retrieving data from a certain time period, when rules==0, both startTime and endTime do not need to be passed, and 0 is passed by default
        * @param startTime Starting timestamp unit: seconds
        * @param endTime End timestamp unit: seconds
        * @param systemTime Real time timestamp unit: seconds
        * @param listener
        */
   long systemTime = System.currentTimeMillis()/1000;
   long startTime = (systemTime-60*60*1000*24)/1000;
   long endTime = systemTime;
   
   int rule = 0;
   
   mBleManager.queryHistoryData(macAddress,rule, startTime, endTime, systemTime, new OnQueryResultListener<HistoryHtData>() {
   
       @Override
       public void OnQueryResult(boolean b, HistoryToFData historyToFData) {
           if(b){
                  List<Records> historyDataList = historyHtData.getHistoryDataList();
                  for (Records records : historyDataList) {
                           
                  }
           }else{
               Toast.makeText(context,"selectHTHistoryData Result: fail",Toast.LENGTH_LONG).show();
           }
   
       }
   
   
   });
   

6. Firmware upgrade.

       /**
        * Firmware update
        * @param macAddress macAddress
        * @param isLinkUpgrade   Is it a link upgrade
        * @param dfuTarget dfuTarget = 0
        * @param upgradeData : Upgrade package data bytes from read OTA file
        * @param listener
        */
   mBleManager.firmwareUpgrade(mac, false,0,upgradeData, new OnFirmwareUpgradeListener() {
       
       /**
        * Upgrade package data writing progress
        */
       @Override
       public void updateProgress(int progress) {
   		
       }
   
   	/**
         * Callback when the upgrade is successful. At this time, the device will actively disconnect from the mobile phone, so       * the OnConnStateListener callback will be triggered and return
         * BleConnectionState.Disconnect state
         */
       @Override
       public void upgradeSuccess() {
   
       }
       
   	/**
         * Upgrade failed
         */
       @Override
       public void upgradeFailed() {
   
       }
   });
   

History

• 2026/01/15 Add editing documents and add Api for ToF distance measurement basic function ;