From 05ac0641d0de54191adbf1de6fb710307130543b Mon Sep 17 00:00:00 2001 From: starry_lixu <2495646304@qq.com> Date: Mon, 14 Aug 2023 22:42:23 +0800 Subject: [PATCH] readme --- README | 281 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 281 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 index 0000000..d1844f7 --- /dev/null +++ b/README @@ -0,0 +1,281 @@ +智能笔SDK使用说明文档 +（P10&P20-Android 版本） +文件状态： +[ ] 草稿 +[ √ ] 正式发布 +[ ] 正在修改 文件标识： 20200425001 + 当前版本： V1.2.21 + 机密等级： 公开 + 作 者： 李秋 + 更新日期： 2021-5-7 +深圳市凝趣科技有限公司 +修订历史 +序号 版本 编写/修订说明 修订人 修订日期 备注 +1 V0.1.0 第一次建档写「新建文档」 李秋 2020-4-25 +2 V1.0.0 更新单例名 李秋 2020-5-25 +3 V1.0.3 增加获取版本信息增加对坐标最大值的计算 李秋 2020-8-7 +4 V1.0.6 补充坐标换算实际尺寸的方法 李秋 2020-8-17 +5 V1.1.0 1、 增加了对 BookNumber 的支持 +2、 调整坐标原点在左上角 +3、 对飞笔做了过滤优化 李秋 2020-8-21 +6 V1.1.3 1、更新文档,NQDot 增加 booknum 李秋 2020-9-9 +7 V1.1.7 DotType 修改为 Down、Move、Up 李秋 2020-10-10 +8 V1.1.8 支持 P20 蓝牙笔 李秋 2021-2-3 +9 V1.2.21 更新离线数据部分 李秋 2021-5-7 此版本开始，版本号为 SDK 版本 +注：版本号命名规范 +示例「V0.0.0」“主版本号.子版本号.修正版本号” +（1） 文档最初完成的版本，版本号可以为 0.1.0； +（2） 当项目在进行了局部修改或 bug 修正时，主版本号和子版本号都不变，修正版本号加 1; +（3） 当项目在原有的基础上增加了部分功能时，主版本号不变，子版本号加 1，修正版本号复位为 0； +（4） 当项目在进行了重大修改或局部修正累积较多，而导致项目整体发生全局变化时，主版本号加 1; +目 录 +一、 简介...........................................................................................................................................1 二、 开发环境准备...........................................................................................................................1 三、 集成...........................................................................................................................................1 四、 ANDROIDMANIFEST 配置.................................................................................................. 1 +五、 接口...........................................................................................................................................2 +（一） SDK 单例 NQPenSDK 提供以下功能函数方法.....................................................2 +（二） 初始化回调接口...........................................................................................................3 +（三） 扫描连接回调接口.......................................................................................................4 +（四） 实时书写数据点接收接口...........................................................................................4 +（五） 笔信息回调接口...........................................................................................................5 +（六） 离线数据回调接口.......................................................................................................6 六、 类说明.......................................................................................................................................6 +（一） 点的类型.......................................................................................................................6 +（二） 码点坐标.......................................................................................................................7 +（三） 设备...............................................................................................................................7 +1、 设备基类 NQDeviceBase..............................................................................................7 +2、 蓝牙设备.............................................................................................................................7 +3、 USB 设备............................................................................................................................9 七、 状态码.......................................................................................................................................9 （一） 连接状态码 ConnectState........................................................................................9 +（二） 错误码 ErrorCode...................................................................................................... 9 +八、 坐标转换.................................................................................................................................10 九、 常见问题.................................................................................................................................12 + +一、简介 +该使用说明文档对sdk的集成和接口功能进行简要说明。二、开发环境准备 +建议使用android studio，并下载更新android sdk到最新版。三、集成 +把aar包拷贝到app 的module下的libs目录下在app的build.gradle配置文件添加依赖 +dependencies { implementation fileTree(dir: 'libs', include: ['*.aar]) +} +四、AndroidManifest 配置 +在AndroidManifest.xml的根节点下添加以下权限 +1、 USB通信需要添加以下权限 + + + + + +2、 BLE通信需要添加以下权限 + + + + + + +3、 在内添加service声明 + + +五、接口 +（一）SDK单例 NQPenSDK提供以下功能函数方法 +调用SDK建议再封装一个单例管理类来调用SDK的功能，使用前请先调用init()初始 +如果是BLE和USB切换使用，请先release再init +化，退出时调用release()释放资源，， +记得重新添加接口监听； +函数名 参数 返回值 功能说明 +void init() Context context 上下文 +CONN_TYPE type 连接 +类型 +InitListener initListener +初始化监听 无 初始化 +CONN_TYPE +USB/BLE/SPP +(SPP 暂不支持) +void release() 无 无 释放资源，监听接口会置空，下次连接请添加接口监听 +int startScanDevice() 无 0 成功 +-1 失败 发起扫描设备 +void stopScan() 无 无 停止扫描设备 +void connect(NQDeviceBase device) device 设 备 基 类 +NQDeviceBase ，可通过 +扫描设备返回获得 无 发起连接设备 +void disconnect() 无 无 断开连接设备 +NQDeviceBase getConnectedDevice() 无 NQDeviceBa se +设备基类 获取当前连接的设备 +void setDotListener(PenDotListener listener) listener 数据点监听器 +PenDotListener 无 设置实时书写数据点监听 +void setPenConnectListener(PenConne ctListener listener) listener 连接监听器 +PenConnectListener 无 对 USB 插拔、扫描、连接进行监听 +Void setPenOfflineDataListener(PenOff lineDataListener listener) 离线数据同步回调监听器 +PenOfflineDataListener 无 +public void addPageSizeByPaperSize +(float width, float height, int bookNum, int pageFrom, int pageTo) width 毫米，纸张宽度 height 毫米，纸张高度 +bookNum 整数，页码编码 +pageFrom 整数，起始页 +pageTo 整数，截止页 无 添加 PageSize，指 定 booknum 对应的页码范围。 +该方法设置的 +是纸张的实际 +物理尺寸，单位：毫米 +public void addPageSize(int width, int height, int bookNum, int pageFrom, int pageTo) width 纸张的码点宽度 +height 纸张的码点高度 +bookNum 整数，页码编码 +pageFrom 整数，起始页 +pageTo 整数，截止页 无 添加 PageSize，指 定 booknum 对应的页码范围 +public PageSize +getPageSizeByBookNum(int bookNum) bookNum 整数，页码编码 PageSize 返回 bookNum 对 应 的 +PageSize 根 据 bookNum +获取 PageSize +public void removePageSize(int bookNum) bookNum 整数，页码编码 无 根 据 bookNum +删除 PageSize + +（二）初始化回调接口 +/** +* 初始化回调 +*/ public interface InitListener { +NQPenSDK.CONN_TYPE conn_type +void success();//初始化成功 +void failure(int error, String message);//初始化失败 +} +（三）扫描连接回调接口 +public interface PenConnectListener extends ScanListener { +/** +* 连接状态 +* @param state +*/ void onConnectState(int state); +/** +* 插入USB设备 +* @param usbDevice +*/ void onUsbDeviceAttached(UsbDevice usbDevice); +/** +* 拔出USB设备 +* @param usbDevice +*/ void onUsbDeviceDetached(UsbDevice usbDevice); +} +（四）实时书写数据点接收接口 +public interface PenDotListener { void onReceiveDot(NQDot nqDot); void onError(int error, String message); +} +（五）笔信息回调接口 +public interface PenMsgListener { +/** +* 返回固件信息 +* @param ver +*/ public void onFWVer(String ver); +/** +* 返回 MCU 信息 +* @param ver +*/ public void onMCUVer(String ver); +/** +* 返回电量信息(蓝牙笔) +* @param bat 例如 3.9v +*/  +@Override public void onBatInfo(float bat); +/** +* 返回序列号(蓝牙笔) +* @param bat 例如 3.9v +*/ @Override public void onSerialNumber(String s) { +} +} +（六）离线数据回调接口 +public interface PenOfflineDataListener { +//开始同步 离线数据数量单位：byte +void offlineDataSyncStart(long var1); +//停止同步 +void offlineDataSyncStop(); +//离线数据点 +void offlineDataDidReceivePenData(NQDot var1); +//成功删除离线数据 +void offlineDataDel(); +//离线数据数量单位： byte +void offlineDataLength(long var1); +} +六、类说明 +（一）点的类型 +public class DotType { +/** +* 落笔 +*/ +public static final int PEN_ACTION_DOWN = 0;//落笔 +/** +* 移动笔 +*/ public static final int PEN_ACTION_MOVE = 1;//移动笔 +/** +* 抬笔 +*/ public static final int PEN_ACTION_UP=2;//抬笔 +} +（二）码点坐标 +public class NQDot { +public int type;// 0 表示Down ，1表示Move , 2表示 Up public int x;//x坐标 public int y;//y坐标 public int page;//页码 public int book_width;//页面宽度最大值 public int book_height;//页面高度最大值 public long time_stamp;//时间戳，传输时的时间 public long bookNum;//Book类型 +} +（三）设备 +1、设备基类 NQDeviceBase +2、蓝牙设备 +public class NQBtDevice extends NQDeviceBase +{ +private String name; private String mac; private int rssi; @Override public String getType() { return type; } +public NQBtDevice(){ this.type = "bt"; +} +public void init(String name, String mac, int rssi){ this.name = name; this.mac = mac; this.rssi = rssi; +} +public String getName() { return name; } +public void setName(String name) { this.name = name; +} +public String getMac() { return mac; } +public void setMac(String mac) { +this.mac = mac; +} +public int getRssi() { return rssi; } +public void setRssi(int rssi) { this.rssi = rssi; +} +} +3、USB 设备 +public class NQUsbDevice extends NQDeviceBase{ +UsbDevice device; +@Override public String getType() { return this.type; +} +public UsbDevice getDevice(){ return this.device; +} +public void setDevice(UsbDevice device){ this.device = device; this.type = "usb"; +} +} +七、状态码 +（一）连接状态码ConnectState +public class ConnectState { public static final int CONN_STATE_CLOSED = 0; public static final int CONN_STATE_CONNECTING = 1; public static final int CONN_STATE_CONNECTED = 2; public static final int CONN_STATE_DISCONNECTING = 3; +} +（二）错误码ErrorCode +public class ErrorCode { public static final int SCAN_OK = 0;//正常 public static final int ERR_SCAN_ERROR = -1;//异常 public static final int ERR_INIT_ERROR = 100;//初始化异常 public static final int ERR_RESCAN_SCANNING = 101;//扫描过程中无法再次执行扫描过程 +public static final int ERR_STOP_SCAN = 102;//尝试在不扫描时取消扫描 public static final int ERR_CONTEXT_IS_NULL = 103;//context is null public static final int ERR_BT_ADAPTER_IS_NULL = 104;//bt adapter is null public static final int ERR_PERMISSION_NOT_GRANTED = 105;//动态检查是否已经 +获取定位授权 +public static final int ERR_BT_ADAPTER_TURN_OFF = 106;//蓝牙适配器没有开启 public static final int ERR_SCANNER_IS_NULL = 107;//获取的BluetoothLeScanner 为空 +public static final int ERR_SCAN_TIMEOUT_VALUE = 108;//设置的扫描超时时间无效 +public static final int ERR_USB_MANAGER_IS_NULL = 109;//UsbManager is null publicstaticfinalintERR_DEVICE_LIST_IS_NULL =110;//UsbDeviceLISTisnull public static final int ERR_USB_VID_PID_IS_ERROR = 111;//vid or pid is error publicstaticfinalintERR_USB_INTERFACE_IS_NULL=112;//usbinterfaceisnull +public static final int ERR_PARSER_DATA = 114;//码点数据异常（如页码、坐标） public static final int ERR_PARSER = 115;//码点解析异常（如传输协议解析） public static final int ERR_PAGESIZE_EMPTY = 116;//PAGESIZE IS NULL public static final int ERR_PAGESIZE_OUT_OF_RANGE = 117;//PAGE 超出 PAGESIZE +范围 +public static final int ERR_COORDINATE_EXCEPTION = 118;//coordinate exception public static final int ERR_LACK_OF_UP = 119;//last stroke lack of DotType.Up publicstaticfinalintERR_DISTANCE_TOO_LARGE=120;//thedistancebetweentow points is too large public static final int ERR_UP_DOT_PAGE = 121;//the up dot page error 抬笔点 +//的页码与上一点的页码不同 +public static final int ERR_CONN_CONNECT = 211;//连接异常 public static final int ERR_CONN_USB_GET = 212;//usb 获取连接失败 public static final int ERR_CONN_USB_OPEN = 213;//usb 打开设备失败 +八、坐标转换 +把接收到的码点坐标转换成App屏幕的像素坐标。 +数据接收回调“voidonReceiveDot(NQDotnqDot)”返回的坐标是码点上的坐标，码点坐标的原点(0, 0)在左上角。屏幕像素坐标的原点(0, 0)在左上角。 +以下是算法的伪代码： +int W2= 屏幕宽度 int H2= 屏幕高度 +int x1 = dot.x;//码点纸的x坐标 int y1 = dot.y;//码点纸的y坐标 int x2 =0;//App屏幕点的x坐标 int y2 = 0;//App屏幕点的y坐标 +int H1= dot.book_height;//当前码点纸张的宽度 int W1= dot.book_width;//当前码点纸张的高度 int page = dot.page;//当前码点纸张的页码 +float xRatio = (float) ((float) (W2) / (float) W1);//计算屏幕宽度相对码点纸 +张宽度的比例 +float yRatio = (float) ((float) (H2) / (float) H1);//计算屏幕高度相对码点纸 +张高度的比例 +X2 = (int) ((float) x 1* xRatio);//根据比例把码点的X坐标换算成屏幕X坐标 y2 = (int) ((float) y1 * yRatio);//根据比例把码点的Y坐标换算成屏幕Y坐标 +如图： + +*码点坐标值的计算方法 +1、 计算码点有多少个码点单元 +码点单元数=码点文件的宽度(毫米)/码点单元(2.032 平方毫米) +2、 码点单元数换算成整数值 +如：A4 纸宽 210 毫米 +码点单元数=210/2.032=103.34 +整个 X 或 Y 坐标数据有 12bit（整数 8bit、小数 4bit），所以 103.34 换算成整数 103 左移 4 位（103*16）+0.34*16=1648+5=1653 +3、 根据坐标值换算成实际尺寸举例： +坐标值 101，先换算成 2 进制，1100101，低 4 位表示小数值，高 8 位表示整数值，得到码点数是 6.5，而每个码点实际尺寸 2.032 毫米，所以坐标值 101 换算后 6.5*2.03 毫米=13.195 毫米。 +九、常见问题 +1、 Sdk 文件提取路径？ +demo 项目源码的 lib 文件夹 +2、 点击搜索 USB 设备返回 110 错误码可能是手机的 OTG 开关没有打开，或者是 USB 线有问题； +一般手机 OTG 打开路径：进入手机设置 -> 更多设置 -> OTG -> 开启 OTG（不同手机设置 +OTG 开关位置不一样） +3、 书写返回 115 错误码码点解析异常，请检查书写的码点文件是否正确。 +4、 蓝牙搜索不到请确认设备的蓝牙和定位是否授权并打开。 +5、 正常发送了数据，没有收到数据？ +请检查是否 release 后，重新设置了监听。