## MinewESLKit Documentation

This set of SDK only supports Bluetooth ESL devices produced by Minew. 
The SDK can help developers handle all the work between the phone and ESL, including: scanning the device, connecting the device, writing data to the device, receiving data from the device, etc.


MinewESLKit can be used in `AppCompat` or` androidx` environment

### Preliminary work

Overall framework: MinewTagBleManager is a device management class, which is always a singleton when the APP is running. TagInfo is a device instance class. This suite will generate a TagInfo instance for each device, which contains device broadcast data, which will be updated as the device keeps broadcasting.

`MinewTagBleManager`: a device management class that can scan the surrounding ESL devices and connect them, verify them, etc;

`TagInfo`: device instance obtained during scanning, used during the scanning phase;

`TagModule`: It can be obtained when starting to connect. As an instance of the connected device, read and write operations will be used.

### Import to project

1. Add `MinewESLKit.jar` to the module's libs folder, and add the following statement in the` build.gradle` of the `module` (add dependencies directly):

   ```groovy
   implementation files('libs/MinewESLKit.jar')
   implementation '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.
   
   
   The project also needs to add `Java 8` support. You need to add the following configuration in build.gradle:
   
   ```groovy
   android{
       defaultConfig {
           minSdkVersion 18
           targetSdkVersion 28
       }
       
       compileOptions {
           sourceCompatibility JavaVersion.VERSION_1_8
           targetCompatibility JavaVersion.VERSION_1_8
       }
   }
   ```
   
2. The following permissions are required in `AndroidManifest.xml`. If` targetSdkVersion` is greater than 23, you need to do ** Permission Management ** to obtain permissions:

   ```xml
   <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.ACCESS_COARSE_LOCATION" />
   ```

### Start development

sdk is divided into two stages of scanning and connection.

#### Scanning

```java
//Get management class singleton
MinewTagBleManager tagBleManager = MinewTagBleManager.getInstance();

//You can set the default scan time in milliseconds before you start scanning. 
//Set the scan time to be no less than 8 seconds
tagBleManager.setDefaultScanTime(10*1000);

//Clear all previous scan results
tagBleManager.clearScanResult(10*1000);
//Start scanning and set the listener, the default scan is 10s
tagBleManager.getScanTagManager().startScan(this, new OnScanTagResultListener() {
    @Override
    public void onScanTagResult(List<TagInfo> list) {
		//Process scan results here
    }

    @Override
    public void onStopScan(List<TagInfo> list) {
		//Automatically stop scanning and return all devices acquired during the scan time
    }
});

//Or use: start scanning and set the listener, set the scan to 8 seconds, set the scan time to be not less than 8 seconds
tagBleManager.getScanTagManager().startScan(this,8000， new OnScanTagResultListener() {
    @Override
    public void onScanTagResult(List<TagInfo> list) {
		//Process scan results here
    }

    @Override
    public void onStopScan(List<TagInfo> list) {
		//Automatically stop scanning and return all devices acquired during the scan time
    }
});
```

#### Connection

The surrounding tag device can be obtained through the scanning method, and then the specified tag can be connected. Before the connection, the key must be written before the connection method can be called. Connect by calling `connect ()`.

```java
TagModule tagModule = tagBleManager.getScanTagManager().setEaxKeyByAddress(tagInfo, "3141592653589793");
//setEaxKeyByAddress() returns a TagModule instance
tagBleManager.getConnTagManager().connect(tagModule)
```

During the connection phase, including subsequent write operations, a listener needs to be set to determine the status. Brushing can be done after success, and callback notification can also be obtained here after brushing successfully.

```java
tagBleManager.getConnTagManager().setOnConnStateListener(new OnConnStateListener() {
    @Override
    public void onUpdateConnState(String s, ConnectionState connectionState) {
        switch (connectionState) {
            case Connecting:
               //Start to connect
                break;
            case Connect_Complete:
                // Authentication is successful, at this time, the connection is considered successful
                break;
            case BRUSH_IMAGE:
               // Called after successful drawing, the connection will be disconnected
                break;
            case Disconnect:
                //Disconnect
            default:
                break;
        }
    }
});
```

#### Brush

After the connection is successful, you can go to brush. First you need to get the image data written into the tag. Due to the limitation of the Bluetooth data transmission length, if it exceeds the limit, it will be subcontracted and then sent in turn.

```java
//The screen information is stored in the DeviceStaticInfoFrame class
DeviceStaticInfoFrame frame = (DeviceStaticInfoFrame) tagModule.getMinewFrame(FrameType.DEVICE_STATIC_INFO_FRAME);
//Remove the screen information, and then get the brush data according to the screen information
String screenInfo = frame.getScreenInfo();
tagBleManager.sendImageData(macAddress, imageBytes, new OnWriteLargeDataListener() {
    
    /**
     * Update write progress
     *
     * @param index Current number written
     * @param total The total number of writes
     */
    @Override
    public void onWriteUpdate(int index, int total) {
        Log.e("tetetetete", "sendImageData " + index + " " + total);
    }

    /**
     * Write successfully
     */
    @Override
    public void onWriteSuccess() {

    }

    /**
     * Write failed. 
     * reason has little effect and is only used to troubleshoot the cause of failure
     */
    @Override
    public void onWriteFailed(int i) {

    }
});
```

**Note: After the drawing is successful, the SDK will actively disconnect and the Disconnect status will not be returned in the OnConnStateListener callback! **

### Property description

1. `DeviceStaticInfoFrame` is a static information frame of the device. In this information frame, screenInfo is one of the most important information. Only by matching the brush data obtained through screenInfo, can the brush be successful.

   | Name            | Type   | Description          |
   | --------------- | ------ | -------------------- |
   | firmwareVersion | String | Firmware version     |
   | hardwareVersion | String | hardware information |
   | screenInfo      | String | Screen information   |
   | chipInfo        | String | Chip model           |

2. `DeviceRunInfoFrame`, Device run information frame

   | Name           | Type   | Description      |
   | -------------- | ------ | ---------------- |
   | batteryVoltage | int    | 设备的电压       |
   | imageId        | String | 设备的刷图数据ID |

## Update history

### V1.0.0 2020/03/10

Add documents.

### V1.0.1 2020/07/01 

1. Method changes. 
   The methods `getScanTagManager()` and `getConnTagManager()` of the `MinewTagBleManager` class are `@Deprecated`. Previously, these two methods were needed to obtain the specified object and use it to complete the writing of data, etc., which can now be done directly, such as:

2. ```java
   tagBleManager.getScanTagManager().startScan();
   //Will be replaced with:
   tagBleManager.startScan();
   
   tagBleManager.getConnTagManager().sendImageData();
   //Will be replaced with:
   tagBleManager.sendImageData();
   ```

   But through `tagBleManager.getScanTagManager().startScan();` and other methods are still valid, we recommend directly calling `startScan()` and other methods.

3. Improve the drawing callback. Two methods are added to the `OnWriteLargeDataListener()` interface. As follows: 

   ```java
   public interface OnWriteLargeDataListener {
   
       /**
        * Update write progress
        *
        * @param index Current number written
        * @param total The total number of writes
        */
       void onWriteUpdate(int index, int total);
   
       /**
        * Write successfully
        */
       void onWriteSuccess();
   
       /**
        * Write failed. 
        * reason has little effect and is only used to troubleshoot the cause of failure
        */
       /**
        * Write failed. 
        * reason has little effect and is only used to troubleshoot the cause of failure.
        * If the writing fails, the connection will be disconnected, and the Disconnect state will be returned through OnConnStateListener
        */
       void onWriteFailed(int reason);
   }
   ```

3. In the flashing scene, `onWriteSuccess` will be executed first and then the `BRUSH_IMAGE` status will be returned via `OnConnStateListener`; after the write is added, the connection will be disconnected, and the `onWriteFailed` will be used to notify the flashing failure and disconnect. 
4. Add a Property description to add some descriptions of broadcast frame attributes.

See the documentation for details.