Skip to content

组件语义(蓝牙) ​

本文说明字段变化会让组件产生什么变化,供开发者或 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 不同)。
  • 视频组件在蓝牙项目中不可用。
  • 重力传感器、指南针在蓝牙项目中可用。

# 写代码前的自查 ​

  1. 每个 out 字段都有触发点(按键、传感器变化),不是周期发送。
  2. 每个 in 字段都能被设备写入,且不会反过来依赖页面下发。
  3. 布尔值同时兼容 1/0 与 true/false。
  4. ToggleFragment 用 enabled,SwitchFragment 用 switch。
  5. 组类组件的字段数量按页面实际配置,不写死。
  6. 按钮的发送内容来自页面配置,不是 bindKey。

# 相关文档 ​