MinewMWC03Kit Documentation

This SDK only supports Bluetooth devices produced by Minew company.

SDK can assist developers in handling all tasks between mobile phones and Bluetooth devices, including scanning devices, broadcasting data, connecting devices, writing data to devices, receiving data from devices, etc.

At present, the SDK only supports the use of BLE LTE Location Badge devices.

Preliminary work

Overall framework: MWC03BleManager is a device management class that remains singleton during app runtime. MWC03Model is a device instance class that generates an instance for each device, which is used after scanning and connecting. It contains device broadcast data, which is updated as the device broadcasts continuously during scanning. ``MWC03BleManager: Device management class that can scan surrounding devices, connect them, verify them, etcMWC03Model: The BLE LTE Location Badge device instance obtained during scanning, inherited from BaseBleDeviceEntity`

Import into project

1. development environment

   The SDK supports a minimum of Android 5.0 and corresponds to API Level 21. Set minSdkVersion to 21 or above in the build. gradle of the module:

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

2. Add the jar package to the libs folder of the moduleand add the following statement in the build. gradle of the module (directly add dependencies):

   implementation files('libs/lib_ble_base.jar')
   implementation files('libs/lib_ble_mwc03.jar')
   implementation files('libs/lib_ble_nl.jar')
   implementation files('libs/lib_ble_v3.jar')
   api 'org.lucee:bcprov-jdk15on:1.52.0'
   api 'com.fasterxml.jackson.dataformat:jackson-dataformat-cbor:2.16.0'
   

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

   Add the. so library file and add the following configuration to build. gradle in the App directory:

   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 If targetSdkVersion is greater than 23, permission management needs to be done to obtain 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_IMAGES" />
       <uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />
       <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
       <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

SDK is divided into three stages: scanning, connection, and read-write.

For Android 6.0 and above systems, when performing BLE scanning, it is necessary to first apply for Bluetooth permission and turn on the location switch before proceeding.

Start Scan

For Android 6.0 and above systems, when performing BLE scanning, it is necessary to first apply for Bluetooth permission and turn on the location switch before proceeding.

To enable Bluetooth scanning, you need to first turn on Bluetooth. If you scan without turning on Bluetooth, the app will flash back. BLETool. checkBluetooth (this) can be used to determine if Bluetooth is turned on. If it's not turned on, you can turn on Bluetooth first.

MWC03BleManager mBleManager = MWC03BleManager.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 scanning time to 5 minutes, the SDK defaults to a scanning time of 5 minutes
		mBleManager.startScan(this, 5 * 60 * 1000, new OnScanDevicesResultListener<MWC03Model>() {
            @Override
            public void onScanResult(List<MWC03Model> list) {
            }

            @Override
            public void onStopScan(List<MWC03Model> list) {
            }
        });
        break;
    case BLUETOOTH_OFF:
        Intent enableIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE);
        startActivityForResult(enableIntent, 4);
        break;
}

During the scanning process, the APP can obtain a portion of the current device data through the SDK. Obtain device data through the MWC03Model as shown below, which is saved in the broadcast frame object.

The SDK providesBaseBleDeviceEntity as the base class for MWC03Model to store public data of devices, as shown in the following table:

field	type	description
macAddress	String	mac
name	String	device name
rssi	int	blue strength

BaseBleDeviceEntity also stores a Map, which is used internally to store the device broadcast data frames obtained during scanning. It can be retrieved in the following ways:

MWC03Model module;
DeviceStaticInfoFrame deviceInforFrame = (DeviceStaticInfoFrame) module.getMinewFrame(FrameType.DEVICE_INFORMATION_FRAME);
LTEDeviceFrame lteDeviceFrame = (LTEDeviceFrame) module.getMinewFrame(FrameType.LET_DEVICE_FRAME);
if (deviceInforFrame != null) {
    //mac
    String macAddress = deviceInforFrame.getMacAddress();
    //Battery
    int battery = deviceInforFrame.getBattery();
    //FirmwareVersion
    String firmwareVersion = deviceInforFrame.getFirmwareVersion();
}
if (lteDeviceFrame != null) {
    //SignalStrength：from -140 to 0 —> The closer to 0, the stronger the signal
    float signalStrength = lteDeviceFrame.getSignalStrength();
    //Latitude
    float latitude = lteDeviceFrame.getLatitude();
    //Longitude
    float longitude = lteDeviceFrame.getLongitude();
    //Altitude
    float altitude = lteDeviceFrame.getAltitude();
}

BLE LTE Location Badge have 2 types of broadcast frames available。

1. DeviceStaticInfoFrame

   • DeviceStaticInfoFrame

     field	type	description
     frameVersion	int	device type
     firmwareVersion	String	firmware version
     batteryLevel	int	Percentage of battery charge
     macAddress	String	mac
     peripheralSupportInfo	PeripheralSupportInfo	Peripheral support description, including device product ID

2. LTEDeviceFrame

   • LTEDeviceFrame

     field	type	description
     signalStrength	int	Cellular signal strength
     latitude	double	latitude info
     longitude	double	longitude info
     altitude	double	altitude info

Connect

Before connecting, it is generally necessary to stop scanning. The SDK provides methods for connecting and disconnecting.

MWC03BleManager mBleManager = MWC03BleManager.getInstance();
//stop
mBleManager.stopScan(context);
//set SecretKey
String key="minewtech1234567";
mBleManager.setSecretKey(macAddress,key);
//Connection: The module is the device to be connected to
MWC03Model module;
mBleManager.connect(context,module);
//Disconnect: macAddress is the device's MAC address
mBleManager.disConnect(macAddress);

Attention: Before connecting the device, please confirm if the device is scanned. If the device broadcast is not scanned, calling the connection method will result in a connection failure.

After calling 'connect()', the SDK will monitor the status of the connection process.

//Set up listener
mBleManager.setOnConnStateListener(new OnConnStateListener() {
    /*
     * State callback during connection process
     * @param macAddress      mac
     * @param BleConnectionState connectionState
     */
    @Override
    public void onUpdateConnState(String address, BleConnectionState state) {
        switch (state) {
            case Connecting:
				//After calling connect(), the state will be called back
                break;
            case Connected:
                //The initial connection was successful, but as a transitional stage, it was not truly successful at this time
                break;
            case EnterAuthenticatePassword:
				//The V3 protocol device will require the input of the device connection password, and the timeout period is 30 seconds
				//Here, it is necessary to require the customer to enter the device connection password through pop ups or other interface interaction methods
				//e.g. showDialog -> input password ->
				//Set the device key entered by the user and initiate authentication
				String key="minewtech1234567";
				mBleManager.setSecretKey(macAddress,key);
                mBleManager.authenticateV3Password(mwC03Model)
                break;
            case Bond_None:
				//NanoLink protocol device pairing callback, this is an invalid pairing state
                break;
            case Bond_Bonding:
				//NanoLink protocol device pairing callback, this is in the pairing state
                break;
            case Bond_Bonded:
				//NanoLink protocol device pairing callback, here is the pairing completion status
                //NanoLink protocol devices must be paired before they can be operated using the methods provided in MWC03BleManager
                break;
            case AuthenticateFail:
				//V3 protocol device key verification failed
                break;
            case AuthenticateSuccess:
				//V3 protocol device key verification successful
                break;
            case ConnectComplete:
				//V3 protocol devices must be connected before they can be operated using the methods provided in MWC03BleManager
                break;
            case Disconnect:
				//Connection failure or device disconnection will trigger a callback, while active disconnection will not trigger this status
                break;
            default:
                break;
        }
    }
});

During the connection process, the SDK will return multiple connection states to the app, and the app needs to handle them properly.

• BleConnectionState.Connecting，BleConnectionState.Connected: In the connected device, do not perform time-consuming operations in this state, as the device discovers services and sends authentication data.
• BleConnectionState.EnterAuthenticatePassword: The V3 protocol type 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 MWC03BleManager, and then call the authenticateV3Password method of MWC03BleManager for authentication.
• BleConnectionState.Bond_None: The NanoLink protocol device pairing is invalid.
• BleConnectionState.Bond_Bonding: The NanoLink protocol device is currently in pairing mode.
• BleConnectionState.Bond_Bonded: The NanoLink protocol device pairing status is complete. Only after the NanoLink protocol device pairing is completed can the NanoLink protocol device be operated using the methods provided in MWC03BleManager.
• BleConnectionState.ConnectComplete: The V3 protocol device has been successfully connected and can perform read and write operations, such as configuring broadcast parameters and reading historical data.
• BleConnectionState.AuthenticateFail：During the device authentication process, if the input key is incorrect, this status will be called back and the device will actively disconnect.
• BleConnectionState.AuthenticateSuccess：During the device authentication process, if the key is verified and entered correctly, this status will be called back.
• BleConnectionState.Disconnect: Connection failure or device disconnection will result in a callback.

Device configuration read and write operations

The API for device configuration read and write operations is as follows, which can be called using the MWC03BleManager mBleManager=MWC03BleManager. getInstance() object:

    /**
     * Clear the list of scanning devices
     */
     void clearScanResult();

    /**
     * Set default scanning duration
     *
     * @param scanTime Scanning duration, in milliseconds
     */
     void setDefaultScanTime(int scanTime);

    /**
     * Start scanning device
     *
     * @param context context
     * @param listener OnScanDevicesResultListener
     */
     void startScan(Context context, OnScanDevicesResultListener listener) ;

    /**
     * Start scanning device
     *
     * @param context context
     * @param scanTime Scanning duration, in milliseconds
     * @param listener OnScanDevicesResultListener
     */
     void startScan(Context context, int scanTime, OnScanDevicesResultListener listener) ;

    /**
     * Stop scanning device
     *
     * @param context context
     */
     void stopScan(Context context) ;

    /**
     * Determine if scanning is in progress
     *
     */
     boolean isScanning() ;

    /**
     * Set the connection key for V3 protocol devices
     *
     * @param macAddress mac
     * @param key Device key
     */
     void setSecretKey(String macAddress, String key) ;

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

    /**
     * Shutdown
     *
     * @param macAddress mac
     * @param listener OnModifyConfigurationListener
     */
     void powerOff(String macAddress, OnModifyConfigurationListener listener);

    /**
     * Restart
     *
     * @param macAddress mac
     * @param listener OnModifyConfigurationListener
     */
     void reboot(String macAddress, OnModifyConfigurationListener listener);

    /**
     * Connected Device
     *
     * @param context context
     * @param macAddress mac
     */
	 void connect(Context context, String macAddress);

    /**
     * Connected Device
     *
     * @param context context
     * @param module MWC03Model
     */
	 void void connect(Context context, MWC03Model module);

    /**
     * Disconnect
     *
     * @param macAddress mac
     */
	 void void disConnect(String macAddress);

    /**
     * Set up device connection listener
     *
     * @param listener OnConnStateListener
     */
	void setOnConnStateListener(OnConnStateListener listener)

    /**
     * V3 protocol device firmware upgrade
     *
     * @param macAddress  mac
     * @param isLinkUpgrade ：true -> upgrade by url，false -> upgrade by file。Default value false, does not support URL upgrade method
     * @param dfuTarget isLinkUpgrade =true, dfuTarget = 0
     * @param upgradeData Upgrade package data
     * @param listener OnFirmwareUpgradeListener
     */
     void firmwareUpgrade(String macAddress,boolean isLinkUpgrade,int dfuTarget,byte[] upgradeData, 		 OnFirmwareUpgradeListener listener);

    /**
     * V3 protocol device and NanoLink protocol device firmware upgrade
     *
     * @param macAddress  mac
     * @param isLinkUpgrade ：true -> upgrade by url，false -> upgrade by file
     * @param dfuTarget isLinkUpgrade =true, dfuTarget = 0 (Used for upgrading V3 protocol devices, NanoLink protocol device upgrade is invalid)
     * @param upgradeData Upgrade package data(Used for upgrading V3 protocol devices, NanoLink protocol device upgrades can be  blank)
     * @param listener OnFirmwareUpgradeListener
     * @param firmwareUpgradeConfig (Used for upgrading configuration objects of NanoLink protocol devices, V3 protocol device upgrades can be blank)
     */
     void combineFirmwareUpgrade(String macAddress,boolean isLinkUpgrade,int dfuTarget,byte[] upgradeData, 		 OnFirmwareUpgradeListener listener,FirmwareUpgradeConfig firmwareUpgradeConfig);

	//Brief content about FirmwareUpgradeConfig class [NanoLink protocol upgrade using this configuration object]
	public class FirmwareUpgradeConfig {
        
            //Context
    		private Context context;
    		//mac地址
    		private String macAddress;
        
            public static final String URL_LINK_MODEM = "Modem";
    		public static final String URL_LINK_APP = "APP";
    		//Link upgrade method usage: firmware module name to be upgraded, default: URL_LINK-APP, optional URL_LINK-APP, URL_LINK-MODEM
    		private String upGradeFwName;
    		//Link upgrade method: Upgrade firmware URL
    		private String path;
        
            //File upgrade method usage: sent file content
    		private byte[] fileContent = null;
        	
    }

    /**
     * Set cellular APN parameters
     *
     * @param macAddress mac
     * @param PDAType PDAType
     * @param apnName apn name
     * @param listener OnModifyConfigurationListener
     */
     void setLteAPN(String macAddress, PDAType PDAType, String apnName, OnModifyConfigurationListener listener);

    /**
     * Set cellular APN parameters
     *
     * @param macAddress mac
     * @param PDAType PDAType 
     * @param apnName apn name
     * @param authType Authentication type: default "None", 1 is "PAP", 2 is "CHAP"
     * @param userName userName
     * @param passWord passWord
     * @param listener OnModifyConfigurationListener
     */
     void setLteAPN(String macAddress, PDAType PDAType, String apnName,int authType,String userName,String passWord, OnModifyConfigurationListener listener);

    /**
     * Obtain cellular APN parameters
     *
     * @param macAddress mac
     * @param listener OnQueryResultListener
     */
	void getLteAPN(String macAddress, OnQueryResultListener<LTEAPNModel> listener);
        
    //Brief content about the LTEAPNModel class
	public class LTEAPNModel {
            //Default unauthenticated type
    		public static final int NO_USE_AUTH_TYPE = 255;
    		//【V3 protocol】pda type
    		private PDAType pdnType ;
    		//apn name
    		private String apnName;
    		//IP address
    		private String ipAddress;
    		//【V3 protocol】Authentication type
    		private int authentication;
    		//user name
    		private String userName;
    		//password
    		private String passWord;
    		//【NanoLink protocol】pda type
    		private String type;
    		//【NanoLink protocol】Authentication type
    		private String auth;
    }

    /**
     * Query firmware version
     *
     * @param macAddress mac
     * @param listener OnQueryResultListener
     */
	void getFirmwareVersion(String macAddress, OnQueryResultListener<FirmwareVersionModel> listener);

    //Brief content about the FirmwareVersionsModel class
	public class FirmwareVersionModel {
        List<VersionInfo> versionInfoList;
    }

    //About the brief content of the VersionsInfo class
	public class VersionInfo {
        // Firmware Name
        private String firmwareName;
        // Firmware type
        private int firmwareType;
        // Firmware version
        private String firmwareVersion;
        // Firmware slot
        private String slot;
    }

	/**
     * Query network type
     *
     * @param macAddress mac
     * @param listener   OnQueryResultListener
     */
	void getNetworkType(String macAddress, OnQueryResultListener<NetworkType> listener);

	/**
     * Set network type
     *
     * @param macAddress mac
     * @param networkType   Network Type
     * @param listener   OnModifyConfigurationListener
     */
	void setNetworkType(String macAddress, NetworkType networkType, OnModifyConfigurationListener listener);

	/**
     * Connection authentication
     *
     * @param module Device entity object
     */
	void authenticateV3Password(@NonNull MWC03Model module);

	/**
     * OTA Firmware upgrade file format verification using V3 protocol devices
     *
     * @param macAddress mac
     * @param zipFilePath Zip format file path
     * @param dfuProductIdTypes The set of allowed product IDs in the zip format file
     */
	boolean verifyOtaFile(String macAddress,String zipFilePath,List<String> dfuProductIdTypes);

    /**
     * Obtain certificate file upload path [NanoLink protocol device]
     *
     * @param macAddress mac
     * @param listener OnQueryResultListener
     */
	void getCertificatesPath(String macAddress, OnQueryResultListener<CertificatesPathInfo> listener);

   
	/**
     * Upload certificate file for NanoLink protocol device
     *
     * @param macAddress mac
     * @param fileUploadConfig File upload configuration
     * @param onFileUploadListener Upload processing listener
     */
	void updateCertificates(String macAddress, FileUploadConfig fileUploadConfig, OnFileUploadListener onFileUploadListener); 

    //Brief content about FileUploadConfig class
	public class FileUploadConfig {
    	//The path for storing files on the device side is obtained through the getCertificates Path() method
    	private String devicePath = null;
    	//The name of the file stored on the device side is "ca" for ca.pem type files, "cert" for client-side. pem type files, and "priv" for client-side. key type files
    	private String deviceFileName = null;
        
        //File upload usage：Context
    	private Context context;
    	//File upload usage：mac
    	private String macAddress;
    	//File upload usage：The content of the sent file
    	private byte[] fileContent = null;
    }

	/**
     * Set MQTT connection parameters for NanoLink protocol devices
     *
     * @param macAddress mac
     * @param MQTTNanoLink MQTT configuration
     * @param listener OnModifyConfigurationListener
     */
	void setMQTTConnection(String macAddress, MQTTNanoLink MQTTNanoLink, OnModifyConfigurationListener listener);

	/**
     * Set MQTT theme parameters for NanoLink protocol devices
     *
     * @param macAddress mac
     * @param MQTTNanoLink MQTT configuration
     * @param listener OnModifyConfigurationListener
     */
	void setMQTTTopic(String macAddress, MQTTNanoLink MQTTNanoLink, OnModifyConfigurationListener listener);
	
	/**
     * Get MQTT connection parameters [NanoLink protocol device]
     *
     * @param macAddress mac
     * @param listener OnQueryResultListener
     */
	void getMQTTConnection(String macAddress, OnQueryResultListener<MQTTNanoLink> listener);

	/**
     * Get MQTT topic parameters for NanoLink protocol devices
     *
     * @param macAddress mac
     * @param listener OnQueryResultListener
     */
	void getMQTTTopic(String macAddress, OnQueryResultListener<MQTTNanoLink> listener);
	
	//Brief content about MQTTNanoLink class
	public class MQTTNanoLink {
        //Data reporting URL
    	private String url = "";
        //Data reporting port
    	private String port = "8883";
        //mqtt quality of service
    	private int qos = 0;
        //interval
    	private int intvl = 0;
        //client ID
    	private String client_id = "";
        //user name
    	private String usrname = "";
        //password
    	private String pwd = "";
        //Is SSL/TLS enabled? 'None' means not enabled, 'TLS' means enabled
    	private String sec = "";
        //Data reporting theme
    	private String notify = "";
        //Command Control Theme
    	private String req = "";
        //Command Control Response Theme
    	private String rsp = "";
    }
	

Provide additional explanations for some methods:

1. The command to make some cellular network configurations effective is very important and needs to be used after successfully calling the API for configuring MQTT, APN, and other device network related parameters to make the device network related parameter configurations effective:

   	/**
        * Network configuration effective command
        *
        * @param macAddress mac
        * @param listener OnNetworkConfigOnListener
        *
        * In calling setLteAPN，setNetworkType，updateCertificates，setMQTTConnection，setMQTTTopic  After the method is successful, it must be called once
        *
        */
   	void networkConfigOn(String macAddress, OnNetworkConfigOnListener listener);
   
   

2. Firmware upgrade:

   /**
    * Firmware upgrade:
    *
    * @param macAddress  mac
    * @param upgradeData Upgrade package data
    * @param listener    OnFirmwareUpgradeListener
    */
   mBleManager.firmwareUpgrade(mac,false,0, upgradeData, new OnFirmwareUpgradeListener() {
       
       /**
        * Update package data writing progress
        */
       @Override
       public void updateProgress(int progress) {
       }
   
       /**
        * Upgrade successful callback, at this point the device will actively disconnect from the phone, triggering the On State Listener callback and returning the BleeConnectionState.Disconnect status
        */
       @Override
       public void upgradeSuccess() {
       }
       
       /**
        * Upgrade failed
        */
       @Override
       public void upgradeFailed() {
       }
   });
   

Document update record

• 2025/06/11 Add MWC03 device operation basic function API