MinewModuleKit Programming Guide for Android

# MinewModuleKit Programming Guide for Android

This SDK only supports the module device producted by Minew. The developers can handle all bluetooth operations between iPhone and modules. such as: scan modules, connect modules, write data to modules, receive data from modules and so on.

# Structure

This framework is very simple: the MTModuleManager is device managing Class, always using shared instance when the APP is running. the MTModule is device instance Class, the SDK will create instances for devices. the developer can use the MTModule instance for operate module devices.

The framework is as the screenshot below:

设计说明

MTModuleManager： Device managing class, you can scan module devices around, and connect to the modules.

MTModule：the Module instance class, when the manager found a physical module device it will create a module instance for the device, the instance is correspond to the module device.

# PreWorks

# Environment：

Android Studio

# Import to project:

Please copy the MTModuleKit.jar file of the development kit to the libs directory and add dependencies to the build.gradle file of the corresponding module.As the screenshot below:

Add bluetooth permissions and corresponding component registration under the AndroidManifest.xml file.As follows:

    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.BLUETOOTH"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>

1
2
3
4
5

Bluetooth scanning in Android-6.0 or above requires dynamic application of geographical permission, as follows:

if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_COARSE_LOCATION)
                != PackageManager.PERMISSION_GRANTED) {
            ActivityCompat.requestPermissions(this,
                    new String[]{Manifest.permission.ACCESS_COARSE_LOCATION}, PERMISSION_COARSE_LOCATION);
        }

1
2
3
4
5

# Start Developing

# Scan devices

First you need to get a single instance of the MTModuleManager, then check the current bluetooth status of the phone, and then you can scan the device.

// Get the Manager instance
MTModuleManager mMTModuleManager=MTModuleManager.getInstance(context);

//Get the bluetooth status of the phone
BluetoothState bluetoothState = MTModuleManager.getInstance(this).checkBluetoothState();
		//response for status
        switch (bluetoothState) {
            case BluetoothStateNotSupported:
                //Not support
                break;
            case BluetoothStatePowerOff:
                //Power off
                break;
            case BluetoothStatePowerOn:
            	//Power on and start scan
            	MTModuleManager.getInstance(getContext()).startScan(mScanMTModuleCallback);
                break;
        }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# New Scan Method(20200408)

Open system ScanFilter and ScanSettings.Don't use it lightly.As follows:

    if (Build.VERSION.SDK_INT>Build.VERSION_CODES.LOLLIPOP) {
        ScanSettings scanSettings = new ScanSettings.Builder()
            .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)
            .setReportDelay(0)
            .build();
        ArrayList<ScanFilter> list = new ArrayList<>();
        list.add(new ScanFilter.Builder()
            .setServiceUuid(ParcelUuid.fromString("0000ffe1-0000-1000-8000-00805f9b34fb"))
            .build());
        list.add(new ScanFilter.Builder()
            .setManufacturerData(0x004c, new byte[]{})
            .build());
        mtModuleManager.startScan(scanMTModuleCallback, list, scanSettings);
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Please Note: only the phone bluetooth power on can the SDK works well.

# connect to the device

// get the module
MTModule mtModule = mtModules.get(position);

// listen to the changes of device connection
// ！！！writing data to device needs connected status.
MTModuleManager.getInstance(getContext()).setModuleChangeConnection(new ModuleChangeConnection() {
       @Override
       public void onDeviceChangeStatus(final MTModule device, ConnectionState status) {
           switch (status) {
               case DeviceLinkStatus_Connected:
                   break;
               case DeviceLinkStatus_ConnectFailed:
               case DeviceLinkStatus_Disconnect:
                   break;
           }
       }
   });

// connect to a module device.
MTModuleManager.getInstance(getContext()).connect(mtModule);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# Write data to device

From last step, you can write or receive data from device when the device connected to the phone.

// write data to device
// at first, make the data you want to write
// This is a 4 bytes data: 0x01,0x02,0x03,0x04.
byte[] bytes = {0x01,0x02,0x03,0x04};

// then write the bytes above to device
// you can get a writing result from the WriteCallback.
module.writeData(bytes, new WriteCallback() {
        @Override
        public void write(final boolean success, ModuleException exception) {
            if (success) {
				//write data successfully.
            } else {
				//write data failed.
            }
        }
    });

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Receiving data from device.

We don't know when the device send data, so please implementate the callback.

// the data receiving callback.
module.setMTModuleListener(new MTModuleListener() {
        @Override
        public void didReceiveData(byte[] bytes) {

        }
    });

1
2
3
4
5
6
7

# Read system infomation from device

If the firmware contains system information, you can obtain it by following methods:

// Obtain the system information corresponding to the device
HashMap<String, String> systemInfos = mMTModule.getSystemInfos();
systemInfos.get(Constants.MANUFACTURER);
systemInfos.get(Constants.MODLENUMBER);
systemInfos.get(Constants.SOFTWARE_VERSION);
systemInfos.get(Constants.HARDWARE_VERSION);
systemInfos.get(Constants.FIRMWARE_VERSION);
systemInfos.get(Constants.SERIALNUMBER);

1
2
3
4
5
6
7
8

The system information is controlled by firmware version, and the supported firmware versions are:

Firmware Verison(Verison)	Support or not
Version < 1.6.0	No
1.6.0 <= Version < 2.0.0	Yes
2.0.0 <= Version < 2.3.0	No
2.3.0 <= Version < 3.0.0	Yes
3.0.0 <= Version < 3.1.0	No
3.1.0 <= Version	Yes

# Tables

# MTModuleManager's properties

Name	Type	Description
mBluetoothState	BluetoothState	the phone's bluetooth status
scannedModules	LinkedList	the scanned devices.
connectedModules	HashMap	the connected devices.

# MTModule

Name	Type	Description
name	String	the bluetooth name
macAddress	String	the mac address
advertisingData	byte[]	the advertisement data
lastUpdate	long	last scanned timestamp
connection	ConnectionState	the connection status
rssi	int	the RSSI

# ChangeLog：

20200408 Add new scan method.
20190904 Commented code for log.
20180830 Add function for obtain system information；
20180614 First version；