跳到主要内容

运动数据和设备控制通信协议

版本历史

版本时间作者描述
1.0.020231124胡伟初始化文档
1.1.020240319胡伟增加导航数据
1.1.120240320胡伟完善运动数据同步
1.2.020240416胡伟调整命令格式，增加大MTU数据模式
1.3.020240607高畅增加Ymodel服务，Ymodel传输流程，增加pipeline特征中动态数据模式下发，通知命令，增加Panel,UserProfile文件定义
1.3.120240620高畅增加Panel出厂文件示例，增加充电盒电量显示
1.3.220240620高畅增加WorkoutStatus 结束运动状态定义值
1.3.320240620高畅增加NaviStatus 用户主动结束导航状态定义值
1.3.320240711高畅增加ANCS开关命令，查询和返回值定义

作者

姓名邮箱公司
胡伟wei.hu@bi-ci.com上海大不自多信息科技有限公司

版权告知

本文档版权属于上海大不自多信息科技有限公司。

1. 概述

智能硬件蓝牙通信协议（以下简称本协议）用于规范化第三方硬件与行者/XOSS APP之间进行蓝牙数据传输和命令控制。我们定义传输服务以及三个数据传输通道，智能设备通过实现必须的服务和通道来与行者APP进行数据通信与传输。

1.1 描述依赖​

基于蓝牙Generic Attribute Profile (GATT) 定义。

1.2 蓝牙规范和兼容性要求​

本规范要求蓝牙版本4.0以及以上，支持低功耗蓝牙（BLE）。

1.3 专业术语​

  1. Bluetooth Remote Device：蓝牙外设，后面简称BR Device
  2. Bluetooth Remote Profile：蓝牙外设配置，简称BR Profile
  3. Bluetooth Remote Service：蓝牙外设服务，蓝牙层服务，简称BRS
  4. Device Information Service：蓝牙标准设备信息服务，简称DIS
  5. Bluetooth Ymodel Service：蓝牙Ymodel服务，蓝牙层服务，简称BYS

2 配置

2.1 规则​

本规范定义了2个角色：BR Device，Collector。

  • BR Device 蓝牙设备：眼睛，摄像设备等

  • Collector（APP or 码表）：用户接受设备信息和控制设备

3 Bluetooth Remote Device要求

BG设备必须包含且仅包含一个Bluetooth Remote Service （简称BRS）

BG设备必须包含标准蓝牙的Device Information Service（简称DIS）

BG设备必须包含标准蓝牙的Battery Service （简称BS）

BG设备可选包含OTA Service （简称OTA）

3.1 Bluetooth Remote Service要求​

3.1.1 低功耗传输要求​

本节中描述Bluetooth Remote设备定义的Bluetooth Remote服务必须通过低功耗蓝牙传输（Low Energy）。

3.1.1.1 服务UUIDs 广播

Bluetooth Remote设备广播时，必须在广播信息中带有Bluetooth Remote Service的uuid信息，以增强用户使用体验，方便用户在发现时识别设备类型。

3.1.1.2 设备名称广播

为了增强用户体验，设备名称必须在广播时提供。

3.2 广播服务数据​

本节定义了BR设备的广播信息内容，允许客户端通过广播信息确定设备类型。自定义广播数据如下表：

广播数据字段类型大小要求
Service Data AD TypeUINT81M
BRS UUID2M

表

广播数据Appearance Value定义

类型值
Glass 眼镜0x01C0
Camera 相机
Display 显示器0x0140
Ebike 电助力自行车0x08C3

3.3 字节顺序Byte Ordering​

本文档中当特征值或者描述值有多个字节组成时，定义如下：

LSBLeast Significant Bit（最低有效位）
LSOLeast Significant Octet（最低有效字节）
MSBMost Significant Bit（最高有效位）
MSOMost Significant Octet（最高有效字节）

表

3.4 DIS要求​

参考蓝牙官方标准协议，DIS服务UUID为0x180A，本设备需要的特征服务表定义如下：

特征UUID支持描述
Manufacturer Name String0x2A29M设备制造商的名称，写设备制造商为外界所熟识的名称
Model Number String0x2A24M由设备制造商定义，建议写为某个产品的型号
Serial Number String0x2A25M由制造商定义的产品编号，为每个产品赋一唯一的编号,可以按实际应用定义自己产品SN的格式。
Hardware Revision0x2A27M产品的硬件编号，建议使用三位数以点相隔，分别表示主版本号，副版本号，发行编号
Firmware Revision0x2A26M固件软件版本号，建议使用三位数以点相隔，分别表示主版本号，副版本号，发行编号
Software Revision0x2A27O应用软件版本号，建议使用三位数以点相隔，分别表示主版本号，副版本号，发行编号（偶数发行，奇数调试）
System ID0x2A23O包含OUI( Oranizationally Unique Identifier)和一个由制造商为该产品编排的唯一编号
PnP ID0x2A50O包含由国标组织颁给制造商的编号，制造商定义的产品ID,由制造商定义的产品版本信息

表

3.5 BS要求​

参考蓝牙官方标准协议，BS服务UUID为0x180F，本设备需要的特征服务表定义如下：

特征UUID支持描述
Battery Level0x2A19M电池电量 0～100
Battery Level Status0x2A24O电池电量状态定义，包括是否充电中

表

4. 蓝牙服务和特征​

BGS 是设备的主要属性和功能，设备支持的服务和特征如下表：

Profile需求章节支持
Service 发现4.1必需
BGS 服务发现4.1必需
DIS 服务发现4.1必需
特性发现4.2必需
BGS 服务特征发现4.2.1必需
DIS 服务特征发现4.2.2必需

4.1 服务发现​

使用低功耗蓝牙传输时，Collector应该在遍历发现主服务，并比对出相应的uuid的服务。

Bluetooth Remote Service UUID：0xADB401C0-B1C6-11ED-AFA1-0242AC120002

4.2 特征发现​

4.2.1 Bluetooth Remote 特征发现​

Bluetooth Remote Characteristics包含以下特性

Characteristics支持属性描述
Bluetooth Remote FeatureMRead支持的特性
Bluetooth Remote Machine StatusMRead, Notify当前状态，支持读和通知模式
Bluetooth Remote Control PointOWrite, Indicate控制和设置设备，支持写和写响应
Bluetooth Remote Live DataOWrite用于发送实时数据

4.2.2 DIS特征发现​

参考蓝牙官方标准协议

4.2.3 BS特征发现​

参考蓝牙官方标准协议

4.3 Bluetooth Remote Features特征​

特征UUID：0xADB40001-B1C6-11ED-AFA1-0242AC120001

Bluetooth Remote Feature特征用于描述本设备支持的特性。定义结构如下：

FeatureRemote TypeRemote ModeReserved
字段类型UINT16UINT16
大小2 octets2 octets
字节顺序LSO...MSOLSO...MSO
单位NoneNone

表

4.3.1 设备类型特性支持（Remote Type Feature）定义​

当Remote Type Feature 字段中的某个位设置为 1 (True) 时，服务支持关联的功能。 如果服务不支持相关功能，则相关功能位应设置为 0（false），设备Type支持配置表：

Bit定义类型值
0Glass 眼镜0 - Not Support 1 - Support
1Camera 相机0 - Not Support 1 - Support
2Display 显示器0 - Not Support 1 - Support
3Ebike 电助力自行车0 - Not Support 1 - Support
4Reserved0
5Reserved0
6Reserved0
7Reserved0
8～15Reserved0

4.3.2 设备模式特性支持（Remote Mode Feature）定义​

当Remote Mode Feature 字段中的某个位设置为 1 (True) 时，服务支持关联的功能。 如果服务不支持相关功能，则相关功能位应设置为 0（false），设备支持模式表如下：

Bit描述值
0OFF 设备关0 - Not Support 1 - Support
1ON 投影模式0 - Not Support 1 - Support
2CUSTOM 自定义模式0 - Not Support 1 - Support
3~15保留0

4.4 Bluetooth Remote Machine Status特征​

Bluetooth Remote Machine Status特征用于描述本设备目前的设备状态。

特征UUID：0xADB40002-B1C6-11ED-AFA1-0242AC120002，定义结构如下：

Byte描述大小默认值单位
0Flags1 octet
1Remote type 表 3-42 octet
2Remote Mode Status 表 4-92 octet
3Remote Glass StatusMTU-3 octets
4Remote Camera StatusMTU-3 octets
5Remote Display StatusMTU-3 octets
6Ebike StatusMTU-3 octets

Flags field

Flag bitValue = 0Value = 1
0Remote type field not presentRemote type field present
1Remote mode field not presentRemote mode field present
2Remote Glass field not presentRemote Glass field present
3Remote Camera field not presentRemote Camera field present
4Remote Display field not presentRemote Display field present
5Ebike field not presentEbike field present
6～7Resevred

4.4.1 设备Remote type​

设备类型参考表

4.4.2 设备模式当前状态​

1字节表示，每个已链接设备模式状态描述如下表：

值定义
0设备关闭
1投影开
2自定义
3~63保留

4.4.3 眼镜设备当前状态​

Byte描述大小默认值单位备注
0Box Battery1 octet0%电池仓电量
1Box Status1 octet0%电池仓状态

4.4.4 相机设备当前状态​

Byte描述大小默认值单位备注
0camera lens1 octet14mm焦距
1frame1 octet0fps帧率，0表示自动
2shutter2 octet01/N快门，0表示自动
4iso2 octet0iso，0表示自动
6wb2 octet0色温，0表示自动
8tint1 octet0色调
9hdr1 octet00，off， 1，on
10log1 octet00，off， 1，on

4.4.5 显示设备当前状态​

TODO

4.4.6 Ebike当前状态​

电量电池状态 Battery Level Status电机功率保留
大小UINT8UINT8UINT16
值电量% 0～10000
备注电量，255 表示不支持默认0实时电机功率, 65535表示不支持

Battery Level Status如下表：

Value描述
0(0x00)Reserved
1(0x01)Battery Status = New/Full
2(0x02)Battery Status = Good
3(0x03)Battery Status = Ok
4(0x04)Battery Status = Low
5(0x05)Battery Status = Critical
6(0x06)Battery Status = Charging

4.5 Bluetooth Remote Control Point 特征​

特征UUID：0xADB40003-B1C6-11ED-AFA1-0242AC120003，在Bluetooth Remote Control Point 特征通道中，向本通道写入命令，命令的格式定义如下表：

     LSO           MSO
Op CodeParameter
OrderLSO...MSO
TypeUINT8Variable
Size1 octet0～MTU—2 octets

4.5.1 Operate Code 操作定义​

控制命令操作符号表

Op Code支持定义参数描述
0x00MRequest ControlN/A请求对设备的控制，响应码为0x80
0x01MResetN/A请求重置设备的控制，响应码为0x80
0x02OSet Remote TypeRemote Type：设置类型
0x03OSet Remote ModeRemote Mode：设置模式
0x04~0x09O保留
0x0AOdebug Workout Data [4.6]最长MTU—2字节最长MTU—2字节 运动数据
0x0BOdebug Navigation Data [4.6]最长MTU—2字节最长MTU—2字节 导航数据
0x0C～0X7FN保留
0x80M响应代码表 4-12标记对Control Point的请求响应
0x81～0xD9N保留
0xDAO设置设备时间日期8字节UInt32 GMT时间+UInt32 当地时间 时间戳 小端存储
0xDB～0xDFN保留
0xDFO请求设备进入DFU状态N/A设备进入DFU状态，即断开，无返回值
0xF0～0xFFN保留

表 4-11

眼镜设备相关控制命令

Op Code支持定义参数描述
0x06O设置亮度设置光强度百分比，值范围0～100 UINT8 0xFF表示请求当前亮度值
0x12O0 ～ 6000 当前值UInt16 0xFFFF - 请求状态秒
0x20OANCS通知开关Parameter:00关 01开 0xFF查询当前状态

MTU 是硬件设备和APP之间握手的单次最大包大小。

4.5.2 Response Code 操作定义​

在Bluetooth Remote Control Point 特征通道中响应数据格式如下：

Reponse CodeOp Code=0x80Request Op CodeResult CodeResponse Parameter
OrderLSO...MSO
TypeUINT8UINT8UINT8
Size1 octet1 octet1 octet0～17 octets

表 4-12

4.5.3 Reslut Code 定义​

Result Code定义Request Op CodeResponse Parameter
0x00ReservedN/AN/A
0x01成功表 4-11N/A
0x02不支持Op Code表 4-11N/A
0x03非法参数表 4-11N/A
0x04失败表 4-11N/A
0x05没有权限表 4-11N/A
0x06~FFReservedN/AN/A

表 4-13

眼镜 OPCode Functions Response Parameter

Op Code支持定义Response Parameter描述
0x06O设置亮度设置光强度百分比，值范围0～100 UINT8 0xFF表示请求当前亮度值
0x12O休眠时间当前值UInt16
0x20OANCS通知开关Parameter:00关 01开 0xFF查询当前状态

4.5.4 Workout Data 定义​

详见 [4.6]

4.5.5 Navigation Data 定义​

详见 [4.6]

4.5.6 Camera Control 定义​

Control Code支持定义参数描述
0x00Otake photoN/A拍照
0x01Ostart videoN/A开始录像
0x02Ostop videoN/A结束录像
0x03Ocamera configparameters相机配置 参考 4.4.4
0x04Oformat storageN/A格式化存储

4.5.6 图层样式 定义​

Workout Data TypeOverlay style Value
Order
TypeUINT8UINT8
Size1 octet 参考 4.5.4 key值1 octet

4.6 Bluetooth Data pipeline 特征​

特征UUID：0xADB40004-B1C6-11ED-AFA1-0242AC120004，在Bluetooth Data pipeline 特征通道中，使用 write without response 向本通道写入实时数据，实时数据的格式定义如下表：

     LSO           MSO
Data typeData
OrderLSO...MSO
TypeUINT8Variable
Size1 octet0～MTU—2 octets

4.6.1 Data type 定义​

数据类型表

Data type支持定义描述
0x00OWorkout Data运动实时数据
0x01ONavigation Data导航实时数据
0x02OOverlay Data图层数据
0x03ODynamic Workout Data动态运动数据
0x04ODynamic Navigation Data动态导航数据
0x05ONotification Data通知数据（渠道）

4.6.2 Workout Data 定义​

WorkoutData 约束为1个字节数据类型和2个字节值类型：

Workout Data TypeData Value
Order
TypeUINT8
Size1 octet1~4 octets

Workout data type 定义如下：

key值Title定义Data Type
0Type运动类型枚举UINT8
1Sub Type子类型UINT8
2Workout State状态UINT80记录中;1暂停中;2结束
3CaloriesUINT16
4Moving TimeUINT32
5Total TimeUINT32
6Paused TimeUINT32
7DistanceUINT32单位米，scale: 100
8SpeedUINT16单位米/秒，scale: 1000
9Avg Moving SpeedUINT16
10Avg SpeedUINT16
11Max SpeedUINT16
12PaceUINT8
13Avg PaceUINT8
14Max PaceUINT8
15ElevationUINT16单位米
16GradeUINT16原始值+90，scale: 100，单位%
17Elevation GainUINT32单位米，scale: 100
18Elevation LossUINT32单位米，scale: 100
19Avg GradeUINT16原始值+90，scale: 100，单位%
20VAMUINT16单位米，scale: 100
21HeartrateUINT8
22Max HRUINT8
23AVG HRUINT8
24% MAX HRUINT8
25% LTHRUINT8
26CadenceUINT8
27Max CadenceUINT8
28Avg CadenceUINT8
29PowerUINT16watts
30Avg PowerUINT16
31Max PowerUINT16
323s Avg PowerUINT16
3310s Avg PowerUINT16
3430s Avg PowerUINT16
35% FTPUINT8%，scale: 100
36NPUINT8
37latINT32scale: 1000000
38lonINT32scale: 1000000
39GNSS StatusUINT80, 信号丢失，1，正常
40～199Reserved
200combine1组合数据1
201combine2组合数据2
203combine3组合数据3
202～255Reserved

combine1 基础数据组合

Data TypeWorkout StateMoving TimeDistanceSpeedElevationHeartrate
TypeUINT8UINT8UINT32UINT32UINT16UINT16UINT8
Size1 octet1 octet4 octets4 octets2 octets2 octets1 octet

combine2 爬坡数据组合

Data TypeElevationGradeElevation GainVAM
TypeUINT8UINT16UINT8UINT32UINT16
Size1 octet2 octets1 octet4 octets2 octets

combine3 传感器数据组合

Data TypeHeartrateCadencePowerAVG HRAvg CadenceAvg Power
TypeUINT8UINT8UINT8UINT16UINT8UINT8UINT16
Size1 octet1 octet1 octet2 octets1 octet1 octet2 octets

组合字段种如果该字段数值不存在或者无效时 UInt8 = 0xFF UInt16 = 0xFF UInt32 = 0xFFFF

Workout Type ValueType
0Generic
1Walk
2Running
3Cycling
4Hiking
5Swimming
6Skiing
7Travel
8Trainer
11IndoorCycling
12Virtual
13ebike
14motobike

4.6.3 Workout Data 示例​

workout data 参考4.5.4内容

例子：

  • 单个workout 数据 speed = 10m/s = 0x2710

    0x00 08 10 27

  • 组合workout 数据1 cycling recording 3600s 30km 12m/s 765m 143bpm

Data typeWorkout KeySportWorkout StateMoving TimeDistanceSpeedElevationHeartrate
Workout Data组合数据1 200cycling记录中3600s30km12m/s765m143bpm
UINT8UINT8UINT8UINT8UINT32UINT32UINT16UINT16UINT8
0x00C8030010 0E 00 00C0 C6 2D 00E0 2EFD 028F

导航数据例子： 前方300米右转进入ABC，距离终点32000米，预计6000s到达终点 第一组数据表示到终点的状态

Data typeFlagRemaining DistanceEstimated Time
UINT8UINT8UINT32UINT32
Navi Data导航数据标志剩余里程32000剩余时间3600s
0x010011110100 7D 00 0010 0E 00 00

第二组数据表示到下一个途径点的状态

Data typeFlagRemaining DistanceManeuver
UINT8UINT8UINT32Uint8
Navi Data导航数据标志剩余里程300剩右转
0x010001100112 0C 00 0005

第三组数据表示路名（如果有）

Data typeFlagStreet Name
UINT8UINT8String
Navi Data导航数据标志路名
0x0110000000二进制字符串编码unicode 不超过18字节

4.6.4 Navigation Data 定义​

FlagsRemaining DistanceRemaining Vertical DistanceEstimated TimeManeuverStreet Name
TypeUINT8UINT32UINT32UINT32UINT8
Size1 octet1 octet4 octets4 octets1 octetN octets

Flags Field 1bytes

Flag bitNameValue = 0Value = 1
0Remaining Distance 剩余距离not presentpresent
1Remaining Vertical Distance 剩余爬升not presentpresent
2Estimated Time of Arrival 预计到达时间not presentpresent
3Position Status 定位状态not PositionPosition
4Maneuver 方向指引not presentpresent
5Navigation Indicator Type 导航指引类型Remaining Distance is relative to the Step/Waypoint 下一步Remaining Distance is relative to the Destination 终点
6Reached 是否到达not reachedreached
7Street Namenot presentpresent

骑行导航 Maneuver indicator 定义

Maneuver indicator TypeDescription
0x00直行
0x01偏左
0x02左转
0x03左急
0x04偏右
0x05右转
0x06右急

NAVI data MTU>100 大包模式

Flags导航状态到下一个导航点剩余距离到下一个导航点剩余预估时间到终点剩余距离到终点预估时间当前坡的剩余爬升距离当前坡距离坡顶距离当前坡的剩余预估时间坡度评级Maneuver航向路名长度路名
TypeUINT8UINT8UINT32UINT32UINT32UINT32UINT32UINT32UINT32UINT8UINT8UInt8
Size1 octet1 octet4 octets4 octets4 octets4 octets4 octets4 octets4 octets1 octet1 octet1 octetmax 64 octets

要求mtu交换所得值大于96 octets的情况下使用 Flags Field 1bytes 值固定为 0xFF

NaviState 定义

CodeDescription
0x01导航中
0x02已偏航
0x03从偏航状态回归到导航路线
0x04到达终点，正常结束导航
0x05导航失败
0x06用户主动结束导航

路名 最大64 octets,使用Unicode编码，中文最大个16个字符。

坡度评级 ：

Slope TypeDescription
0x011级坡
0x022级坡
0x033级坡
0x044级坡
0x05HC级坡

4.6.6 Dynamic Workout Data 定义​

数据结构如图所示，每个结构由数据长度，数据类型，数据值组成 数据定义 所有数据类型的示例如下表

运动状态

Flags(03)数据长度 Data Lenth（n octet）运动类型枚举Key运动类型枚举数据长度 Data Lenth（n octet）子类型Key子类型数据长度 Data Lenth（n octet）状态Key状态数据长度 Data Lenth（n octet）卡路里Key卡路里
TypeUINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8
Size1 octet1 octet1 octet(0x00)1 octet1 octet1 octet(0x01)1 octet1 octet1 octet(0x02)1 octet1 octet1 octet(0x03)1 octet

运动时间

数据长度 Data Lenth（n octet）运动时间 Moving Time Key运动时间 Moving Time数据长度 Data Lenth（n octet）总时间 Key总时间数据长度 Data Lenth（n octet）暂停时间 Paused Time Key暂停时间 Paused Time
UINT8UINT8UINT32UINT8UINT8UINT32UINT8UINT8UINT32
1 octet1 octet(0x04)4 octet1 octet1 octet(0x05)4 octet1 octet1 octet(0x06)4 octet

速度类

数据长度 Data Lenth（n octet）距离Key距离数据长度 Data Lenth（n octet）速度 Key速度数据长度 Data Lenth（n octet）平均运动速度 Avg Moving Speed Key平均运动速度 Avg Moving Speed数据长度 Data Lenth（n octet）平均速度 Avg Speed Key平均速度 Avg Speed数据长度 Data Lenth（n octet）最大速度 Key最大速度数据长度 Data Lenth（n octet）步速 Pace Key步速 Pace数据长度 Data Lenth（n octet）平均步速 Avg Pace Key平均步速 Avg Pace数据长度 Data Lenth（n octet）最大步速 Max Pace Key最大步速 Max Pace
UINT8UINT8UINT32UINT8UINT8UINT16UINT8UINT8UINT16UINT8UINT8UINT16UINT8UINT8UINT16UINT8UINT8UINT16UINT8UINT8UINT16UINT8UINT8UINT16
1 octet1 octet(0x07)4 octet1 octet1 octet(0x08)2 octet1 octet1 octet(0x09)2 octet1 octet1 octet(0x0a)2 octet1 octet1 octet(0x0b)2 octet1 octet1 octet(0x0c)2 octet1 octet1 octet(0x0d)2 octet1 octet1 octet(0x0e)2 octet

海拔和爬升

数据长度 Data Lenth（n octet）海拔 Elevation Key海拔 Elevation数据长度 Data Lenth（n octet）坡度 Grade Key坡度 Grade数据长度 Data Lenth（n octet）爬升Elevation Gain Key爬升Elevation Gain数据长度 Data Lenth（n octet）下降 Elevation Loss Key下降 Elevation Loss数据长度 Data Lenth（n octet）平均坡度 Avg Grade Key平均坡度 Avg Grade数据长度 Data Lenth（n octet）平均爬升速度 VAM Key平均爬升速度 VAM
UINT8UINT8UINT16UINT8UINT8UINT8UINT8UINT8UINT32UINT8UINT8UINT32UINT8UINT8UINT8UINT8UINT8UINT16
1 octet1 octet(0x0f)2 octet1 octet1 octet(0x10)1 octet1 octet1 octet(0x11)4 octet1 octet1 octet(0x12)4 octet1 octet1 octet(0x13)1 octet1 octet1 octet(0x14)2 octet

心率

数据长度 Data Lenth（n octet）心率 Heartrate Key心率 Heartrate数据长度 Data Lenth（n octet）最大心率 Max HR Key最大心率 Max HR数据长度 Data Lenth（n octet）平均心率 AVG HR Key平均心率 AVG HR数据长度 Data Lenth（n octet）最大心率 % MAX HR Key最大心率 % MAX HR数据长度 Data Lenth（n octet）阈值心率 LTHR Key阈值心率 LTHR
UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8
1 octet1 octet(0x15)1 octet1 octet1 octet(0x16)1 octet1 octet1 octet(0x17)1 octet1 octet1 octet(0x18)1 octet1 octet1 octet(0x19)1 octet

踏频

数据长度 Data Lenth（n octet）踏频 Cadence Key踏频 Cadence数据长度 Data Lenth（n octet）最高踏频 Max Cadence Key最高踏频 Max Cadence数据长度 Data Lenth（n octet）平均踏频 AvgCadence Key平均踏频 AvgCadence
UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8
1 octet1 octet(0x1a)1 octet1 octet1 octet(0x1b)1 octet1 octet1 octet(0x1c)1 octet

功率

数据长度 Data Lenth（n octet）功率 Power Key功率 Power数据长度 Data Lenth（n octet）最大功率 Max Power Key最大功率 Max Power数据长度 Data Lenth（n octet）3秒平均功率 3s Avg Power Key3秒平均功率 3s Avg Power数据长度 Data Lenth（n octet）10秒平均功率10s Avg Power Key10秒平均功率10s Avg Power数据长度 Data Lenth（n octet）30秒平均功率30s Avg Power Key30秒平均功率30s Avg Power
UINT8UINT8UINT8UINT8UINT8UINT16UINT8UINT8UINT16UINT8UINT8UINT16UINT8UINT8UINT16
1 octet1 octet(0x1d)1 octet1 octet1 octet(0x1f)2 octet1 octet1 octet(0x20)2 octet1 octet1 octet(0x21)2 octet1 octet1 octet(0x22)2 octet

功率

数据长度 Data Lenth（n octet）功能阈值功率FTP Key功能阈值功率FTP数据长度 Data Lenth（n octet）标准化功率 NP Key标准化功率 NP
UINT8UINT8UINT8UINT8UINT8UINT8
1 octet1 octet(0x23)1 octet1 octet1 octet(0x24)1 octet

经纬度

数据长度 Data Lenth（n octet）纬度 lat Key纬度 lat Key数据长度 Data Lenth（n octet）经度 lon Key经度 lon
UINT8UINT8UINT32UINT8UINT8UINT8
1 octet1 octet(0x24)4 octet1 octet1 octet(0x25)4 octet

4.6.7 Dynamic Navi Data 定义​

数据结构如图所示，每个结构由数据长度，数据类型，数据值组成 数据定义

导航数据类型定义

key值Title定义Data Type
0Navi State导航状态UINT8
1到下一个导航点剩余距离UINT32
2到下一个导航点剩余预估时间UINT32
3到终点剩余距离UINT32
4到终点预估时间UINT32
5Slope Vertical Distance当前坡的剩余爬升距离UINT32
6Slope Horizontal Distance当前坡距离坡顶距离UINT32
7当前坡的剩余预估时间UINT32
8Level坡度评级UINT8
9Maneuver航向UINT8
10Street Name路名

所有数据类型的示例如下表

Flags数据长度 Data Lenth（n octet）导航状态Key导航状态数据长度 Data Lenth（n octet）到下一个导航点剩余距离Key到下一个导航点剩余距离数据长度 Data Lenth（n octet）到下一个导航点剩余预估时间Key到下一个导航点剩余预估时间数据长度 Data Lenth（n octet）到终点剩余距离Key到终点剩余距离数据长度 Data Lenth（n octet）到终点预估时间Key到终点预估时间数据长度 Data Lenth（n octet）当前坡的剩余爬升距离Key当前坡的剩余爬升距离数据长度 Data Lenth（n octet）当前坡的剩余爬升距离Key当前坡距离坡顶距离数据长度 Data Lenth（n octet）当前坡的剩余预估时间Key当前坡的剩余预估时间数据长度 Data Lenth（n octet）坡度评级Key坡度评级数据长度 Data Lenth（n octet）Maneuver航向 KeyManeuver航向数据长度 Data Lenth（n octet）路名Key路名
TypeUINT8UINT8UINT8UINT8UINT8UINT8UINT32UINT8UINT8UINT32UINT8UINT8UINT32UINT8UINT8UINT32UINT8UINT8UINT32UINT8UINT8UINT32UINT8UINT8UINT32UINT8UINT8UINT8UINT8UINT8UINT8UINT8UINT8
Size1 octet1 octet1 octet(0x00)1 octet1 octet1 octet(0x01)4 octets1 octet1 octet(0x02)4 octets1 octet1 octet(0x03)4 octets1 octet1 octet(0x04)4 octets1 octet1 octet(0x05)4 octets1 octet1 octet(0x06)4 octets1 octet1 octet(0x07)4 octets1 octet1 octet(0x08)1 octet1 octet1 octet(0x09)1 octet1 octet1 octet(0x0a)max 64 octets

4.6.8 Notification Data 数据类型​

Data type定义描述
0x00Telephone电话
0x01Message短信
0x02WX微信
0x03QQQQ

5. Bluetooth Ymodel Service

5.1 概述​

Ymodel蓝牙通信协议（以下简称本协议）用于App和设备进行文件传输。我们定义传输服务以及三个数据传输通道，智能设备通过实现必须的服务和通道来与行者APP进行数据通信与传输。

5.2 蓝牙服务和特征​

本协议是基于开放式的服务通道，服务通道UUID为： 0x6E400001-B5A3-F393-E0A9-E50E24DCCA9E 在该服务下，我们定义了三个基础特征来完成数据通信和命令控制。

特征名UUID描述属性
命令0x6E400004-B5A3-F393-E0A9-E50E24DCCA9E命令特征，用于APP和硬件之间发送和接受命令Read&Write
接受数据0x6E400003-B5A3-F393-E0A9-E50E24DCCA9E用于APP接受硬件数据Notify
发送数据0x6E400002-B5A3-F393-E0A9-E50E24DCCA9E用于APP向智能硬件发送数据Write

5.3 控制命令​

5.3.1 命令定义​

命令UUID 0x6E400004-B5A3-F393-E0A9-E50E24DCCA9E，手机端和智能设备端命令的通信，用于发起传输请求，控制以及状态表示，属性包含NOTIFY和WRITE。

  • 最大长度20个字节

  • 包括校验码、内容和校验异或值(XOR)

  • 校验异或值(XOR)

  • 无论手机端向设备端Write，还是设备端向手机端Notify,都使用此结构

OpcodeConcentChecksum（XOR）
1Byten Byte (n <= 18)1Byte

命令结构表

5.3.2 命令表​

命令名Code描述
空闲状态命令0x04IDLE
文件获取命令0x05APP向智能硬件请求发送文件
文件获取传输中状态0x06智能硬件正在向APP传输文件
文件发送命令0x07智能硬件向APP请求发送文件
文件发送传输中状态0x08APP正在向智能硬件传输文件
停止传输命令0x1FAPP主动停止文件传输命令
错误状态0x11设备错误:命令格式错误/命令校验错误/不支持的命令
错误状态0x12设备错误:无此文件
错误状态0x13设备错误:内存不足
错误状态0x14设备错误:非空闲状态
错误状态0x15设备错误:文件解析失败
错误状态0x1Ftimeout 设备无响应，发送命令10秒底层为返回，或者底层超时上发
状态命令0xFF获取当前智能硬件设备状态命令

命令内容Content：内容一般为文件名，如 panel.json,.json *.txt。若为空，则补一个字节 0x00。

  • 注:发送 panel.json 获取表盘布局配置。。

校验和Checksum：命令和内容从 1 至 n-1 的异或校验值（xor）。

5.3.3 检查设备状态是否空闲FF命令流程(命令下发实例)​

1.正常流程：App下发ff命令，设备处于空闲状态，回复04命令，表示设备空闲，可以执行其他命令，app继续下发其他命令

2.异常流程（Timeout）：App下发ff命令，等待超时（15s）,如果超时了，App继续下发04命令，设备接受到04命令，终止当前传输任务，回到空闲状态，然后回复04，App接收到04，继续执行其他命令

3.异常流程（Error）:App下发ff命令，设备回复错误命令（0x11-0x15参考命令表定义），App提示报错

  • 注: ff 命令是请求设备状态命令；04命令是IDLE,空闲中命令（App下发时，是让设备置为空闲）；错误命令0x11-0x15参考命令表4.2

命令交互时序图 如图，列举了所有交互情况，在文件传输流程前执行

5.4 文件传输​

5.4.1 传输流程​

通过文件命令，进入文件传输流程，为了保障文件高效稳定的传输，基于 Ymodem 协议，且数据区大小固定为 128 字节（可扩展为1024），具体的数据包格式如下(因为 BLE 的 20 字节限制，所以在传输和接受时需要做拼包和拆包处理)。

数据包开始序列号序列号补码数据区CRC 高字节CRC 低字节
SOH01FE................
1Byte1Byte1Byte128Byte1Byte1Byte

协议传输的完整的握手过程

APP获取智能设备文件

Step智能硬件Phone APP
1Command:0x05 2015.fit
2Command:0x06 2015.fit
3Send(0002发送数据 ):‘C’
4Send(0003发送数据 ):SOH 00 FF “2015.fit” “xxx” CRC CRC
5Send:ACK
6Send:‘C’
7Send:SOH 01 FE Data[128] CRC CRC
8Send:ACK
Send:SOH 02 FD Data[128] CRC CRC
Send:ACK
Send:SOH 03 FC Data[128] CRC CRC
Send:ACK
Send:SOH 01 FE Data[100] NUL[28] CRC CRC
Send:ACK
9Send:EOT
10Send:NAK
11Send:EOT
12Send:ACK
13Command:0x04

APP向智能设备传数据包

StepPhone APP智能硬件
1Command(0001):0x07 “setting.json”
2Command(0001):0x08 “setting.json”
3Send(发送数据 0003):‘C’
4Send(发送数据 0002):SOH 00 FF “setting.json” “xxx” CRC CRC
5Send:ACK
6Send:‘C’
7Send:SOH 01 FE Data[128] CRC CRC
8Send:ACK
Send:SOH 02 FD Data[128] CRC CRC
Send:ACK
Send:SOH 01 FC Data[128] CRC CRC
Send:ACK
Send:SOH 01 FE Data[100] NUL[28] CRC CRC
Send:ACK
9Send:EOT
10Send:NAK
11Send:EOT
12Send:ACK
13Command(0001):0x04 /0x15

文件传输流程

智能硬件端: 发送方

Phone APP: 接收方

发送需要获取的文件 Command 后 第一步先由接收方，发送一个字符'C'，开启传输 发送方收到'C'后，发送第一帧数据包，内容如下:

SOH 00 FF “2015.fit” “xxx” CRC

第 1 字节 SOH:表示本包数据区大小有 128 字节。

第 2 字节 00:编号，第一包为 00,第二包为 01，第三包为 02 依次累加。到 FF 后继续从 0 循环递增。

第 3 字节 FF: 编号的反码。 编号为 00 对应 FF，为 01 对应 FE，以此类推。

第 4 字节到最后两字节:第 1 字节为 SOH 表示有 128 字节，为 STX 时有 1024 字节，这部 分为数据区。“2015.fit” 文件名，在文件名后还有文件 xxx，在文件名和文件大小之后，如果 不满 128 字节，以 0 补满。

最后两字节:只有数据部分参与了校验 CRC,不包括头和编码部分，16 位 CRC 效验，高字节 在前，低字节在后。

接收方收到第一帧数据包后，发送 ACK 正确应答。

然后再发送一个字符'C', 上面接收方只是收到了一个文件名，现在正式开启文件传输， 发送方收到'C'后，开始发送第二帧，第二帧中的数据存放的是文件的第一包数据。 接收方收到数据校验成功后，发送一个 ACK 然后等待下一包数据传送完毕，继续 ACK 应答。 直到所有数据传输完毕。

若数据校验失败，则返回 NAK，发送端重发，重发次数超过 5 次则直接退出发送 若最后一包数据不足 128 字节，则以 0 补满数据传输完毕后，发送方发 EOT，第一次接收方以 NAK 应答，进行二次确认。 发送方收到 NAK 后，重发 EOT，接收方第二次收到结束符，就以 ACK 应答。

发送方必须等待接受方的 ACK 或者 NCK 才会发送下一个数据包，若发送方 5s 内没有收到 ACK/NCK 或者重发次数超过 5 次则直接退出发送，并由发送方将 Command 状态置为空闲。

状态常量定义如下:

状态Code描述
SOH0x01start of 128-byte data packet
STX0x02start of 1024-byte data packet
EOT0x04end of transmission
ACK0x06acknowledge
NAK0x15negative acknowledge

Ymodel流程图

5.7 蓝牙4.2/5.0 扩展支持​

蓝牙组织自4.2开始，支持数据包长度的扩展，可以自定义最大244MTU的数据包传输。本节部分通过新的扩展提高单包字节数来提交数据传输效率。

  • LE Data Packet Length Extension (BT v4.2)

  • LE 2M PHY (BT v5.0)

启用DLE

  1. 主从设备都需要支持Bluetooth 4.2及以上规范iPhone 设备需要iPhone 6以及以上版本；Android视设备而定

  2. 主从设备支持 LE Data Packet Length Extension 链路层特性

  3. 主从设备通过发送LL_LENGTH_REQ命令来启动DLE支持的数据长度更新流程，该命令通过LL_LENGTH_RSP返回完成握手过程。在数据长度更新过程中，主从协商以下四个值：

1. connMaxTxOctets 可以在单个链路层数据包中发送的有效载荷字节数​
2. connMaxTxTime 可以主动传输单个链路层数据包的时间长度（微秒）​
3. connMaxRxOctets 在单个链路层数据包中可以接收的有效载荷字节数​
4. connMaxRxTime 可以主动接收单个链路层数据包的时间长度（微秒）​

通过握手后，硬件设备将可以响应的最大MTU数同步发送给手机端。

5.8 用户信息文件​

user_profile.json

ObjectTypeDefault ValueRangeDescription
MAXHRUint1800~255最大心率

sample:

{
  "version": "2.0.0",
  "device_model": "XL",
  "sn": "xxxx.xxxx",
  "updated_at": 1233676623,
  "user_profile": {
    "MAXHR": 180
  }
}

5.9 表盘设置文件​

panel.json配置文件定义

页面定义page

ObjectTypeDefault ValueDescription
indexUint页面索引
pidUint1页面模式
items[item]表盘元素数组
countUint表盘元素数组数量
piditem_countDescription
01表盘中只显示一个数据
12表盘中显示两个数据

表盘中item定义如下： 默认：5页，每页1-2个数据。用户可在app中自定义显示的数据。 出厂默认的5页：时钟、实时速度、运动时间、运动里程、导航信息 实时速度、运动时间、运动里程、实时心率、实时踏频、导航信息、海拔、实时坡度、累计爬升、当前时钟,最多配置5项

item idtypetitle中文名称default valueunitdescriptionsize limit
1001Moving Time运动时间0ssecond
1031Current Time当前时钟0s时钟
2002Distance距离0.0mm/km/mi
3003Speed实时速度0.0m/s
4004Elevation海拔0mm/ft
4034Grade实时坡度0.0%
4044Elevation Gain累计爬升0.0m
5005Heartrate实时心率0BPM
6006Cadence实时踏频0RPM
8018Navi Instruction导航指引""String

sample:

{
  "version": "2.0.0",
  "device_model": "XL",
  "sn": "xxx.xxx",
  "updated_at": 1233676623,
  "pages_count": 3,
  "pages": [
    {
      "index": 0,
      "pid": 0,
      "count": 1,
      "items": [
        300
      ]
    },
    {
      "index": 1,
      "pid": 1,
      "count": 2,
      "items": [
        200,
        400
      ]
    },
    {
      "index": 2,
      "pid": 0,
      "count": 1,
      "items": [
        500
      ]
    }
  ]
}


出厂文件

{
  "version": "2.0.0",
  "device_model": "XL",
  "sn": "xxx.xxx",
  "updated_at": 1718782574,
  "pages_count": 5,
  "pages": [
    {
      "index": 0,
      "pid": 0,
      "count": 1,
      "items": [
        103
      ]
    },
    {
      "index": 1,
      "pid": 0,
      "count": 1,
      "items": [
        300
      ]
    },
    {
      "index": 2,
      "pid": 0,
      "count": 1,
      "items": [
        100
      ]
    },
    {
      "index": 3,
      "pid": 0,
      "count": 1,
      "items": [
        200
      ]
    },
    {
      "index": 4,
      "pid": 0,
      "count": 1,
      "items": [
        801
      ]
    }
  ]
}

6 接入流程

6.1 链接流程​

TODO