feat: 文档

md/webview-sensor.md

@@ -0,0 +1,187 @@
+# Android Web容器文档
+
+## WebView 注入对象
+
+android端在拉起web容器时，会向其js上下文中注入全局对象
+
+### app对象
+
+app对象包含几个和android互操作的封装方法，基本如下
+
+| 方法                                    | 描述                                                                               | 备注  |
+| ------------------------------------- | -------------------------------------------------------------------------------- | --- |
+| clearCache()                          | 清除本地缓存，并且刷新页面                                                                    | -   |
+| versionCode(): Int                    | 获取当前app版本号                                                                       | -   |
+| setCache(key:String, value:String)    | 设置缓存数据                                                                           | -   |
+| getCache(key) :String                 | 获取缓存数据，返回string或者null                                                            | -   |
+| offlinePage()                         | 进入离线模式页面                                                                         | -   |
+| onlinePage()                          | 进入在线模式页面                                                                         | -   |
+| fileList(dir)                         | 获取当前dir下的文件，dir可传空，返回值为多行字符串，一行代表一个文件的绝对路径                                       | -   |
+| fileWriteString(path, content, token) | 参数path路径，content为文本，token为回调标记，完成后会调用 app.onFileWrite(token, path, success, err) | -   |
+| fileReadString(path, token)           | 参数path路径，token为回调标记，完成后会调用 app.onFileRead(token, path, content)                  | -   |
+| fileDelete(path, token)               | 参数path路径，token为回调标记，完成后会调用 app.onFileDelete(token, path, success)                | -   |
+
+注意path参数，如不知道具体路径，则以 "/" 开头，目前不支持文件夹操作
+
+### net对象
+
+net包含部分网络操作封装
+
+| 方法                                          | 描述                         | 备注  |
+| ------------------------------------------- | -------------------------- | --- |
+| ping(host: String, timeoutMs: Int): Boolean | 向指定主机地址ping，不可达或超时则返回false | -   |
+
+### sensor对象
+
+sensor对象包含传感器初始化和交互的方法，已有方法如下
+
+| 方法                                                  | 描述              | 备注                                                    |
+| --------------------------------------------------- | --------------- | ----------------------------------------------------- |
+| initAll()                                           | 检测并且初始化现有的所有设备  | 当前方法会阻塞调用                                             |
+| flush()                                             | 刷新当前检测到的所有设备    | 用于USB设备插拔后，调用此方法后，应当调用sensorList()获取最新的传感器信息          |
+| sensorList():List\<Sensor>                          | 获取当前传感器列表数据     |                                                       |
+| init(id:String)                                     | 初始化指定传感器设备并获取权限 | 当前方法会阻塞调用                                             |
+| open(id:String)                                     | 打开指定传感器设备       | 开启指定传感器设备，传感器开启状态通过sensorList()获取                     |
+| close(id:String)                                    | 关闭指定传感器设备       |                                                       |
+| operation(id:String, opId:String, args:String)      | 对传感器设备进行操作      | 此方法会在sensorList()下返回对应的操作对象, id与opId用于区分传感器和操作方法      |
+| operationAsync(id:String, opId:String, args:String) | 异步对传感器设备进行操作    | 此方法调用后无返回值，而是会异步调用sensor.onOperationCallback()方法下回调参数 |
+
+### appSensor对象
+
+| 方法       | 描述                          | 备注  |
+| -------- | --------------------------- | --- |
+| open()   | 打开传感器管理器对象，尝试打开本地所有已物理连接的设备 | -   |
+| close()  | 关闭传感器管理器对象                  | -   |
+| isOpen() | 判断传感器管理器是否打开                | -   |
+
+当管理器开始工作后，会持续调用`appSensor.onValueCallback(obj)`方法，前端需要实现此方法
+
+```js
+if (appSensor != null) {
+    appSensor.onValueCallback = function(obj) {
+        console.log("obj:", obj)
+    }
+}
+```
+
+其中obj对象结构如下，其中value可能是对象类型
+
+```json
+{
+  "sensor": "HWT6053",
+  "method": "read-speed",
+  "value": "1"
+}
+```
+
+枚举上报值
+
+```kotlin
+enum class SensorMethod(
+    val sensor: Sensor,
+    val code: String,
+    val methodDesc: String
+) {
+    TOF5000_M1(Sensor.TOF5000, "read-speed", "读取速度"),
+    TOF5000_M2(Sensor.TOF5000, "read-baud-rate", "获取波特率"),
+    TOF5000_M3(Sensor.TOF5000, "read-slave-address", "获取从站地址"),
+    TOF5000_M4(Sensor.TOF5000, "read-laser-switch", "获取激光开关状态"),
+    TOF5000_M5(Sensor.TOF5000, "read-range", "获取当前距离"),
+
+    HWT6053_M1(Sensor.HWT6053, "read-version", "获取版本号"),
+    HWT6053_M2(Sensor.HWT6053, "read-temp", "获取温度"),
+    HWT6053_M3(Sensor.HWT6053, "read-euler", "获取角度"),
+    HWT6053_M4(Sensor.HWT6053, "read-heading-and-vertical", "获取朝向和垂直夹角"),
+
+    CHC_CGI_430_M1(Sensor.CHC_CGI_430, "read-rtk", "获取RTK数据"),
+
+    LOCAL_EULER_M1(Sensor.LOCAL_EULER, "euler", "获取设备欧拉角数据"),
+    LOCAL_EULER_M2(Sensor.LOCAL_EULER, "euler-filter", "获取设备滤波后欧拉角数据"),
+    LOCAL_EULER_M3(Sensor.LOCAL_EULER, "yaw", "偏航角"),
+    LOCAL_EULER_M4(Sensor.LOCAL_EULER, "magnetic", "磁场强度"),
+    LOCAL_EULER_M5(Sensor.LOCAL_EULER, "has-disturb", "是否有干扰"),
+
+    LOCAL_LOCATION_M1(Sensor.LOCAL_LOCATION, "support", "本设备是否支持"),
+    LOCAL_LOCATION_M2(Sensor.LOCAL_LOCATION, "location", "获取定位位置"),
+}
+```
+
+### appLocation对象
+
+此对象封装了获取定位经纬度的操作函数
+
+| 方法          | 描述                     | 备注                                                              |
+| ----------- | ---------------------- | --------------------------------------------------------------- |
+| isSupport() | 检查当前设备是否支持GPS定位（非基站定位） | 返回 true/false                                                   |
+| isOpen()    | 返回当前定位设备是否已打开          | 返回 true/false                                                   |
+| open()      | app侧自行申请授权并开始定位        | 此方法为异步方法，异步回调`onOpened(status)`、`onLocationChanged(location)`函数 |
+| close()     | 关闭定位                   |                                                                 |
+
+除了web调用app侧的函数，还需要web侧实现函数用于异步回调
+无特殊说明，函数均在此实例对象下，如`onOpen`函数，web侧应当如此定义
+
+```js
+if (appLocation != null) {
+    appLocation.onOpen = function(status) {
+        console.log("location device status:", status)
+    }
+}
+```
+
+| 方法                     | 描述                                                                | 备注  |
+| ---------------------- | ----------------------------------------------------------------- | --- |
+| onOpened(status)       | 当调用`open()`方法后回调，入参status可能值如下 0-开启成功 1-设备不支持GPS 2-用户拒绝授权         |     |
+| onLocationChanged(loc) | 当调用`open()`方法后回调，入参`loc`是Object类型，包含latitude，longitude，默认WGS84坐标系 |     |
+
+#### 传感器回调函数
+
+js中，在sensor对象下自行添加实现两个函数，以接收传感器插拔的回调
+
+| 方法                                    | 描述               | 备注  |
+| ------------------------------------- | ---------------- | --- |
+| onSensorAttached(id, name)            | 当传感器插入时回调        |     |
+| onSensorDetached(id, name)            | 当传感器拔出时回调        |     |
+| onOperationCallback(id, opId, result) | 异步对传感器设备进行操作后的回调 |     |
+
+## 传感器
+
+描述传感器现有提供适配的传感器驱动
+
+### HWT6053-水平传感器
+
+波特率9600，从站地址0x50
+
+| 操作                            | 描述        | 备注                              |
+| ----------------------------- | --------- | ------------------------------- |
+| $id#read-version              | 获取当前传感器版本 | -                               |
+| $id#read-temp                 | 获取设备温度    | -                               |
+| $id#read-euler                | 获取设备角度    | 返回值为包含roll,pitch,yaw三个角度的json字符 |
+| $id#reset-euler               | 重置角度传感器基准 | 返回0为成功                          |
+| $id#read-heading-and-vertical | 获取朝向和垂直夹角 | 返回0为成功                          |
+
+### TOF5000-距离传感器
+
+波特率115200，从站地址0x01
+
+| 操作             | 描述        | 备注  |
+| -------------- | --------- | --- |
+| $id#read-speed | 获取设备读取速度  | -   |
+| $id#read-range | 读取当前传感器距离 | -   |
+
+### CHC CGI-430
+
+波特率230400，无从站地址，接入设备后会以1s的间隔下发数据
+
+| 操作           | 描述            | 备注                                                 |
+| ------------ | ------------- | -------------------------------------------------- |
+| $id#read-rtk | 获取传感设备下发的定位数据 | web端调用后，会获取到设备下发的最后一条数据，数据同手册内容，但是可能会返回截断数据，需要注意处理 |
+
+## 离线交互流程
+
+1. 首次启动app后，会向`223.5.5.5`ping 并且最多等待1s
+2. ping成功进入在线页面
+3. ping不成功进入离线页面
+4. 离线页面需要在android版本发布时嵌入发布包中（后续改成在在线页面下下载？）
+5. 在线离线页面中需要对应切换页面按钮，或者使用侧滑菜单选择进入对应的在线/离线页面
+
+TODO