577 lines
8.5 KiB
Markdown
577 lines
8.5 KiB
Markdown
# 传感器接入待开发方案
|
||
> 文档版本：v1.0
|
||
> 最后更新：2026-04-02 08:28:05
|
||
|
||
|
||
本文档用于整理当前项目后续可利用的传感器能力，分为：
|
||
|
||
- 微信小程序能力边界
|
||
- 原生 Flutter App 能力边界
|
||
- 两端统一的抽象建议
|
||
- 推荐落地顺序
|
||
|
||
目标不是一次性接入所有传感器，而是优先接入对当前地图玩法、自动转图、运动状态识别、HUD/反馈最有价值的能力。
|
||
|
||
---
|
||
|
||
## 1. 总体原则
|
||
|
||
传感器接入必须遵守以下原则：
|
||
|
||
- 原始传感器数据只放在 `engine/sensor`
|
||
- 融合后的高级状态放在 `telemetry`
|
||
- 地图引擎只消费“对地图有意义的结果”
|
||
- 规则引擎只在玩法确实需要时消费高级状态
|
||
- 不要把原始三轴值直接喂给地图或玩法逻辑
|
||
|
||
推荐统一产出的高级状态包括：
|
||
|
||
- `movementState`
|
||
- `headingSource`
|
||
- `devicePose`
|
||
- `headingConfidence`
|
||
- `cadenceSpm`
|
||
- `motionIntensity`
|
||
|
||
---
|
||
|
||
## 2. 微信小程序可用传感器
|
||
|
||
### 2.1 当前确认可用
|
||
|
||
基于微信小程序官方 API 与项目内 typings，当前可直接使用的能力包括：
|
||
|
||
- `Location`
|
||
- `wx.startLocationUpdate`
|
||
- `wx.startLocationUpdateBackground`
|
||
- `wx.onLocationChange`
|
||
- `Accelerometer`
|
||
- `wx.startAccelerometer`
|
||
- `wx.onAccelerometerChange`
|
||
- `Compass`
|
||
- `wx.startCompass`
|
||
- `wx.onCompassChange`
|
||
- `DeviceMotion`
|
||
- `wx.startDeviceMotionListening`
|
||
- `wx.onDeviceMotionChange`
|
||
- `Gyroscope`
|
||
- `wx.startGyroscope`
|
||
- `wx.onGyroscopeChange`
|
||
- `WeRunData`
|
||
- `wx.getWeRunData`
|
||
|
||
### 2.2 当前确认不可直接获得的原始能力
|
||
|
||
微信小程序没有直接开放以下原始传感器接口：
|
||
|
||
- `Gravity`
|
||
- `Linear Acceleration`
|
||
- `Rotation Vector`
|
||
- `Geomagnetic Field` 原始三轴
|
||
- `Proximity`
|
||
- 原始 `Step Counter`
|
||
|
||
说明：
|
||
|
||
- `wx.getWeRunData` 不是实时步数传感器流
|
||
- 它更适合中长期统计，不适合实时地图玩法
|
||
|
||
---
|
||
|
||
## 3. 微信小程序推荐应用方案
|
||
|
||
### 3.1 第一优先级
|
||
|
||
#### A. Gyroscope
|
||
|
||
用途：
|
||
|
||
- 提升自动转图平滑度
|
||
- 降低跑步中手机晃动导致的朝向抖动
|
||
- 增强指北针和地图旋转过渡体验
|
||
|
||
推荐产出：
|
||
|
||
- `turnRate`
|
||
- `headingSmoothFactor`
|
||
- `headingStability`
|
||
|
||
#### B. DeviceMotion
|
||
|
||
用途：
|
||
|
||
- 识别手机姿态
|
||
- 判断设备是竖持、倾斜还是接近平放
|
||
- 配合 gyro 增强朝向可信度
|
||
|
||
推荐产出：
|
||
|
||
- `devicePose`
|
||
- `orientationConfidence`
|
||
- `tiltState`
|
||
|
||
#### C. Compass
|
||
|
||
用途：
|
||
|
||
- 静止或低速时，作为持机朝向基准
|
||
- 指北针展示
|
||
|
||
推荐角色：
|
||
|
||
- 继续保留
|
||
- 作为“静止朝向输入”
|
||
- 不再单独承担跑动中的全部朝向逻辑
|
||
|
||
### 3.2 第二优先级
|
||
|
||
#### D. Accelerometer
|
||
|
||
用途：
|
||
|
||
- 辅助识别是否真的在移动
|
||
- 识别急停、抖动、运动强度变化
|
||
|
||
推荐产出：
|
||
|
||
- `motionIntensity`
|
||
- `movementConfidence`
|
||
|
||
说明：
|
||
|
||
- 不建议直接用原始加速度驱动地图行为
|
||
- 应和 GPS、gyro 一起融合使用
|
||
|
||
#### E. Location
|
||
|
||
用途：
|
||
|
||
- 当前定位
|
||
- 轨迹
|
||
- 目标距离
|
||
- movement heading
|
||
- 速度估计
|
||
|
||
推荐角色：
|
||
|
||
- 继续作为地图和玩法核心输入
|
||
- 后续更多与 gyro / accelerometer 配合使用
|
||
|
||
### 3.3 当前不建议优先投入
|
||
|
||
#### F. WeRunData
|
||
|
||
用途：
|
||
|
||
- 日级步数统计
|
||
- 长周期运动数据
|
||
|
||
当前不建议投入原因：
|
||
|
||
- 不是实时传感器
|
||
- 不适合当前地图实时玩法主链
|
||
|
||
---
|
||
|
||
## 4. 微信小程序推荐先产出的高级状态
|
||
|
||
### A. movementState
|
||
|
||
建议值：
|
||
|
||
- `idle`
|
||
- `walk`
|
||
- `run`
|
||
|
||
来源：
|
||
|
||
- GPS 速度
|
||
- accelerometer
|
||
- device motion
|
||
|
||
### B. headingSource
|
||
|
||
建议值：
|
||
|
||
- `sensor`
|
||
- `blended`
|
||
- `movement`
|
||
|
||
来源：
|
||
|
||
- compass
|
||
- gyroscope
|
||
- GPS track
|
||
|
||
### C. devicePose
|
||
|
||
建议值：
|
||
|
||
- `upright`
|
||
- `tilted`
|
||
- `flat`
|
||
|
||
来源：
|
||
|
||
- device motion
|
||
- gyroscope
|
||
|
||
### D. headingConfidence
|
||
|
||
建议值：
|
||
|
||
- `low`
|
||
- `medium`
|
||
- `high`
|
||
|
||
来源：
|
||
|
||
- compass
|
||
- gyroscope
|
||
- GPS 精度
|
||
- movement heading 是否可靠
|
||
|
||
---
|
||
|
||
## 5. 原生 Flutter App 可用传感器
|
||
|
||
原生 Flutter App 的能力边界明显更强，后续如果迁移或并行开发，可直接利用系统原始传感器。
|
||
|
||
### 5.1 可考虑直接接入
|
||
|
||
- `Location / GNSS`
|
||
- `Compass / Magnetometer`
|
||
- `Gyroscope`
|
||
- `Accelerometer`
|
||
- `Linear Acceleration`
|
||
- `Gravity`
|
||
- `Rotation Vector`
|
||
- `Step Counter / Pedometer`
|
||
- `Barometer`（如设备支持）
|
||
- `Proximity`（视玩法需求）
|
||
|
||
说明：
|
||
|
||
- Flutter 本身一般通过插件获取这些能力
|
||
- 具体以 Android / iOS 可用性差异为准
|
||
|
||
### 5.2 Flutter 相对小程序的主要优势
|
||
|
||
- 能直接拿到更完整的原始传感器矩阵
|
||
- 更适合做高质量姿态融合
|
||
- 更适合做步数、步频、跑动状态识别
|
||
- 可更深度控制后台行为和采样频率
|
||
|
||
---
|
||
|
||
## 6. Flutter 推荐应用方案
|
||
|
||
### 6.1 第一优先级
|
||
|
||
#### A. Rotation Vector
|
||
|
||
用途：
|
||
|
||
- 作为地图自动转图的高质量姿态输入
|
||
- 优于单纯磁力计 + 罗盘
|
||
|
||
推荐产出：
|
||
|
||
- `deviceHeadingDeg`
|
||
- `devicePose`
|
||
- `headingConfidence`
|
||
|
||
#### B. Gyroscope
|
||
|
||
用途：
|
||
|
||
- 旋转平滑
|
||
- 快速转身检测
|
||
- 姿态短时补偿
|
||
|
||
#### C. Linear Acceleration
|
||
|
||
用途：
|
||
|
||
- 识别运动状态
|
||
- 急停、冲刺、抖动判定
|
||
|
||
推荐产出：
|
||
|
||
- `motionIntensity`
|
||
- `movementState`
|
||
|
||
#### D. Step Counter
|
||
|
||
用途：
|
||
|
||
- 实时步数
|
||
- 步频
|
||
- 跑步状态识别
|
||
- 训练/卡路里模型增强
|
||
|
||
推荐产出：
|
||
|
||
- `stepCount`
|
||
- `cadenceSpm`
|
||
- `movementState`
|
||
|
||
### 6.2 第二优先级
|
||
|
||
#### E. Gravity
|
||
|
||
用途：
|
||
|
||
- 持机姿态识别
|
||
- 平放/竖持策略切换
|
||
|
||
#### F. Magnetometer
|
||
|
||
用途：
|
||
|
||
- 作为姿态融合底层输入
|
||
|
||
建议：
|
||
|
||
- 不建议单独直接映射到业务逻辑
|
||
- 主要与 rotation vector / gyro 融合
|
||
|
||
#### G. Barometer
|
||
|
||
用途：
|
||
|
||
- 海拔变化
|
||
- 爬升检测
|
||
|
||
适合：
|
||
|
||
- 户外定向训练
|
||
- 赛后统计
|
||
|
||
---
|
||
|
||
## 7. Flutter 推荐先产出的高级状态
|
||
|
||
### A. movementState
|
||
|
||
建议值：
|
||
|
||
- `idle`
|
||
- `walk`
|
||
- `run`
|
||
- `sprint`
|
||
|
||
来源：
|
||
|
||
- GPS
|
||
- step counter
|
||
- linear acceleration
|
||
|
||
### B. cadenceSpm
|
||
|
||
用途：
|
||
|
||
- 训练分析
|
||
- 卡路里估算增强
|
||
- 玩法资源逻辑
|
||
|
||
### C. devicePose
|
||
|
||
建议值：
|
||
|
||
- `upright`
|
||
- `tilted`
|
||
- `flat`
|
||
|
||
### D. headingSource
|
||
|
||
建议值：
|
||
|
||
- `sensor`
|
||
- `blended`
|
||
- `movement`
|
||
|
||
### E. headingConfidence
|
||
|
||
建议值：
|
||
|
||
- `low`
|
||
- `medium`
|
||
- `high`
|
||
|
||
### F. elevationTrend
|
||
|
||
建议值：
|
||
|
||
- `flat`
|
||
- `ascending`
|
||
- `descending`
|
||
|
||
来源：
|
||
|
||
- barometer
|
||
- GPS altitude
|
||
|
||
---
|
||
|
||
## 8. 两端统一抽象建议
|
||
|
||
尽管两端可用传感器不同，但建议统一抽象，不让上层感知平台差异。
|
||
|
||
### 8.1 原始层
|
||
|
||
放在：
|
||
|
||
- `engine/sensor`
|
||
|
||
职责：
|
||
|
||
- 读取平台原始传感器
|
||
- 做最基础的节流、归一化、权限处理
|
||
|
||
### 8.2 融合层
|
||
|
||
放在：
|
||
|
||
- `telemetry`
|
||
|
||
职责：
|
||
|
||
- 生成统一高级状态
|
||
- 对外屏蔽平台差异
|
||
|
||
建议统一输出：
|
||
|
||
- `movementState`
|
||
- `devicePose`
|
||
- `headingSource`
|
||
- `headingConfidence`
|
||
- `cadenceSpm`
|
||
- `motionIntensity`
|
||
|
||
### 8.3 消费层
|
||
|
||
#### 地图引擎消费
|
||
|
||
- `headingSource`
|
||
- `devicePose`
|
||
- `headingConfidence`
|
||
|
||
#### 规则层消费
|
||
|
||
- `movementState`
|
||
- `cadenceSpm`
|
||
- `motionIntensity`
|
||
|
||
#### HUD / Feedback 消费
|
||
|
||
- `movementState`
|
||
- `cadenceSpm`
|
||
- 心率 / 卡路里 / 训练强度
|
||
|
||
---
|
||
|
||
## 9. 推荐接入顺序
|
||
|
||
### 微信小程序第一阶段
|
||
|
||
先接：
|
||
|
||
- `Gyroscope`
|
||
- `DeviceMotion`
|
||
|
||
目标：
|
||
|
||
- 提升自动转图质量
|
||
- 产出更稳定的姿态与朝向可信度
|
||
|
||
### 微信小程序第二阶段
|
||
|
||
再接：
|
||
|
||
- `Accelerometer`
|
||
|
||
目标：
|
||
|
||
- 提升 movement state 识别
|
||
|
||
### Flutter 第一阶段
|
||
|
||
先接：
|
||
|
||
- `Rotation Vector`
|
||
- `Gyroscope`
|
||
- `Linear Acceleration`
|
||
|
||
目标：
|
||
|
||
- 直接建立高质量朝向与运动状态底座
|
||
|
||
### Flutter 第二阶段
|
||
|
||
再接：
|
||
|
||
- `Step Counter`
|
||
- `Gravity`
|
||
|
||
目标：
|
||
|
||
- 增强运动统计与姿态判断
|
||
|
||
---
|
||
|
||
## 10. 当前最值得优先投入的方向
|
||
|
||
如果只从当前项目收益看，最值得优先做的是：
|
||
|
||
### 微信小程序
|
||
|
||
- `Gyroscope`
|
||
- `DeviceMotion`
|
||
|
||
### Flutter
|
||
|
||
- `Rotation Vector`
|
||
- `Gyroscope`
|
||
- `Linear Acceleration`
|
||
|
||
原因：
|
||
|
||
- 这些能力最直接影响地图体验
|
||
- 最贴近当前自动转图、前进方向、姿态识别需求
|
||
- 复用价值高
|
||
|
||
---
|
||
|
||
## 11. 一句话结论
|
||
|
||
### 微信小程序
|
||
|
||
可用传感器有限，但足够继续做：
|
||
|
||
- 更稳的自动转图
|
||
- 更好的朝向平滑
|
||
- 更好的运动状态识别
|
||
|
||
最值得优先接入的是：
|
||
|
||
- `Gyroscope`
|
||
- `DeviceMotion`
|
||
- `Accelerometer`
|
||
|
||
### 原生 Flutter App
|
||
|
||
可利用的原始传感器更完整，建议未来重点发挥：
|
||
|
||
- `Rotation Vector`
|
||
- `Gyroscope`
|
||
- `Linear Acceleration`
|
||
- `Step Counter`
|
||
|
||
两端都应遵守同一个原则：
|
||
|
||
**原始传感器进 `engine/sensor`，高级状态进 `telemetry`，上层只消费统一状态。**
|
||
|
||
|
||
|