组件语义(蓝牙)
本文说明字段变化会让组件产生什么变化,供开发者或 AI 写固件时查阅。 「页面上有哪些字段」看控制台导出的组件描述;「字节怎么排」看《二进制协议》。 本文只收录写错就会错的条目,不重复组件描述里的 type / 量程。
# 数据方向
每个字段的 direction 决定谁写谁:
| direction | 含义 | 固件要做的事 |
|---|---|---|
in | 只输入 | 只上报。设备不要等这个字段下发 |
out | 只输出 | 只接收。页面不会因为设备上报而改变它 |
inout | 双向 | 既要处理下发,也要上报 |
# 值的形态(文本协议)
text
$X#D#switch:1;slider:35&校验\r\n- 布尔字段:
true/false或1/0都认。 - 数组字段:
a,b,a(逗号分隔,允许重复)。 - 对象字段(
deviceState):capacity:80这类子项形式,或按页面实际配置。 - 同一个
bindKey在整页里应当唯一;重名的字段会互相覆盖。
启用二进制转换表后,映射字段按《二进制协议》编码,未映射字段仍走上面的文本帧。
# 各组件
开关 SwitchFragment
- 字段:
switch,Boolean,inout - 下行:
0/1或false/true;上行:设备状态变化时上报 - 不要周期性重复上报同一个值,页面会重复触发状态动画
切换 ToggleFragment
- 字段:
enabled,Boolean,inout - 注意:bindKey 是
enabled,不是switch。它和开关是两种组件,最容易抄错
滑块 SliderFragment
- 字段:
slider,Float,inout - 量程/步进/小数位以组件描述里的
min/max/step/precision为准 - 默认
justUpSend = true:只在松手时发送一次,设备不要期待拖动过程中的连续帧
滑块组 / 数值组
- 一个槽位一个字段:
slider1、slider2……(组的成员数量由页面决定) - 不要写死 3 个,按组件描述里的实际字段生成
选择按钮 CheckboxFragment
- 字段:
item(单数),inout - 单选时值是一个字符串,多选时值是数组
- 二进制:多选按
items顺序每项占 1 bit;单选按下标写入索引(LSB 优先)
选项组 CheckboxGroupFragment
- 一槽一字段:
group1、group2……,inout - 每组是单选还是多选,由页面里该行配置决定(
multiCheck),同一个组里可以不同
下拉选择 SelectFragment
- 字段:
selected,String,inout - 值是
options里的value(常见为"0"、"1"),不是显示文本 - 二进制:写下标索引,位宽由转换表决定
方向键 ArrowKeyFragment
- 字段:
up、down、left、right、ok,都是 String、out - 按下发对应值,释放发空;
isSendUp/isSendDown控制是否发送按下/松开两帧 - 二进制:每个方向 1 bit,按下为 1
颜色选择器 ColorPickerFragment
- 字段:
color,Color,inout - 文本:
#RRGGBB或ff0000;二进制:RGB565(16 位时 R5G6B5)
按钮 ButtonFragment
- 没有 bindKey,组件描述里看不到它
- 点击后发送的是页面里配置的
sendData(文本)或sendHex(十六进制) - 写固件时必须向用户确认按钮发的是什么,不能按字段猜
曲线图 LineMarkerFragment
- 没有 bindKey,数据以
series里的 key 接收 - 收到同 key 的数据是追加一个点,不是替换
- 二进制转换表里没有曲线图字段,只能走文本
设备状态 DeviceStateFragment
- 字段:
deviceState,Object,in - 蓝牙端只有
capacity(0~100,101 表示充电中),信号强度由 App 计算,设备不需要上报 - 二进制不能映射 Object,只能走文本或属性帧
0x11(电量在 byte0:AE 11 02 [capacity][rssi])
显示类组件
数字滚动、仪表盘、进度条、水位、电池、文本、接收器等:direction 基本是 in,设备只上报即可,不要等待下发。
# 蓝牙端专属约束
- 设备状态没有 rssi(与 IoT 不同)。
- 视频组件在蓝牙项目中不可用。
- 重力传感器、指南针在蓝牙项目中可用。
# 写代码前的自查
- 每个
out字段都有触发点(按键、传感器变化),不是周期发送。 - 每个
in字段都能被设备写入,且不会反过来依赖页面下发。 - 布尔值同时兼容
1/0与true/false。 ToggleFragment用enabled,SwitchFragment用switch。- 组类组件的字段数量按页面实际配置,不写死。
- 按钮的发送内容来自页面配置,不是 bindKey。
