FeasyBlue SDK For Android

[English]

SDK资源包下载

[Download FeasyBlue_SDK_3.5.1]

SDK接入文档

对应SDK版本	编写日期	编写人员
V3.3.1	2024年4月13日	常纪刚

接入方式

解压SDK，把解压的全部文件拖到工程里。

权限申请

使用SDK必须动态获取定位权限，打开手机定位开关与手机蓝牙开关才能正常使用（Android 6.0 以上如果没有动态获取定位权限并打开手机定位开关将扫描不到BLE设备，Android 的限制）

AndroidManifest.xml 中需加入以下权限

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

// Android 12 需要以下权限
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>

// 需要导入Kotlin 协程环境
implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:$coroutines_version"

初始化

• BLE初始化

// getInstance(context)与initialize()只需要执行一次，后续其他Activity 需要使用到FscBleCentralApi的地方 直接使用 FscSppCentralApiImp.getInstance()即可
FscBleCentralApi sFscBleCentralApi = FscBleCentralApiImp.getInstance(context);
sFscBleCentralApi.initialize();

• SPP初始化

// getInstance(context)与initialize()只需要执行一次，后续其他Activity 需要使用到FscSppCentralApi的地方 直接使用 FscSppCentralApiImp.getInstance()即可
FscSppCentralApi sFscSppCentralApi = FscSppCentralApiImp.getInstance(context);
sFscSppCentralApi.initialize();

接口统计

BLE接口

/**
* 设置回调
* @param callback 回调
*/
void setCallbacks(FscBleCentralCallbacks callback);

/**
* 获取最后连接设备的mtu值
* @return mtu
*/
int getMtu();

/**
* 获取指定设备的mtu值
* param address 设备地址
* @return mtu
*/
int getMtu(String address);

/**
* 获取最后连接设备的当前每包最大发送数
* @return
*/
int getMaximumPacketByte();

/**
* 获取指定设备的当前每包最大发送数
* param address 设备地址
* @return
*/
int getMaximumPacketByte(String address);

/**
* 设置最后连接的特征数据
* @param ch            特征值
* @param properties    属性
* @return
*/
boolean setCharacteristic(BluetoothGattCharacteristic ch, int properties);

/**
* 设置指定设备的特征数据
* @param address       设备地址
* @param ch            特征值
* @param properties    属性
* @return
*/
boolean setCharacteristic(String address, BluetoothGattCharacteristic ch, int properties);

/**
* 读取指定特征值的信息
* @param address   设备地址
* @param ch        特征值
* @return
*/
boolean read(String address, BluetoothGattCharacteristic ch);

/**
* 获取指定设备的服务
* @param address   设备地址
*/
List<BluetoothGattService> getBluetoothGattServices(String address);

/**
* 设置最后连接的设备的mtu
* @param mtu       mtu值
*/
@RequiresApi(value = Build.VERSION_CODES.LOLLIPOP)
void requestMtu(int mtu);

/**
* 设置指定设备的mtu
* @param address   设备地址
* @param mtu       mtu值
*/
@RequiresApi(value = Build.VERSION_CODES.LOLLIPOP)
void requestMtu(String address, int mtu);

/**
* 绑定设备
*/
void createBond();

/**
* 检查dfu文件
* @param dfuFile dfu文件
* @return {@link DfuFileInfo}
*/
DfuFileInfo checkDfuFile(byte[] dfuFile);

SPP接口

/**
* 设置回调
* @param callback 回调
*/
void setCallbacks(FscSppCentralCallbacks callback);

/**
* 打开SDP服务，等待设备连接
*/
void openSdpService();

/**
* 关闭SDP服务，等待设备连接
*/
void closeSdpService();

/**
* 检查升级文件
* @param dfuFile   dfu文件
# @return          解析后的信息
*/
DfuFileInfo checkDfuFile(byte[] dfuFile);

公用接口

/**
* 是否显示日志
* @param isEnableLog
*/
void isShowLog(boolean isEnableLog);

/**
* 初始化
* @return {@link boolean} 初始化结果
*/
boolean initialize();

/**
* 是否已开启蓝牙
* @return {@link boolean} 蓝牙开关状态
*/
boolean isEnabled();

/**
* 删除指定设备配对记录
* @return {@link boolean} 删除是否成功
*/
boolean clearDevice(String address);

/**
* 连接
* @param address 设备地址
*/
void connect(String address);

/**
* 参数修改连接（AT指令模式）
* @param address 设备地址
*/
void connectToModify(String address);

/**
* 空中升级连接
* @param address 设备地址
* @param dfuFile 升级文件
* @param reset   是否恢复出厂设置
*/
void connectToOTAWithFactory(String address, byte[] dfuFile, boolean reset);

/**
* 断开最后连接的设备
*/
void disconnect();

/**
* 断开指定设备连接
* @param address
*/
void disconnect(String address);

/**
* 获取已绑定的设备
* @return {@link FscDevice}
*/
List<FscDevice> getBondDevices();

/**
* 开始扫描
*/
void startScan();

/**
* 停止扫描
*/
void stopScan();

/**
* 是否有设备已连接
* @return
*/
boolean isConnected();

/**
* 通过设备地址查询连接状态
* @param address 设备地址
* @return
*/
boolean isConnected(String address);

/**
* 给最后连接的设备发送数据
* @param data          发送的数据
* @param sendInterval  发送间隔
* @return
*/
boolean send(String data, Long sendInterval);

/**
* 向指定设备发送信息
* @param address       设备地址
* @param data          发送的数据
* @param sendInterval  发送间隔
* @return
*/
boolean send(String address, String data, Long sendInterval);

/**
* 给最后连接的设备发送数据
* @param packet        发送的数据
* @param sendInterval  发送间隔
* @return
*/
boolean send(byte[] packet, Long sendInterval);

/**
* 向指定设备发送信息
* @param address       设备地址
* @param data          发送的数据
* @param sendInterval  发送间隔
* @return
*/
boolean send(String address, byte[] packet, Long sendInterval);

/**
* 生成指定大小的测试文件发送给最后连接的设备
* @param size          测试文件大小
* @param sendInterval  发送间隔
* @return
*/
boolean sendFile(int size, Long sendInterval);

/**
* 生成指定大小的测试文件发送给指定设备
* @param size          测试文件大小
* @param sendInterval  发送间隔
* @return
*/
boolean sendFile(String address, int size, Long sendInterval);

/**
* 发送文件给最后连接的设备
* @param byteArray          测试文件大小
* @param sendInterval  发送间隔
* @return
*/
boolean sendFile(byte[] byteArray, Long sendInterval);

/**
* 发送文件给指定设备
* @param byteArray         测试文件大小
* @param sendInterval      发送间隔
* @return
*/
boolean sendFile(String address, byte[] byteArray, Long sendInterval);

/**
* 给最后连接的设备发送命令
* @param command   命令集合
*/
void sendATCommand(Set<String> command);

/**
* 给指定设备发送命令
* @param address   设备地址
* @param command   命令集合
*/
void sendATCommand(String address, Set<String> command);

/**
* 停止最后连接的设备发送数据
*/
void stopSend();

/**
* 停止指定设备发送数据
* @param address 设备地址
*/
void stopSend(String address);

API使用

搜索

• BLE搜索方法

FscBleCentralApi.start();

• BLE搜索例子

FscBleCentralApi sFscBleCentralApi = FscBleCentralApiImp.getInstance();
sFscBleCentralApi.setCallbacks(new FscBleCentralCallbacksImp(){
  @Override
  public void blePeripheralFound(FscDevice device, int rssi, byte[] record) {
      // 扫描到设备
  }
});
sFscBleCentralApi.startScan();

• BLE停止搜索方法

FscBleCentralApi.stopScan();

• SPP搜索方法

FscSppCentralApi.start();

• SPP搜索例子

FscSppCentralApi sFscSppCentralApi = FscSppCentralApiImp.getInstance();
sFscSppCentralApi.setCallbacks(new FscSppCentralCallbacksImp(){
  @Override
  public void sppPeripheralFound(FscDevice sppDevice, int rssi) {
      // 发现设备
  }
});
sFscSppCentralApi.startScan();

• SPP停止搜索方法

FscSppCentralApi.stopScan();

连接

• BLE连接方法

FscBleCentralApi sFscBleCentralApi = FscBleCentralApiImp.getInstance();
sFscBleCentralApi.setCallbacks(new FscBleCentralCallbacksImp(){
  @Override
  public void blePeripheralConnected(BluetoothGatt gatt, String address)  {
      // 连接成功
  }
});
sFscBleCentralApi.connect();

• SPP连接方法

FscSppCentralApi sFscSppCentralApi = FscSppCentralApiImp.getInstance();
sFscSppCentralApi.setCallbacks(new FscSppCentralCallbacksImp(){
  @Override
  public void sppPeripheralConnected(BluetoothDevice device) {
      // 连接成功
  }
});
sFscSppCentralApi.connect();

断开连接

• BLE断开连接方法

FscBleCentralApi sFscBleCentralApi = FscBleCentralApiImp.getInstance();
sFscBleCentralApi.setCallbacks(new FscBleCentralCallbacksImp(){
  @Override
  public void blePeripheralDisconnected(BluetoothGatt gatt, String address) {
      // 断开连接
  }
});
sFscBleCentralApi.disconnect();

• SPP断开连接方法

FscSppCentralApi sFscSppCentralApi = FscSppCentralApiImp.getInstance();
sFscSppCentralApi.setCallbacks(new FscSppCentralCallbacksImp(){
  @Override
  public void sppPeripheralDisconnected(String address) {
      // 断开连接
  }
});
sFscSppCentralApiImp.disconnect();

回调

• BLE回调方法

/**
* 扫描到设备
* @param device         扫描出的设备
* @param rssi             信号值
* @param scanRecord     扫描到的广播信息
*/
void blePeripheralFound(FscDevice device, int rssi, byte[] scanRecord);

/**
* 发送设备
* @param gatt        BluetoothGatt 对象
* @param address     设备地址
*/
void blePeripheralConnected(BluetoothGatt gatt, String address);

/**
* 断开连接
* @param gatt        BluetoothGatt 对象
* @param address     设备地址
*/
void blePeripheralDisconnected(BluetoothGatt gatt, String address);

/**
* 发现服务
* @param gatt        BluetoothGatt 对象
* @param address     设备地址
* @param services    服务
*/
void servicesFound(BluetoothGatt gatt, String address, List<BluetoothGattService> services);

/**
* 发现服务
* @param gatt        BluetoothGatt 对象
* @param address     设备地址
* @param service     服务
* @param characteristic 特征值
*/
void characteristicForService(BluetoothGatt gatt, String address, BluetoothGattService service, BluetoothGattCharacteristic characteristic);

/**
* 读特征值信息
* @param address     设备地址
* @param ch          特征值
* @param strValue    读到的数据
* @param hexString   读到的十六进制数据
* @param rawValue    原数据
*/
void readResponse(String address, BluetoothGattCharacteristic ch, String strValue, String hexString, byte[] rawValue);

/**
* mtu 变更
* @param mtu         请求后的mtu值
* @param status      请求mtu 的状态
*/
void bleMtuChanged(int mtu, int status);

• SPP回调方法

/**
* 扫描到设备
* @param sppDevice 设备地址
*/
void sppPeripheralFound(FscDevice sppDevice, int rssi);

/**
* 连接成功
* @param device 连接成功的设备
*/
void sppPeripheralConnected(BluetoothDevice device);

/**
* 断开连接
* @param address 设备地址
*/
void sppPeripheralDisconnected(String address);

/**
* 发送数据
* @param address       设备地址
* @param strValue      发送的数据
* @param hexString     发送的十六进制数据
* @param data          原数据
*/
void packetSend(String address, String strValue, String hexString, byte[] data);

• 相同回调方法

/**
* 开始扫描回调
*/
void startScan();

/**
* 停止扫描
*/
void stopScan();

/**
* 收到数据
* @param address 设备地址
* @param strValue 字符串
* @param dataHexString 十六进制
* @param data 源数据
*/
void packetReceived(String address, String strValue, String dataHexString, byte[] data);

/**
* 发送数据
* @param address 设备地址
* @param strValue 字符串
* @param data 源数据
*/
void packetSend(String address, String strValue, byte[] data);

/**
* 发送文件进度
* @param address 设备地址
* @param percentage 进度
* @param data 源数据
*/
void sendPacketProgress(String address, int percentage, byte[] data);

/**
* OTA 升级进度
* @param address 设备地址
* @param percentage 进度
* @param status 状态
*/
void otaProgressUpdate(String address, int percentage, int status);

/**
* AT 指令模式通讯回调
* @param command 发送的命令
* @param parameter 收到的回复
* @param type 类型
* @param status 状态
*/
void atCommandCallBack(String command, String parameter, int type, int status);

/**
* AT 指令发送结束时触发
*/
void endATCommand();

/**
* 开始发送AT指令时触发
*/
void startATCommand();

发送数据

• BLE发送数据方法

FscBleCentralApi sFscBleCentralApi = FscBleCentralApiImp.getInstance();
sFscBleCentralApiImp.send("abc");

• SPP发送数据方法

FscSppCentralApi sFscSppCentralApi = FscSppCentralApiImp.getInstance();
sFscSppCentralApiImp.send("abc");

空中升级

• BLE空中升级方法

FscBleCentralApi sFscBleCentralApi = FscBleCentralApiImp.getInstance();

sFscBleCentralApi.setCallbacks(new FscBleCentralCallbacksImp(){
  public void otaProgressUpdate(address: String, percentage: Int, status: Int) {
      // 升级进度
  }
});
sFscBleCentralApi.connectToOTAWithFactory(
                  fscDevice.getAddress(),
                  dfuByte,
                  reset
              );

• SPP空中升级方法

FscSppCentralApi sFscSppCentralApi = FscSppCentralApiImp.getInstance();
sFscSppCentralApi.setCallbacks(new FscSppCentralCallbacksImp(){
  public void otaProgressUpdate(address: String, percentage: Int, status: Int) {
      // 升级进度
  }
});
sFscSppCentralApi.connectToOTAWithFactory(
                  fscDevice.getAddress(),
                  dfuByte,
                  reset
              );

附件

下载PDF版本

下载PDF版本