158 lines
5.0 KiB
Markdown
158 lines
5.0 KiB
Markdown
# DevicePlugin 统一设备管理插件设计
|
||
|
||
## 1. 核心理念
|
||
|
||
所有硬件访问统一通过 DevicePlugin 一个插件完成。多平台适配只需替换 DevicePlugin 的后端实现，上层业务插件无需改动。
|
||
|
||
## 2. 架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────┐
|
||
│ 业务插件 (Video/BLE/HTTP/...) │
|
||
│ 通过 Message 发送 DeviceCommand │
|
||
├──────────────────────────────────────────┤
|
||
│ DevicePlugin │
|
||
│ 接收 DeviceCommand → 分发给 Backend │
|
||
│ Backend 事件 → 发送 DeviceEvent 消息 │
|
||
├──────────────────────────────────────────┤
|
||
│ DeviceBackend trait │
|
||
│ ┌─────────┬──────────┬───────────────┐ │
|
||
│ │ Linux │ Android │ Embedded │ │
|
||
│ │ ARM64 │ │ (bare-metal) │ │
|
||
│ └─────────┴──────────┴───────────────┘ │
|
||
├──────────────────────────────────────────┤
|
||
│ 硬件层 │
|
||
│ Framebuffer / DRM / GPIO / I2C / SPI │
|
||
│ Screen / Backlight / Sensors / Audio │
|
||
└──────────────────────────────────────────┘
|
||
```
|
||
|
||
## 3. DeviceBackend trait
|
||
|
||
```rust
|
||
pub trait DeviceBackend: Send {
|
||
/// 后端名称 (如 "linux-arm64", "android", "embedded")
|
||
fn name(&self) -> &str;
|
||
|
||
/// 初始化后端
|
||
fn init(&mut self, config: &serde_json::Value) -> Result<()>;
|
||
|
||
/// 处理设备命令
|
||
fn handle_command(&mut self, cmd: DeviceCommand) -> Result<DeviceResponse>;
|
||
|
||
/// 获取设备能力列表
|
||
fn capabilities(&self) -> Vec<DeviceCapability>;
|
||
|
||
/// 关闭后端
|
||
fn shutdown(&mut self) -> Result<()>;
|
||
}
|
||
```
|
||
|
||
## 4. 消息类型
|
||
|
||
### DeviceCommand (业务插件 → DevicePlugin)
|
||
```rust
|
||
pub enum DeviceCommand {
|
||
// 显示
|
||
GetDisplayInfo,
|
||
SetBrightness(u8),
|
||
SetBacklight(bool),
|
||
WriteFramebuffer { data: Vec<u8>, format: PixelFormat },
|
||
|
||
// 输入
|
||
GetTouchEvents,
|
||
GetButtonState,
|
||
GetSensorData(SensorType),
|
||
|
||
// 音频
|
||
PlayAudio { path: String },
|
||
SetVolume(u8),
|
||
|
||
// 电源
|
||
GetBatteryLevel,
|
||
SetSleepInhibit(bool),
|
||
|
||
// 通用
|
||
CustomCommand { subsystem: String, payload: serde_json::Value },
|
||
}
|
||
```
|
||
|
||
### DeviceResponse (DevicePlugin → 请求者)
|
||
```rust
|
||
pub enum DeviceResponse {
|
||
DisplayInfo { width: u32, height: u32, format: PixelFormat },
|
||
SensorData { sensor: SensorType, value: f64 },
|
||
BatteryLevel(u8),
|
||
Ok,
|
||
Error(String),
|
||
Custom(serde_json::Value),
|
||
}
|
||
```
|
||
|
||
### DeviceEvent (DevicePlugin → 广播)
|
||
```rust
|
||
pub enum DeviceEvent {
|
||
TouchEvent { x: i32, y: i32, action: TouchAction },
|
||
ButtonEvent { button: u8, pressed: bool },
|
||
BatteryLow(u8),
|
||
DisplayConnected,
|
||
DisplayDisconnected,
|
||
SensorAlert { sensor: SensorType, value: f64 },
|
||
}
|
||
```
|
||
|
||
## 5. DeviceCapability
|
||
|
||
```rust
|
||
pub enum DeviceCapability {
|
||
Display,
|
||
Touch,
|
||
Buttons,
|
||
Audio,
|
||
Battery,
|
||
Backlight,
|
||
Sensors,
|
||
Framebuffer,
|
||
GPIO,
|
||
}
|
||
```
|
||
|
||
## 6. 实施计划
|
||
|
||
### 阶段一：基础框架
|
||
1. 在 Message enum 中添加 DeviceCommand/DeviceResponse/DeviceEvent 变体
|
||
2. 创建 src/plugins/device/mod.rs — DevicePlugin 实现
|
||
3. 创建 src/plugins/device/backend.rs — DeviceBackend trait
|
||
4. 创建 src/plugins/device/linux_arm64.rs — 当前平台后端
|
||
|
||
### 阶段二：迁移现有功能
|
||
1. ScreenPlugin 的防息屏/光标隐藏 → DevicePlugin.SetSleepInhibit/backlight
|
||
2. VideoPlugin 的 framebuffer 写入 → DevicePlugin.WriteFramebuffer
|
||
3. 保持旧插件作为 thin wrapper 过渡期兼容
|
||
|
||
### 阶段三：扩展
|
||
1. 触摸/按钮输入事件
|
||
2. 传感器数据读取
|
||
3. 音频播放
|
||
4. 其他平台后端 (Android 等)
|
||
|
||
## 7. 关键约束
|
||
- DevicePlugin 是唯一允许直接访问硬件的插件
|
||
- 其他插件通过 Message 与 DevicePlugin 交互
|
||
- DeviceBackend 通过编译 feature gate 或运行时配置选择
|
||
- 首次实现只需支持 Linux ARM64 后端
|
||
- 所有 DeviceCommand 必须是 Serialize + Deserialize (跨 FFI 边界)
|
||
|
||
## 8. 验收标准
|
||
- [ ] DevicePlugin 通过 Plugin trait 正确注册和启动
|
||
- [ ] 至少 Display + SleepInhibit 两个能力在 Linux ARM64 后端工作
|
||
- [ ] ScreenPlugin 功能迁移到 DevicePlugin 且测试通过
|
||
- [ ] 新增测试 ≥ 5 个
|
||
- [ ] cargo check 零 warning, cargo test 全部通过
|
||
|
||
## CEO 决策
|
||
- 报告来源：架构师王思远分析设计
|
||
- 评审结论：方案通过，分三阶段实施
|
||
- 优先级：P1 (Phase 2 核心任务)
|
||
- 负责人：待 PM 分配
|