Skip to content

Commit fb74f21

Browse files
AurLemonAurLemon
committed
docs: 更新自述文件，生成事件文档
1 parent 6d87019 commit fb74f21

3 files changed

Lines changed: 264 additions & 34 deletions

File tree

‎README.md‎

Lines changed: 8 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -15,24 +15,14 @@ The current prototype is split into two parts:
1515
- `firmware`: PlatformIO firmware for the ESP32-S3 device
1616
- `app`: Electron + TypeScript + Vite desktop application
1717

18-
## Layouts
19-
20-
The repository layout is intentionally simple:
21-
22-
- `app/`
23-
Electron desktop-side project
24-
- `app/src/main.ts`
25-
Electron main process entry
26-
- `app/src/preload.ts`
27-
Preload bridge entry
28-
- `app/src/renderer.ts`
29-
Renderer entry
30-
- `firmware/`
31-
Embedded project for the hardware node
32-
- `firmware/src/main.cpp`
33-
Current firmware entry and sensor polling logic
34-
- `firmware/platformio.ini`
35-
PlatformIO board, framework, and library configuration
18+
## Structure
19+
20+
```txt
21+
root
22+
├── app/ # Desktop application
23+
├── docs/ # Project documentation
24+
└── firmware/ # ESP32-S3 firmware and embedded resources
25+
```
3626

3727
## Devices
3828

‎README_zh.md‎

Lines changed: 6 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -17,22 +17,12 @@ Sense Node 关注的是如何把桌面上的物理交互，转成软件侧可感
1717

1818
## 结构
1919

20-
仓库结构保持得比较直接：
21-
22-
- `app/`
23-
桌面端项目
24-
- `app/src/main.ts`
25-
Electron 主进程入口
26-
- `app/src/preload.ts`
27-
Preload 桥接入口
28-
- `app/src/renderer.ts`
29-
Renderer 入口
30-
- `firmware/`
31-
硬件节点对应的嵌入式工程
32-
- `firmware/src/main.cpp`
33-
当前固件入口与传感器轮询逻辑
34-
- `firmware/platformio.ini`
35-
PlatformIO 的板卡、框架和库依赖配置
20+
```txt
21+
root
22+
├── app/ # 桌面端应用
23+
├── docs/ # 项目文档
24+
└── firmware/ # ESP32-S3 固件与嵌入式资源
25+
```
3626

3727
## 设备
3828

‎docs/firmware-events.md‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
# 固件事件系统说明
2+
3+
## 0. 总体结构
4+
5+
| 层级 | 输入 | 输出 |
6+
| ---------------- | -------------------------------- | ------------------------------------------ |
7+
| IMU 模型原始输出 | IMU 六轴窗口数据 | `idle` / `tap` / `board_motion` |
8+
| IMU 后处理事件 | 模型原始输出 + 运行时特征 | `idle` / `tap` / `board_motion` / `reject` |
9+
| ToF 手部状态 | ToF 距离 | `no_hand` / `hand_hover` / `hand_near` |
10+
| ToF 一次性事件 | ToF 状态转移 | `hand_leave` |
11+
| 融合状态机 | IMU 后处理事件 + ToF 状态 / 事件 | `final_event` |
12+
13+
## 1. IMU 模型原始输出
14+
15+
| 事件名 | 含义 | 说明 |
16+
| -------------- | ------------ | ------------ |
17+
| `idle` | 板体静止候选 | 模型直接输出 |
18+
| `tap` | 敲击候选 | 模型直接输出 |
19+
| `board_motion` | 板体移动候选 | 模型直接输出 |
20+
21+
说明：
22+
23+
- 原始输出仅包含以上三类
24+
- `reject` 不属于模型原始类别
25+
26+
输入数据：
27+
28+
| 输入项 | 说明 |
29+
| ------------ | ---------- |
30+
| `ax, ay, az` | 加速度三轴 |
31+
| `gx, gy, gz` | 角速度三轴 |
32+
33+
窗口信息：
34+
35+
| 项目 | 值 |
36+
| ---------- | ------ |
37+
| 采样间隔 | `50ms` |
38+
| 每帧轴数 | `6` |
39+
| 原始样本数 | `60` |
40+
41+
## 2. IMU 后处理事件
42+
43+
| 事件名 | 含义 | 条件 |
44+
| -------------- | ------------ | --------------------------------------------- |
45+
| `idle` | IMU 静止事件 | 原始输出为 `idle`，且通过置信度门限 |
46+
| `tap` | IMU 敲击事件 | 原始输出为 `tap`，且通过冲击门限与冷却约束 |
47+
| `board_motion` | IMU 移动事件 | 原始输出为 `board_motion`，且持续时间满足条件 |
48+
| `reject` | IMU 拒识事件 | 置信度不足，或后处理条件不满足 |
49+
50+
`tap` 当前使用的判定项：
51+
52+
| 字段 | 用途 |
53+
| ---------------- | ------------ |
54+
| `imu_label` | 模型候选标签 |
55+
| `imu_confidence` | 置信度门限 |
56+
| `peak_acc_delta` | 冲击强度门限 |
57+
| `lastTapMs` | 冷却控制 |
58+
59+
运行时特征：
60+
61+
| 字段 | 计算或含义 |
62+
| ------------------- | ------------------------ |
63+
| `acc_mag` | 当前合加速度 |
64+
| `acc_delta` | 合加速度与重力基线的偏离 |
65+
| `gyro_mag` | 当前角速度强度 |
66+
| `motion_energy` | 组合运动强度 |
67+
| `peak_acc_delta` | 当前窗口内最大冲击偏移 |
68+
| `event_duration_ms` | 活跃状态持续时间 |
69+
70+
判定流程：
71+
72+
| 步骤 | 规则 |
73+
| ---- | ---------------------------------------------- |
74+
| 1 | 模型输出最高置信类别 |
75+
| 2 | 若最高置信度低于门限，输出 `reject` |
76+
| 3 | 若类别为 `tap`，额外检查冲击门限与冷却期 |
77+
| 4 | 若类别为 `board_motion`，额外检查持续时间 |
78+
| 5 | 条件满足时输出对应 IMU 事件，否则输出 `reject` |
79+
80+
当前实现状态：
81+
82+
| 项目 | 状态 |
83+
| --------------------- | ------ |
84+
| `confidence` 门限 | 已实现 |
85+
| `peak_acc_delta` 门限 | 已实现 |
86+
| `cooldown` | 已实现 |
87+
| `event_duration_ms` | 已实现 |
88+
| `jerk` 判定 | 未实现 |
89+
90+
## 3. ToF 手部状态
91+
92+
| 状态名 | 含义 | 条件 |
93+
| ------------ | -------------- | ---------------------------------------- |
94+
| `no_hand` | 无稳定手部目标 | 距离无效、超出范围，或离开后恢复为空状态 |
95+
| `hand_hover` | 手悬停 | 距离稳定落在 hover 区间 |
96+
| `hand_near` | 手靠近 | 距离稳定小于 near 阈值 |
97+
98+
说明：
99+
100+
- `hand_state` 仅包含以上三个值
101+
102+
阈值项：
103+
104+
| 字段 | 作用 |
105+
| ----------------- | ---------------------------- |
106+
| `NEAR_ENTER` | 进入 `hand_near` 的距离门限 |
107+
| `NEAR_EXIT` | 退出 `hand_near` 的距离门限 |
108+
| `HOVER_MIN` | `hand_hover` 最小距离 |
109+
| `HOVER_MAX_ENTER` | 进入 `hand_hover` 的最大距离 |
110+
| `HOVER_MAX_EXIT` | 退出 `hand_hover` 的最大距离 |
111+
| `TOF_INVALID` | 无效距离值 |
112+
113+
状态转移规则：
114+
115+
| 当前状态 | 条件 | 下一状态 |
116+
| ------------ | -------------------------------------- | ------------ |
117+
| `no_hand` | 距离稳定小于 `NEAR_ENTER` | `hand_near` |
118+
| `no_hand` | 距离稳定落在 hover 区间 | `hand_hover` |
119+
| `hand_near` | 距离大于 `NEAR_EXIT` 且仍在 hover 区间 | `hand_hover` |
120+
| `hand_near` | 距离无效或大于 `HOVER_MAX_EXIT` | `no_hand` |
121+
| `hand_hover` | 距离小于 `NEAR_ENTER` | `hand_near` |
122+
| `hand_hover` | 距离无效或大于 `HOVER_MAX_EXIT` | `no_hand` |
123+
124+
稳定时间：
125+
126+
| 场景 | 约束 |
127+
| ------------------------------- | ------------------------ |
128+
| 进入 `hand_hover` / `hand_near` | 需要持续超过稳定时间门限 |
129+
| 回到 `no_hand` | 需要持续超过离开时间门限 |
130+
131+
## 4. ToF 一次性事件
132+
133+
| 事件名 | 含义 | 条件 |
134+
| ------------ | ------ | ----------------------------------------------------------------- |
135+
| `hand_leave` | 手离开 | 从 `hand_hover` 或 `hand_near` 回到 `no_hand`，并持续超过离开门限 |
136+
137+
说明：
138+
139+
- `hand_leave` 不属于 `hand_state`
140+
- `hand_leave` 为一次性事件
141+
142+
触发过程：
143+
144+
| 步骤 | 条件 |
145+
| ---- | ------------------------------------------ |
146+
| 1 | 上一稳定状态为 `hand_hover` 或 `hand_near` |
147+
| 2 | 当前候选状态变为 `no_hand` |
148+
| 3 | `no_hand` 持续超过离开时间门限 |
149+
| 4 | 触发一次 `hand_leave` |
150+
151+
## 5. 融合状态机最终事件
152+
153+
| 事件名 | 含义 | 输出方式 |
154+
| -------------- | ------------ | -------------------------- |
155+
| `idle` | 默认静止事件 | 持续输出 |
156+
| `hand_hover` | 手悬停事件 | 持续输出 |
157+
| `hand_near` | 手靠近事件 | 持续输出 |
158+
| `hand_leave` | 手离开事件 | 触发一次 |
159+
| `tap` | 敲击事件 | 触发一次，随后进入冷却期 |
160+
| `board_motion` | 板体移动事件 | 短时间保持输出 |
161+
| `unknown` | 兜底事件 | 无可靠层给出稳定判断时输出 |
162+
163+
说明：
164+
165+
- IMU 输出 `reject` 时，最终事件不必然为 `unknown`
166+
- ToF 状态稳定时，可继续输出对应手部事件
167+
168+
融合输入：
169+
170+
| 输入项 | 来源 |
171+
| -------------- | -------------- |
172+
| `motion_event` | IMU 后处理事件 |
173+
| `hand_state` | ToF 手部状态 |
174+
| `hand_leave` | ToF 一次性事件 |
175+
| `confidence` | IMU 最高置信度 |
176+
177+
融合规则：
178+
179+
| 情况 | 最终输出 |
180+
| ------------------------------------ | ------------------- |
181+
| `motion_event == tap` 且通过冷却检查 | `tap` |
182+
| `motion_event == board_motion` | `board_motion` |
183+
| 存在 `hand_leave` 事件 | `hand_leave` |
184+
| `hand_state == hand_near` | `hand_near` |
185+
| `hand_state == hand_hover` | `hand_hover` |
186+
| IMU 可用且未触发其他高优先级事件 | `idle` 或 `unknown` |
187+
188+
补充规则：
189+
190+
| 规则 | 说明 |
191+
| ------------------- | -------------------------------------------- |
192+
| `tap` 冷却 | 冷却期内不重复触发 `tap` |
193+
| `board_motion` 保持 | 触发后维持短时间输出 |
194+
| ToF 兜底 | IMU 为 `reject` 时，ToF 稳定状态仍可继续输出 |
195+
196+
## 6. 事件优先级
197+
198+
```txt
199+
tap > board_motion > hand_leave > hand_near > hand_hover > idle > unknown
200+
```
201+
202+
| 优先级 | 事件名 |
203+
| ------ | -------------- |
204+
| 1 | `tap` |
205+
| 2 | `board_motion` |
206+
| 3 | `hand_leave` |
207+
| 4 | `hand_near` |
208+
| 5 | `hand_hover` |
209+
| 6 | `idle` |
210+
| 7 | `unknown` |
211+
212+
## 7. 当前串口输出字段
213+
214+
| 字段名 | 含义 |
215+
| ---------------- | -------------------- |
216+
| `imu_label` | IMU 模型原始分类结果 |
217+
| `imu_confidence` | IMU 模型最高置信度 |
218+
| `hand_state` | ToF 当前状态 |
219+
| `final_event` | 融合状态机最终输出 |
220+
221+
当前输出顺序：
222+
223+
```txt
224+
tof, ax, ay, az, gx, gy, gz, uptime, imu_label, imu_confidence, hand_state, final_event
225+
```
226+
227+
## 8. 后续接入建议字段
228+
229+
| 字段名 | 用途 |
230+
| --------------- | -------------- |
231+
| `distance_mm` | ToF 原始距离 |
232+
| `motion_event` | IMU 后处理事件 |
233+
| `hand_event` | ToF 一次性事件 |
234+
| `acc_delta` | 运动阈值调参 |
235+
| `reject_reason` | 拒识原因记录 |
236+
237+
`reject_reason` 建议值域：
238+
239+
| 值 | 含义 |
240+
| ----------------- | -------------- |
241+
| `low_confidence` | 置信度不足 |
242+
| `impact_too_weak` | 冲击不足 |
243+
| `cooldown` | 冷却期内 |
244+
| `tof_unstable` | ToF 状态不稳定 |
245+
246+
## 9. OLED 输出
247+
248+
| 字段名 | 含义 |
249+
| ------------- | ------------ |
250+
| `final_event` | 当前最终事件 |

0 commit comments

Comments
 (0)