Update readme

Ficat · Jan 22, 2025 · 36cff52 · 36cff52
1 parent 6939a63
commit 36cff52
Show file tree

Hide file tree

Showing 5 changed files with 76 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
   EasyBle is a framework used for android BLE, this framework makes android Ble operation simpler and supports basic BLE operations, besides, it also support batch writing data and multi connection
 >The version 1.0.x is no longer maintained , please use or update to the newest version(2.0.x)
 
-[中文文档](README_CN.md)
+[中文文档](doc/README_CN.md)
 
 ## Gradle dependency
 ```gradle
@@ -19,7 +19,8 @@ dependencies {
 
 ## Usage
  The framework uses BleManager to manager BLE
-### 1.Check if the device supports BLE, request BLE required permissions and turn on bluetooth
+### 1.Check if the device supports BLE, request BLE required permissions and turn on bluetooth. <br>
+[See BLE permission details](doc/README_MORE.md)
 ```java
         // Check if the device supports BLE
         BleManager.supportBle(context);
@@ -70,7 +71,8 @@ dependencies {
 ```
 
 ### 3.Scan
-On API23+ or higher devices, scan requires some permissions, so ensure all BLE permissions have been granted
+On API23+ or higher devices, scan requires some permissions, so ensure all BLE permissions have been granted. <br>
+[How to use BleDevice to carry extra info](doc/README_MORE.md).
 ```java
         bleManager.startScan(new BleScanCallback() {
             @Override
@@ -106,7 +108,8 @@ Once target remote device has been discovered you can use stopScan() to stop sca
 ```
 
 ### 4.Connect
-You can connect to remote device by device address or BleDevice object. Like scan, now connection also requires permissions.
+You can connect to remote device by device address or BleDevice object. Like scan, now connection also requires permissions.<br>
+ By default, all operation(like connect/notify/read/write/setMtu/readRssi and so on) callbacks run in UI-Thread, but you can select a thread to run them[How to select a thread to run all operation callbacks](doc/README_MORE.md).
 ```java
 
        BleConnectCallback bleConnectCallback = new BleConnectCallback() {

diff --git a/README_CN.md → doc/README_CN.md b/README_CN.md → doc/README_CN.md
@@ -17,7 +17,9 @@ dependencies {
 
 ## Usage
  本库主要通过BleManager类来进行BLE操作
-### 1.判断设备是否支持BLE并打开蓝牙
+### 1.判断设备是否支持BLE并打开蓝牙.
+<br>
+[查看蓝牙所需权限详情](doc/README_MORE_CN.md)
 ```java
         // 是否支持BLE
         BleManager.supportBle(context);
@@ -65,7 +67,8 @@ dependencies {
 ```
 
 ### 3.扫描
-安卓版本不小于6.0的，扫描需要BLE权限，因此扫描前确保所有BLE权限已被授予
+安卓版本不小于6.0的，扫描需要BLE权限，因此扫描前确保所有BLE权限已被授予.<br>
+ [如何使用BleDevice存储或携带额外信息](doc/README_MORE_CN.md).
 ```java
         bleManager.startScan(new BleScanCallback() {
             @Override
@@ -99,7 +102,8 @@ dependencies {
 ```
 
 ### 4.连接
-
+ 你可以使用BleDevice对象或mac地址连接设备<br>
+ 默认情况下，所有操作回调（connect/notify/read/write/readRssi/setMtu等等）都将运行在主线程， 当然你可以选择其运行在子线程[如何选择一个线程来运行所有出扫描外的回调](doc/README_MORE_CN.md).
 ```java
 
        BleConnectCallback bleConnectCallback = new BleConnectCallback() {

diff --git a/README_MORE.md → doc/README_MORE.md b/README_MORE.md → doc/README_MORE.md
@@ -3,18 +3,18 @@
 |------|-----------|
 |API31+|*"android.permission.BLUETOOTH_SCAN"*<br>*"android.permission.BLUETOOTH_CONNECT"*<br>*"android.permission.BLUETOOTH_ADVERTISE"*|
 |API29+|*"android.permission.ACCESS_FINE_LOCATION"*|
-|API23+|*"android.permission.ACCESS_FINE_LOCATION"* or <br>*"android.permission.ACCESS_FINE_LOCATION"*|
+|API23+|*"android.permission.ACCESS_COARSE_LOCATION"* or <br>*"android.permission.ACCESS_FINE_LOCATION"*|
 |API22-| None|
 
-### 2.How to use BleDevice to save extra info
+### 2.How to use BleDevice to carry or save extra info
 ```java
        // If you want to save any extra info to BleDevice, you can do like the following.
        // 1. First, create a class used to save extra info, whatever any name and members
-       //    attribute, but make sure it implements the interface 'Parcelable'
+       //    attribute, but note that it must implement the interface 'Parcelable'
        // 2. Then, create an instance and put info you wanna save into it
        // 3. Finally, call BleDevice#setParcelableExtra()
 
-       // For example, create a class named ExtraInfo, it has implements the interface 'Parcelable'
+       // For example, create a class named ExtraInfo, it has implemented the interface 'Parcelable'
        // and contains three members( String note, int rssi, byte[] scanRecordBytes), we save info
        // like the following
        String strInfo = "this is string info";
@@ -31,4 +31,15 @@
        if (p instanceof ExtraInfo) {
            ExtraInfo e = (ExtraInfo) p;
        }
+```
+
+### 3.How to select a thread to run all operation callbacks(except BleScanCallback， like connect/notify/read/write and so on)
+```java
+       // After creating a BleHandlerThread instance, you can or not call BleHandlerThread#start(),
+       // if you don't call it, it will be called automatically. When disconnected or failed to
+       // connect, BleHandlerThread#quitLooperSafely() will also be called automatically. You don't
+       // have to call other methods(like #getLooper(), #quit(), #or quitSafety()), they all have
+       // been deprecated in BleHandlerThread, and they will not work even if you have called them.
+       // You just need to create a instance and add it to specified position of BleManager#connect()
+       BleManager.getInstance().connect(device.getAddress(), connectCallback, new BleHandlerThread("BleThread"));
 ```
diff --git a/doc/README_MORE_CN.md b/doc/README_MORE_CN.md
@@ -0,0 +1,40 @@
+### 1. 关于BLE所需权限情况
+|API版本|所需权限|
+|------|-----------|
+|API31+|*"android.permission.BLUETOOTH_SCAN"*<br>*"android.permission.BLUETOOTH_CONNECT"*<br>*"android.permission.BLUETOOTH_ADVERTISE"*|
+|API29+|*"android.permission.ACCESS_FINE_LOCATION"*|
+|API23+|*"android.permission.ACCESS_COARSE_LOCATION"* 或 <br>*"android.permission.ACCESS_FINE_LOCATION"*|
+|API22-| None|
+
+### 2.如何使用BleDevice携带一些额外信息（即BleDevice中）
+```java
+       // 若你想在BleDevice存储一些额外信息，可以按以下步骤来
+       // 1. 首先，创建一个用于存储额外信息的类，无论类名以及任何成员都可以，只要该类实现了Parcelable接口
+       // 2. 其次，创建一个该额外信息类的实例，并且将信息传入进去
+       // 3. 最后，调用BleDevice#setParcelableExtra()然后将该实例传进去即可
+       // 例如，我们建一个名叫ExtraInfo的类，该类已实现Parcelable接口，并且该类包含三个成员
+       // ( String note, int rssi, byte[] scanRecordBytes)， 然后我们可以按以下代码处理即可
+       String strInfo = "this is string info";
+       byte[] bytes = new byte[2];
+       int rssi = -50;
+       ExtraInfo extra = new ExtraInfo();
+       extra.setNote(strInfo);
+       extra.setRssi(rssi);
+       extra.setScanRecordBytes(bytes);
+       bleDevice.setParcelableExtra(extra);
+
+       // 从BleDevice对象中获取该额外信息
+       Parcelable p = bleDevice.getParcelableExtra();
+       if (p instanceof ExtraInfo) {
+           ExtraInfo e = (ExtraInfo) p;
+       }
+```
+
+### 3.如何选择一个线程来运行除BleScanCallback外的所有操作（如connect/notify/read/write等）的Callback
+```java
+       // 在创建一个BleHandlerThread对象后，你可以选择调用或不调用BleHandlerThread#start()。若你不调用，则该方法
+       // 会被自动调用。 在连接失败或连接断开后，BleHandlerThread#quitLooperSafely()也会被自动调用。所以你不必
+       // 调用其他方法(如#getLooper()、#quit()或quitSafety())去停止线程，这些方法在BleHandlerThread都已被废弃
+       // 即使你调用了它们也不产生效果，因此你只需要创建一个BleHandlerThread对象然后传到BleManager#connect()即可
+       BleManager.getInstance().connect(device.getAddress(), connectCallback, new BleHandlerThread("BleThread"));
+```
diff --git a/sample/src/main/java/com/ficat/sample/OperateActivity.java b/sample/src/main/java/com/ficat/sample/OperateActivity.java
@@ -205,7 +205,13 @@ public void onClick(View v) {
             // Select a specified connection option
 //            BleManager.getInstance().connect(device.getAddress(), BleManager.ConnectionOptions.newInstance(), connectCallback);
 
-            // Select a thread to run all operation callbacks, like connect/notify/read/write and so on
+            // Select a thread to run all operation callbacks, like connect/notify/read/write and so on.
+            // After creating a BleHandlerThread instance, you can or not call BleHandlerThread#start(),
+            // if you don't call it, it will be called automatically. When disconnected or failed to
+            // connect, BleHandlerThread#quitLooperSafely() will also be called automatically. You don't
+            // have to call other methods(like #getLooper(), #quit(), #or quitSafety()), they all have
+            // been deprecated in BleHandlerThread, and they will not work even if you have called them.
+            // You just need to create a instance and add it to specified position of BleManager#connect()
 //            BleManager.getInstance().connect(device.getAddress(), connectCallback, new BleHandlerThread("BleThread"));
             return;
         } else if (v.getId() == R.id.tv_disconnect) {