# 设备端 MQTT 接入与通信文档

# 1. 连接与认证

设备通过 MQTT 协议与服务端建立连接，需使用指定的认证信息。

服务器地址 (Broker URL)： mqtt://crane-dev.gaiais.com:7883

认证参数示例：

参数	示例值	说明
Client ID	`2gxEAkvMzxdGx5b3.cvt_001`	客户端 ID，用于唯一标识该终端（通常格式为 `ProductKey.DeviceName`）
Username	`cvt_001&2gxEAkvMzxdGx5b3`	用户名，用于认证 MQTT 连接（通常格式为 `DeviceName&ProductKey`）
Password	`987d43cb46105a2c809c5219f67ece4237e3ef62131e3b836d8cb5fe70aece85`	密码，用于认证 MQTT 连接

Topic 所需参数：

ProductKey	`2gxEAkvMzxdGx5b3`	产品唯一标识，用于唯一标识该终端所属的产品
DeviceName	`cvt_001`	设备唯一标识，用于唯一标识该终端

# 2. 设备状态与心跳同步

设备需在开机或关机的时候上传对应报文

上报 Topic： /sys/{productKey}/{deviceName}/thing/state/update

上线心跳 (State = 1)：

{
  "method": "thing.state.update",
  "params": {
    "state": 1
  }
}

下线心跳 (State = 2)：

{
  "method": "thing.state.update",
  "params": {
    "state": 2
  }
}

# 3. 传感器数据上报

设备定期将传感器采集的实时数据上报至云端。

# 3.1 传感器数据上报

上报 Topic: /sys/{productKey}/{deviceName}/thing/property/post

{
  "method": "thing.property.post",
  "params": {
    "wind_speed": 11.1,
    "boom_elevation": 0.19,
    "body_pitch": -0.12,
    "obstacle_front": 2.6605495649949527,
    "obstacle_rear": 0.5,
    "obstacle_left": 2.7301228099146995,
    "obstacle_right": 3.642807893429924,
    "obstacle_top": 3.127299533442788,
    "obstacle_bottom": 2.45007724731956,
    "latitude": 39.907052,
    "longitude": 116.404951,
    "boom_latitude": 39.906914,
    "boom_longitude": 116.405151,
    "chassis_altitude": 45.522,
    "boom_altitude": 47.297,
    "slew_angle": 75.0,
    "slew_speed": 1.6,
    "boom_length": 43.86,
    "boom_tip_height": 0.15,
    "boom_horizontal_projection": 43.86,
    "rtk_quality": 5,
    "satellites_used": 12,
    "hdop": 2.1,
    "gps_timestamp": 1780308372000,
    "obstacle_distance": 0.5,
    "boom_cross_tilt": -1.75,
    "body_roll": 0.94
  }
}

# 3.2 传感器数据字段字典

字段标识符	中文意思	数据类型	取值范围	单位
`wind_speed`	风速	float	0 ~ 70	m/s (米每秒)
`boom_elevation`	吊臂俯仰角	float	-90 ~ 90	° (度)
`body_pitch`	车身俯仰角	float	-90 ~ 90	° (度)
`obstacle_front`	前方避障距离	float	0.03 ~ 20	m (米)
`obstacle_rear`	后方避障距离	float	0.03 ~ 20	m (米)
`obstacle_left`	左侧避障距离	float	0.03 ~ 20	m (米)
`obstacle_right`	右侧避障距离	float	0.03 ~ 20	m (米)
`obstacle_top`	上方避障距离	float	0.03 ~ 20	m (米)
`obstacle_bottom`	下方避障距离	float	0.03 ~ 20	m (米)
`latitude`	车身纬度	double	-90 ~ 90	° (度)
`longitude`	车身经度	double	-180 ~ 180	° (度)
`boom_latitude`	吊臂纬度	double	-90 ~ 90	° (度)
`boom_longitude`	吊臂经度	double	-180 ~ 180	° (度)
`chassis_altitude`	车身海拔高度	double	-500 ~ 9000	m (米)
`boom_altitude`	吊臂海拔高度	double	-500 ~ 9000	m (米)
`slew_angle`	回转角度	float	0 ~ 360	° (度)
`slew_speed`	回转速度	float	-60 ~ 60	°/s (度每秒)
`boom_length`	大臂长度	float	0 ~ 100	m (米)
`boom_tip_height`	臂尖高度	float	-10 ~ 100	m (米)
`boom_horizontal_projection`	大臂水平投影	float	0 ~ 100	m (米)
`rtk_quality`	RTK定位质量	int	0 ~ 5	count (次)
`satellites_used`	使用卫星数	int	0 ~ 40	pcs (个)
`hdop`	水平精度因子	float	0.5 ~ 10	count (次)
`gps_timestamp`	GNSS时间戳	date	-	-
`obstacle_distance`	避障最短距离	float	0.03 ~ 20	m (米)

# 4. 阈值数据通信

用于设备上报当前生效的阈值，以及服务端下发新的阈值配置。

# 4.1 阈值数据上报

上报 Topic： /sys/{productKey}/{deviceName}/thing/property/post

{
  "method": "thing.property.post",
  "params": {
    "threshold": {
      "body_pitch_min": -5.6,
      "body_pitch_max": 5.5,
      "boom_elevation_min": 0.0,
      "boom_elevation_max": 75.0,
      "slew_angle_min": 0.0,
      "slew_angle_max": 360.0,
      "slew_speed_min": -30.0,
      "slew_speed_max": 30.0,
      "boom_length_min": 5.0,
      "boom_length_max": 50.0,
      "boom_tip_height_min": 0.0,
      "boom_tip_height_max": 80.0,
      "obstacle_front": 5.0,
      "obstacle_rear": 3.0,
      "obstacle_left": 4.0,
      "obstacle_right": 4.0,
      "obstacle_top": 10.0,
      "obstacle_bottom": 2.0,
      "fatigue_driving_time_max": 4.0,
      "power_line_dist_min": 3.0,
      "blind_spot_dist_min": 5.0,
      "tilt_angle_l1_max": 3.0,
      "tilt_angle_l2_max": 5.0,
      "tilt_angle_l3_max": 8.0
    }
  }
}

# 4.2 阈值数据下发

下发 Topic：/sys/{productKey}/{deviceName}/thing/property/set

{
  "id": "a33d1abf44e44795bfbc6bf4083f0b3e",
  "reportTime": 1780629753065,
  "deviceId": 88,
  "tenantId": 1,
  "requestId": "a33d1abf44e44795bfbc6bf4083f0b3e",
  "method": "thing.property.set",
  "params": {
    "threshold": {
      "body_pitch_min": -5.3,
      "body_pitch_max": 5.5,
      "boom_elevation_min": 0,
      "boom_elevation_max": 75,
      "slew_angle_min": 0,
      "slew_angle_max": 360,
      "slew_speed_min": -30,
      "slew_speed_max": 30,
      "boom_length_min": 5,
      "boom_length_max": 50,
      "boom_tip_height_min": 0,
      "boom_tip_height_max": 80,
      "obstacle_front": 5,
      "obstacle_rear": 3,
      "obstacle_left": 4,
      "obstacle_right": 4,
      "obstacle_top": 10,
      "obstacle_bottom": 2,
      "fatigue_driving_time_max": 4,
      "power_line_dist_min": 3,
      "blind_spot_dist_min": 5,
      "tilt_angle_l1_max": 3,
      "tilt_angle_l2_max": 5,
      "tilt_angle_l3_max": 8
    }
  }
}

# 4.3 阈值字段数据字典

以下结构体对应 threshold 参数内部的字段解析，包含各字段的中文名称、数据类型、取值范围以及单位：

字段标识符	中文意思	数据类型	取值范围	单位
`body_pitch_min`	车身俯仰角下限	Float	-90 ~ 90	度 (°)
`body_pitch_max`	车身俯仰角上限	Float	-90 ~ 90	度 (°)
`boom_elevation_min`	吊臂俯仰角下限	Float	-90 ~ 90	度 (°)
`boom_elevation_max`	吊臂俯仰角上限	Int/Float	-90 ~ 90	度 (°)
`slew_angle_min`	回转角度下限	Float	0 ~ 360	度 (°)
`slew_angle_max`	回转角度上限	Float	0 ~ 360	度 (°)
`slew_speed_min`	回转速度下限	Float	-60 ~ 60	度每秒 (°/s)
`slew_speed_max`	回转速度上限	Float	-60 ~ 60	度每秒 (°/s)
`boom_length_min`	大臂长度下限	Float	0 ~ 100	米 (m)
`boom_length_max`	大臂长度上限	Float	0 ~ 100	米 (m)
`boom_tip_height_min`	臂尖高度下限	Float	-10 ~ 100	米 (m)
`boom_tip_height_max`	臂尖高度上限	Int/Float	-10 ~ 100	米 (m)
`obstacle_front`	前方距离	Float	0.01 ~ 20	米 (m)
`obstacle_rear`	后方距离	Float	0.01 ~ 20	米 (m)
`obstacle_left`	左侧距离	Float	0.01 ~ 20	米 (m)
`obstacle_right`	右侧距离	Float	0.01 ~ 20	米 (m)
`obstacle_top`	上方距离	Float	0.01 ~ 20	米 (m)
`obstacle_bottom`	下方距离	Float	0.01 ~ 20	米 (m)
`fatigue_driving_time_max`	疲劳驾驶预警	Int	0 ~ 24	小时 (h)
`power_line_dist_min`	近电预警	Float	0 ~ 20	米 (m)
`blind_spot_dist_min`	盲区人员预警	Float	0 ~ 50	米 (m)
`tilt_angle_l1_max`	倾倒风险一级	Float	-90 ~ 90	度 (°)
`tilt_angle_l2_max`	倾倒风险二级	Float	-90 ~ 90	度 (°)
`tilt_angle_l3_max`	倾倒风险三级	Float	-90 ~ 90	度 (°)

# 5. 报警信息上传

等待补充