From 6aad2fe7a9c810a4318b4dcf80b42c43fbeb8898 Mon Sep 17 00:00:00 2001 From: pw <329803553@qq.com> Date: Sat, 2 May 2020 16:43:42 +0800 Subject: [PATCH] update readme --- README.md | 88 ++++++++++++------- README_CN.md | 71 ++++++++++----- .../java/com/ficat/easyble/BleManager.java | 10 +-- 3 files changed, 107 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index 656ad61..20ebf06 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ allprojects { } dependencies { - implementation 'com.github.Ficat:EasyBle:v1.0.4' + implementation 'com.github.Ficat:EasyBle:v2.0.1' } ``` @@ -37,25 +37,28 @@ If you want to turn on bluetooth, I strongly recommend you call enableBluetooth( ``` ### Step -### 1.Get ble manager +### 1.Get ble manager and initialization ```java - //Get ble manager - BleManager bleManager = BleManager.getInstance(this.getApplication()); - - //Set options, you can call this method many times, this framework will use - //the newest options. For example,you have set scan period(like 10s), but next - //scan you wanna scan period longer(like 15s), so you can call this method again - //to set scan period is 15s - BleManager.Options options = new BleManager.Options(); - options.loggable = true; //does it print log? - options.connectTimeout = 10000; //connection time out - options.scanPeriod = 12000; //scan period - options.scanDeviceName = "deviceName"; - options.scanDeviceAddress = "deviceAddress";//like "DD:0D:30:00:0D:9B" - options.scanServiceUuids = serviceUuidArray; - bleManager.option(options); + //scan/connection options is not necessary, if you don't set, + //it will use default config + BleManager.ScanOptions scanOptions = BleManager.ScanOptions + .newInstance() + .scanPeriod(10000) + .scanDeviceName(null); + + BleManager.ConnectOptions connectOptions = BleManager.ConnectOptions + .newInstance() + .connectTimeout(12000); + + + BleManager bleManager = BleManager + .getInstance() + .setScanOptions(scanOptions)//it is not necessary + .setConnectionOptions(connectOptions)//like scan options + .setLog(true, "TAG") + .init(this.getApplication());//Context is needed here,do not use Activity,which can cause Activity leak ``` @@ -85,6 +88,9 @@ If sdk version >=23, scanning ble must have location permissions } }); + //start scan with specified scanOptions + bleManager.startScan(scanOptions, bleScanCallback); + ``` Once target remote device has been discovered you can use stopScan() to stop scanning @@ -108,26 +114,34 @@ You can connect to remote device by device address or BleDevice object } @Override - public void onTimeout(BleDevice device) { + public void onFailure(int failCode, String info, BleDevice device) { + if(failCode == BleConnectCallback.FAIL_CONNECT_TIMEOUT){ + //connection timeout + }else{ + //connection fail due to other reasons + } } - @Override - public void onConnected(BleDevice device) { + @Override + public void onConnected(BleDevice device) { - } + } - @Override - public void onDisconnected(BleDevice device) { + @Override + public void onDisconnected(String info, int status, BleDevice device) { - } + } }; - //connect to the remote device by BleDevice object bleManager.connect(bleDevice, bleConnectCallback); + //connect with specified connectOptions + bleManager.connect(bleDevice, connectOptions, bleConnectCallback); + + //connect with mac address + bleManager.connect(address, bleConnectCallback); + bleManager.connect(address, connectOptions, bleConnectCallback); - //connect to the remote device by address - bleManager.connect(address, bleConnectCallback) ``` Use one of the following methods to disconnect from remote device @@ -139,13 +153,13 @@ Use one of the following methods to disconnect from remote device //disconnect from the specific remote device by address bleManager.disconnect(address); - //disconenct all connected devices + //disconnect all connected devices bleManager.disconnectAll(); ``` ### 4.Notify -Both notification and indication use the following method to set notfication or indication +Both notification and indication use the following method to set notification or indication ```java bleManager.notify(bleDevice, serviceUuid, notifyUuid, new BleNotifyCallback() { @Override @@ -159,8 +173,16 @@ Both notification and indication use the following method to set notfication or } @Override - public void onFail(int failCode, String info, BleDevice device) { - + public void onFailure(int failCode, String info, BleDevice device) { + switch (failCode) { + case BleCallback.FAIL_DISCONNECTED://connection has disconnected + break; + case BleCallback.FAIL_OTHER://other reason + break; + default: + break; + } + } }); ``` @@ -178,7 +200,7 @@ When you want to cancel notification or indication, you can call cancelNotify() } @Override - public void onFail(int failCode, String info, BleDevice device) { + public void onFailure(int failCode, String info, BleDevice device) { } }); @@ -193,7 +215,7 @@ if the length of the data you wanna deliver to remote device is larger than MTU( } @Override - public void onFail(int failCode, String info, BleDevice device) { + public void onFailure(int failCode, String info, BleDevice device) { } }); diff --git a/README_CN.md b/README_CN.md index 4853cd7..fca5620 100644 --- a/README_CN.md +++ b/README_CN.md @@ -11,7 +11,7 @@ allprojects { dependencies { - implementation 'com.github.Ficat:EasyBle:v1.0.4' + implementation 'com.github.Ficat:EasyBle:v2.0.1' } ``` @@ -34,23 +34,28 @@ dependencies { ### 步骤如下 -### 1.获取BleManager对象 +### 1.获取BleManager对象并初始化 ```java - //获取管理器对象 - BleManager bleManager = BleManager.getInstance(this.getApplication()); - - //设置ble选项，可多次设置,EasyBle将使用最新的options。比如本次扫描周期 - //为10s，但你想要下一次扫描周期更长一些，则再次调用本方法去设置即可 - BleManager.Options options = new BleManager.Options(); - options.loggable = true; //是否打印日志 - options.connectTimeout = 10000; //连接超时时间 - options.scanPeriod = 12000; //扫描周期 - options.scanDeviceName = "targetDeviceName"; //扫描的目标设备名 - options.scanDeviceAddress = "targetDeviceAddress"; //扫描目标设备地址如"DD:0D:30:00:0D:9B" - options.scanServiceUuids = serviceUuidArray; //扫描含该服务UUID的目标设备 - bleManager.option(options); + // scan/connection不是必须的，若不设置，那么扫描或连接就 + // 会使用默认参数 + BleManager.ScanOptions scanOptions = BleManager.ScanOptions + .newInstance() + .scanPeriod(10000) + .scanDeviceName(null); + + BleManager.ConnectOptions connectOptions = BleManager.ConnectOptions + .newInstance() + .connectTimeout(12000); + + + BleManager manager = BleManager + .getInstance() + .setScanOptions(scanOptions)//非必须设置项 + .setConnectionOptions(connectOptions) + .setLog(true, "TAG") + .init(this.getApplication());//这里需要Context，但注意不要传Activity ``` @@ -80,6 +85,8 @@ dependencies { } }); + //使用指定扫描参数扫描 + bleManager.startScan(scanOptions, bleScanCallback); ``` 当需要结束扫描时用以下方法结束扫描，建议在扫描到目标设备后停止扫描 ```java @@ -102,7 +109,12 @@ dependencies { } @Override - public void onTimeout(BleDevice device) { + public void onFailure(int failCode, String info, BleDevice device) { + if(failCode == BleConnectCallback.FAIL_CONNECT_TIMEOUT){ + //连接超时 + }else{ + //其他原因导致的连接失败 + } } @@ -112,16 +124,19 @@ dependencies { } @Override - public void onDisconnected(BleDevice device) { + public void onDisconnected(String info, int status, BleDevice device) { } }; - //通过BleDevice对象连接设备 bleManager.connect(bleDevice, bleConnectCallback); + //使用指定连接选项参数进行连接 + bleManager.connect(bleDevice, connectOptions, bleConnectCallback); + + //使用mac地址连接 + bleManager.connect(address, bleConnectCallback); + bleManager.connect(address, connectOptions, bleConnectCallback); - //直接通过mac地址连接 - bleManager.connect(address, bleConnectCallback) ``` 当需要断开与设备的连接时可使用以下任一方法断开设备连接 @@ -152,8 +167,16 @@ notify和indicate都使用以下方法 } @Override - public void onFail(int failCode, String info, BleDevice device) { - + public void onFailure(int failCode, String info, BleDevice device) { + switch (failCode) { + case BleCallback.FAIL_DISCONNECTED://连接断开 + break; + case BleCallback.FAIL_OTHER://其他原因 + break; + default: + break; + } + } }); ``` @@ -171,7 +194,7 @@ notify和indicate都使用以下方法 } @Override - public void onFail(int failCode, String info, BleDevice device) { + public void onFailure(int failCode, String info, BleDevice device) { } }); @@ -185,7 +208,7 @@ notify和indicate都使用以下方法 } @Override - public void onFail(int failCode, String info, BleDevice device) { + public void onFailure(int failCode, String info, BleDevice device) { } }); diff --git a/easyble/src/main/java/com/ficat/easyble/BleManager.java b/easyble/src/main/java/com/ficat/easyble/BleManager.java index 8642b73..ded7183 100644 --- a/easyble/src/main/java/com/ficat/easyble/BleManager.java +++ b/easyble/src/main/java/com/ficat/easyble/BleManager.java @@ -461,10 +461,10 @@ private BleDevice newBleDevice(BluetoothDevice device) { } public static final class ScanOptions { - public int scanPeriod = 12000; - public String scanDeviceName; - public String scanDeviceAddress; - public UUID[] scanServiceUuids; + private int scanPeriod = 12000; + private String scanDeviceName; + private String scanDeviceAddress; + private UUID[] scanServiceUuids; private ScanOptions() { @@ -500,7 +500,7 @@ public ScanOptions scanServiceUuids(UUID[] serviceUuids) { } public static final class ConnectOptions { - public int connectTimeout = 10000; + private int connectTimeout = 10000; private ConnectOptions() {