Skip to content

Livox SDK Communication Protocol HAP

Livox-SDK edited this page Sep 14, 2022 · 28 revisions

Livox HAP SDK 通讯协议

版本记录
时间 版本 描述
20220519 v1.0 初始化版本
20220530 v1.1 1.合并状态与参数key_value信息字段
2.信息推送命令支持推送雷达参数信息及状态信息
20220602 v1.2 1.增加log相关命令
20220622 v1.3 1.56000端口仅支持广播发现命令,广播发现命令ack新增当前雷达的控制指令字段
20220628 v1.4 1. 更新工作状态描述
20220629 v1.4.1 1. key value list 增加 firmware type 新键值
20220914 v1.4.2 1. 增加status_code

[TOC]

1 协议概述

1.1 数据类型

用户和雷达之间有两种类型的数据协议,功能分别如下:

采样数据协议:

控制指令协议:

  • 配置和查询雷达的参数、雷达复位;

  • 雷达状态推送、查询;

  • 升级相关;

    详见 指令详解

两种协议都被封装在UDP的数据段中,协议数据为小端序

1.2 雷达工作状态

状态切换逻辑说明:

  1. 正在自检 状态耗时5s,正在启动 状态耗时最长10s;
  2. 虚线状态(自检状态、电机启动、电机停止、错误状态)为用户不可主动切换的目标状态;
  3. 虚线箭头为雷达根据外界控制条件、外部环境、内部实际工况自动实现的逻辑;
  4. 任意状态下(非错误状态),检测到错误则自动切换至错误状态;
  5. 任意状态下接收到用户请求进入休眠状态,满足休眠条件则进入休眠状态;
  6. 用户请求升级后,雷达自动跳转到升级状态(图中未显示);
  7. 雷达状态具体定义如下:
状态 描述
采样状态 0x01 雷达在此状态下发送点云&IMU数据
待机状态 0x02 雷达处于空闲状态,等待用户操作
休眠状态
0x03
HAP(TX)版本不支持该状态,仅HAP(T1)版本支持;
用户请求雷达进入休眠状态后,雷达检测网线是否断开,若断开,雷达切断
主控电源,进入休眠状态 (仅保持雷达以太网PHY处于工作状态,以检测以太网唤醒信号)
错误状态 0x04 雷达识别到错误,自动切换至本状态
自检状态 0x05 上电时雷达自动进入该模式进行上电自检,若有异常则自动切换
错误状态, 反之切换到 待机状态
电机启动 0x06 雷达处于 待机状态 时,若用户请求 采样状态,则雷达先进入
本状态启动电机电机转速稳定后,雷达自动切换到 采样状态
电机停止 0x07 雷达处于 采样状态 时,若用户请求 待机状态,则雷达先进入本状态,
电机停止运转后,雷达自动切换到 待机状态
升级状态 0x08 用户请求升级后,雷达状态自动切换到本状态

1.3 端口说明

按照数据类型分类,对应的源端口和目的端口说明:

数据类型 方向 lidar host 传输类型 协议
设备类型查询 lidar <---->host 56000 any broadcast UDP
雷达信息
控制相关
lidar<--->host 56000 any unicast UDP
点云数据 lidar --->host 57000 57000 unicast(default) UDP
IMU数据 lidar --->host 58000 58000 unicast(default) UDP
Log lidar<---> host 59000 59000 unicast UDP

Note:

56000作为livox雷达固定监听端口,主要用于上位机通过广播查询设备, 仅支持设备类型查询命令(cmd_id:0x0000),上位机通过此端口获取雷达具体设备类型。此命令响应通过广播回复,以便于上位机与雷达IP不在同一网段时,上位机仍可识别到雷达。

2 点云&IMU数据协议

2.1 协议格式

雷达输出点云数据格式:

字段 偏移(byte) 长度 描述
version 0 1 包协议版本:当前为0
length 1 2 从version开始的整个UDP数据段长度
time_interval 3 2 帧内点云采样时间(单位0.1us)
这帧点云数据中最后一个点减去第一个点时间
Note: imu数据该位保留位0
dot_num 5 2 当前UDP包data字段包含点数目:
点云数据为96,IMU数据为1
udp_cnt 7 2 点云UDP包计数,每个UDP包依次加1,点云帧起始包清0
frame_cnt 9 1 点云帧计数,每帧点云(10Hz/15Hz等)依次加1
对于非重复扫描,此字段无效
Note: HAP该字段为0
data_type 10 1 数据类型,详见 2.3
time_type 11 1 时间戳类型,详见2.2
pack_info 12 1 bit0-1: 功能安全safety_info
0x0:整包可信
0x1:整包不可信;
0x2:非0点可信
bit2-3: tag_type, HAP 固定为0
bit4-7: rsvd
resv 13 11 保留
crc32 24 4 timestamp+data段校验码,使用CRC-32算法(详见-CRC算法说明 )
timestamp 28 8 点云时间戳,详见2.2
data 36 -- 数据信息,详见 2.3

Note:

HAP T1版本不支持IMU功能,仅HAP Tx版本支持IMU功能。

2.2 时间戳

雷达系统支持IEEE 1588v2.0 PTP网络协议同步。

每个数据包中的时间戳代表第一个点云的时间,每个数据包中有n个点云,这n个点云的时间是等间隔的,总间隔时间为 time_interval 的值。

时间戳类型:

时间戳类型 同步源类型 数据格式 说明
0 无同步源,时间戳为雷达开机时间 uint64_t Unit单位: ns
1 gPTP同步,时间戳为master时钟源时间 uint64_t Unit单位: ns

2.3 数据类型

数据类型 回波模式 坐标格式 N 数据频率
IMU Data 0 1 200kHz
Point Cloud Data1 1 Single Return Mode Cartesian Coordinate(32bit) 96 452kHz
Point Cloud Data2 2 Single Return Mode Cartesian Coordinate(16bit) 96 452kHz

IMU Data:

字段 偏移(byte) 数据类型 描述
gyro_x 0 float Unit: rad/s
gyro_y 4 float Unit: rad/s
gyro_z 8 float Unit: rad/s
acc_x 12 float Unit: g
acc_y 16 float Unit: g
acc_z 20 float Unit: g

Point Cloud Data1:

字段 偏移(byte) 数据类型 描述
x 0 int32_t X 轴,unit: mm
y 4 int32_t Y 轴,unit: mm
z 8 int32_t Z 轴,unit: mm
Reflectivity 12 uint8_t Reflectivity
Tag Information 13 uint8_t 详见 2.4

Point Cloud Data2:

字段 偏移(byte) 数据类型 描述
x 0 int16_t X 轴,unit 10mm
y 2 int16_t Y 轴,unit: 10mm
z 4 int16_t Z 轴,unit: 10mm
Reflectivity 6 uint8_t Reflectivity
Tag Information 7 uint8_t 详见 2.4

Note:

  1. There are N samples in each data package.

  2. The default data type of Point Cloud Data is Point Cloud Data1.

2.4 标签信息

tag_type 描述
0 bit [6-7]: 回波序号
00:第0回波
01:第1回波
10:第2回波
11:第3回波
bit [4-5]:基于其他类别的点属性:(不同产品类别存在差异)
00: 置信度优(正常点)
01: 置信度中
10: 置信度差
11: 置信度最差
bit [2-3]: 基于能量强度的点属性:
00: 置信度优(正常点)
01: 置信度中
10: 置信度差
11: 置信度最差
bit [0-1]: 基于空间位置的点属性:
00: 置信度优(正常点)
01: 置信度中
10: 置信度差
11: 置信度最差

3 控制协议

3.1 协议格式

字段 偏移(byte) 长度 描述
sof 0 1 起始字节,固定为 0xAA
version 1 1 协议版本,当前为0
length 2 2 数据帧长度
表示从sof开始到整个data段结束的所有字节数,最大值: 1400
seq_num 4 4 每条新的REQ请求消息此字段递增1;
ACK回复消息此字段与REQ相同,可用于消息匹配;
cmd_id 8 2 不同类型的消息通过此字段进行区分,详见指令ID
cmd_type 10 1 消息类型:
0x00: REQ,主动发送的请求消息;
0x01: ACK,对REQ请求的回复消息;
sender_type 11 1 消息发送设备类型:
0:上位机发送消息
1: 雷达发送消息
resv 12 6 保留
crc16 18 2 包头校验码,校验内容为从sof开始到crc_16(不包括)的共18字节数据, 使用CRC-16/CCITT-FALSE算法(see CRC Algorithm )
crc32 20 4 crc32校验码,data字段校验码, 使用CRC-32算法(see CRC Algorithm )
data 24 n 指令详解

3.2 指令ID

CMD类型 cmd_id 功能
设备类型查询 0x0000 广播发现
雷达信息 0x0100 参数信息配置
0x0101 雷达信息查询
0x0102 雷达信息推送
控制相关 0x0200 请求设备重启
log相关 0x0300 log文件推送
通用升级 0x0400 请求开始升级
0x0401 固件数据传输
0x0402 固件传输结束
0x0403 获取固件升级状态

4 指令详解

4.1 设备类型查询

0x0000 广播发现

Request

CMD 名称 偏移(byte) 数据类型 描述
data NULL

ACK

ACK 名称 偏移(byte) 数据类型 描述
data ret_code 0 uint8_t reture code:
(see 返回码说明 )
dev_type 1 uint8_t lidar type
serial_number 2 uint8_t[16] lidar SN
lidar_ip 18 uint8_t[4] lidar IP address
sample: AA.BB.CC.DD
user_ip[0] = AA
user_ip[1] = BB
user_ip[2] = CC
user_ip[3] = DD
cmd_port 22 uint16_t lidar command port
HAP is 56000(can' t be changed)

4.2 雷达信息

0x0100 参数信息配置

Request

CMD 名称 偏移(byte) 数据类型 描述
data key_num 0 uint16_t 要配置的key的数量
rsvd 2 uint16_t
key_value_list 4 key_value_list[N]

key_value_list 格式定义如下:

数据 偏移(byte) 类型 描述
key 0 uint16_t key number
length 2 uint16_t key数据长度
value 4 --

ACK

ACK 名称 偏移(byte) 数据类型 描述
data ret_code 0 uint8_t return code:
(see 返回码说明 )
error_key 1 uint16_t if the ret_code is not LVX_RET_SUCCESS
the error_key shows which key is error

0x0101 雷达信息查询

Request

CMD 名称 偏移(byte) 数据类型 描述
data key_num 0 uint16_t 要查询的key的数量
rsvd 2 uint16_t
key_list 4 --

The key type in the key_list

DATA 名称 偏移(byte) 数据类型
key 0 uint16_t key number

ACK

ACK 名称 偏移(byte) 数据类型 描述
data ret_code 0 uint8_t return code:
(see 返回码说明 )
key_num 1 uint16_t key的数量
key_value_list 3 --

0x0102 雷达信息推送

雷达主动推送

CMD 名称 偏移(byte) 数据类型 描述
data key_num 0 uint16_t
rsvd 2 uint16_t
key_value_list 4 --

HAP 每1s推送如下信息:

  • 0x800E

  • 0x8006

  • 0x800F

KEY-VALUE定义

the format of the key_value_list

DATA 名称 偏移(byte) 数据类型
key 0 uint16_t key number
length 2 uint16_t key数据长度
value 4 --

key_value_list对应的具体含义如下:

KEY 名称 长度 类型 描述 是否支持如下命令
0x0000 pcl_data_type 1 uint8_t 雷达点云格式,详见数据类型
0x01: 直角坐标(32bits)
0x02: 直角坐标(16bits)
Note: 采样中不允许设置该值, 重启后恢复默认0x01
0x100: Y
0x101: Y
0x102: N
0x0001 pattern_mode 1 uint8_t 空间扫描模式:
0x00: 非重复扫描
0x01: 重复扫描
Note: 设置后需重启雷达,默认0x00
0x100: Y
0x101: Y
0x102: N
0x0003 point_send_en 1 uint8_t 点云发送控制:
0x00:进入工作模式发送点云;
0x01:进入工作模式不发送点云
Note:功能实时生效,重启后恢复默认0x00
0x100: Y
0x101: Y
0x102: N
0x0004 lidar_ipcfg 12 uint8_t[12] 雷达IP地址配置
雷达IP地址:AA.BB.CC.DD
data[0]: AA
data[1]: BB
data[2]: CC
data[3]: DD
雷达IPV4 子网掩码
data[4-7]
雷达IPV4 网关
data[8-11]
Note: 设置后需重启雷达,默认为192.168.1.100
0x100: Y
0x101: Y
0x102: N
0x0006 ponitcloud_host_ipcfg 8 uint8_t[8] 雷达点云数据推送的ip地址配置
data[0-3]点云数据目的IP地址:AA.BB.CC.DD
data[4-5]推送消息目的端口
data[6-7]推送消息源端口
Note:
1. 不会保存设置的IP到flash中,如需指定IP地址,则每次上电时均需配置
2. IMU数据推送IP地址也会更新为该地址
3. 不支持端口设置,只支持端口查询,HAP点云端口固定为57000
4. 若不设置该值,雷达将自动识别目的IP
5. IP不能设置为0.0.0.0或者255.255.255.255
0x100: Y
0x101: Y
0x102: N
0x0007 imu_host_ipcfg 8 uint8_t[8] 雷达点云数据推送的ip地址配置
data[0-3]点云数据目的IP地址:AA.BB.CC.DD
data[4-5]推送消息目的端口
data[6-7]推送消息源端口
Note:
1. 不会保存设置的IP到flash中,如需指定IP地址,则每次上电时均需配置
2. 点云数据推送IP地址也会更新为该地址
3. 不支持端口设置,只支持端口查询,IMU端口固定为58000
4. 若不设置该值,雷达将自动识别目的IP
5. IP不能设置为0.0.0.0或者255.255.255.255
0x100: Y
0x101: Y
0x102: N
0x0012 install_attitude 24 雷达在用户装置上的安装位置;
雷达内部不处理此信息;
格式如下:
{
float roll_deg;
float pitch_deg;
float yaw_deg;
int x_mm;
int y_mm;
int z_mm;
}
0x100: Y
0x101: Y
0x102: N
0x0013 blind_spot_set 4 uint32_t 盲区范围设置(cm)
Note:
1. 范围50~200cm, 默认为50cm
2. 保存在ROM中,实时生效
3. 不建议在开采样状态下设置该值
0x100: Y
0x101: Y
0x102: N
RSVD
0x001A work_tgt_mode 1 uint8_t 雷达目标工作模式(即目标工作状态),详见雷达状态 0x100: Y
0x101: Y
0x102: N
0x001B glass_heat 1 uint8_t 窗口加热开启选项:
0:关闭
1:开启
Note:
1. 单次最长只能开启加热3分钟,否则自动退出窗口加热模式,且本次上电周期内不再响应加热请求, 默认为0x00
2. 错误状态下不会进行加热
0x100: Y
0x101: Y
0x102: N
0x001C imu_data_en 1 uint8_t 0: IMU数据推送关闭
1: IMU数据推动使能
Note:
HAP Tx版本默认为0x01
HAP T1版本该参数无效
0x100: Y
0x101: Y
0x102: N
0X001D fusa_en 1 uint8_t 0: 关闭fusa诊断功能
1: 开启fusa诊断功能
Note: 重启后生效, 默认为0x00
0x100: Y
0x101: Y
0x102: N
0x8000 sn 16 uint8_t[16] 字符串类型(不足16位使用 '\0' 补齐)
雷达SN(不足16位使用 '\0' 补齐)
0x100: Y
0x101: Y
0x102: N
0x8001 product_info 64 char[64] 字符串类型(不足32位使用 '\0' 补齐)
雷达类型+雷达生产日期
示例: "Mid-360 2021/12/01"
0x100: N
0x101: Y
0x102: N
0x8002 version_app 4 uint8_t[4] App固件版本号:aa.bb.cc.dd
version_info[0]: aa
version_info[1]: bb
version_info[2]: cc
version_info[3]: dd
0x100: N
0x101: Y
0x102: N
0x8003 version_loader 4 uint8_t[4] Loader固件版本号:aa.bb.cc.dd
version_info[0]: aa
version_info[1]: bb
version_info[2]: cc
version_info[3]: dd
0x100: N
0x101: Y
0x102: N
0x8004 version_hardware 4 uint8_t[4] 硬件版本号:aa.bb.cc.dd
version_info[0]: aa
version_info[1]: bb
version_info[2]: cc
version_info[3]: dd
0x100: N
0x101: Y
0x102: N
0x8005 mac 6 uint8_t[6] 雷达MAC地址:aa:bb:cc:dd:ee:ff
data[0]: aa
data[1]: bb
data[2]: cc
data[3]: dd
data[4]: ee
data[5]: ff
0x100: N
0x101: Y
0x102: N
0x8006 cur_work_state 1 uint8_t 当前工作状态,详见雷达状态 0x100: N
0x101: Y
0x102: Y
0x800D status_code 32 uint8_t[32] 每个BIT对应一个故障:
0= no error
1= error
详细信息见(https://github.com/Livox-SDK/Livox-SDK2/wiki/hap-status-code)
0x800E lidar_diag_status 2 uint16_t 雷达诊断状态码
模块状态异常等级:
0: normal
1: warning
2: error
3: safety_err
struct diag_status{
bit[0-3]: 系统模块(主控软硬件相关)
bit[4-7]: 扫描模块(光路控制及角度检测相关)
bit[8-11]: 测距模快(发射/接收控制及外围电路、原始信号处理相关)
bit[12-15]: 通信模块(通讯相关软硬件,时间同步)
}
0x100: N
0x101: Y
0x102: Y
0x800F lidar_flash_status 1 uint8_t flash状态:
0: idle
1:busy
Note: 请求重启或者给雷达断电前,需确保FLASH非busy状态,否则可能导致数据丢失
0x100: N
0x101: Y
0x102: Y
0x8010 fw_tpye 1 uint8_t 固件类型:
0= loader
1= app1
2= app2
0x100: N
0x101: Y
0x102: N

4.3 控制相关

0x0200 请求设备重启

Request

CMD 名称 偏移(byte) 类型 描述
data timeout 0 uint16_t reboot time delay,the uint is ms
the range is 100ms~2000ms

ACK

ACK 名称 偏移(byte) 类型 描述
data ret_code 0 uint8_t return code:
(详见 返回码说明 )

4.4 log

0x0300 log文件推送

Request:Lidar

CMD 名称 偏移(byte) 数据类型 描述
data log_type 0 uint8_t 日志类型:
0 : 实时log
1 : 实时异常log
2 : 实时 raw data log
3 : flash log
file_index 1 uint8_t 文件索引号
file_num 2 uint8_t log_type为flash log此字段有效,表示flash log文件数目
flag 3 uint8_t bit 0:
值为1表示需要ack
bit 1:
值为1表示创建文件
bit 2:
值为1表示结束文件
注:雷达发送创建文件,发送配置信息头,结束文件数据包时,需要置位ack位
timestamp 4 uint32_t unix时间戳,表示从1970年1月1日00:00:00所经过的秒数。
上位机创建log文件时,通过以下格式命名log文件
log_<log_type_name>_<file_index>_<system_time>.dat
示例: log_fully_log_1_20220613203140.dat
<system_time>为timestamp转换后的系统时间。假如雷达返回的timestamp为0,上位机则不对timestamp进行转换,直接使用上位机系统时间进行命名
rsvd 8 uint16_t
trans_index 10 uint32_t 传输索引号
log_data_len 14 uint16_t 日志内容长度
log_data 16 -- 日志内容:
需要追加到文件尾

ACK:HOST

ACK 名称 偏移(byte) 数据类型 描述
data ret_code 0 uint8_t return code:
(详见 返回码说明 )
log_type 1 uint8_t
file_index 2 uint8_t
trans_index 3 uint32_t

4.5 通用升级

0x0400 请求开始升级

Request

CMD 名称 偏移(byte) 数据类型 描述
data firmware_type 0 uint8_t 固件类型:
0:大包固件
1:雷达固件
2:其他固件
Note: HAP该字段保留
encrypt_type 1 uint8_t 固件加密类型:
0:None encrypt
1:AES128
2:AES256
3:DES
4:3DES
firmware_length 2 uint32_t 固件总长度
dev_type 6 uint8_t 设备类型:
10:HAP

ACK

ACK 名称 偏移(byte) 数据类型 描述
data ret_code 0 uint8_t return code:
(详见 返回码说明 )

0x0401 固件数据传输

Request

CMD 名称 偏移(byte) 数据类型 描述
data firmware_offset 0 uint32_t
current_length 4 uint32_t
encrypt_type 8 uint8_t
rsvd 9 uint8_t[3]
data 12 uint8_t[n] 固件内容

ACK

ACK 名称 偏移(byte) 数据类型 描述
data ret_code 0 uint8_t return code:
(详见 返回码说明 )
current_offset 1 uint32_t
received_length 5 uint32_t

0x0402 固件传输结束

Request

CMD 名称 偏移(byte) 数据类型 描述
data checksum_type 0 uint8_t
checksum_length 1 uint8_t
checksum_data 2 uint8_t[n]

ACK

ACK 名称 偏移(byte) 数据类型 描述
data ret_code 0 uint8_t return code:
(详见 返回码说明 )

0x0403 获取固件升级状态

Request

CMD 名称 偏移(byte) 数据类型 描述
data NULL

ACK

ACK 名称 偏移(byte) 数据类型 描述
data ret_code 0 uint8_t return code:
(详见 返回码说明 )
upgrade_progress 1 uint8_t upgrade progress:
0 ~ 100%

5 用户指南

  1. 检查雷达网线连接是否正常,给雷达供电(12V直流);
  2. 上位机发送广播发现指令,获取雷达IP地址,控制命令端口号等信息用于下面步骤的信息发送;
  3. 若需要对雷达进行参数配置,须在雷达进入开采样状态前进行。若配置的参数需要保存到flash中(如雷达IP扫描模式配置),配置完成后需重启雷达,重启完成再查询相关参数是否已生效;
  4. 上位机通过0x100指令配置work_tgt_mode为0x01(采样状态), 使雷达开启采样;
  5. 上位机获取点云数据&IMU数据;
  6. 上位机通过0x100指令配置work_tgt_mode为0x02(待机状态), 使雷达停止采样;
  7. 重启或断电雷达。在进行此操作前需查询雷达fls_status,若雷达处于busy状态,需等待雷达完成存储后再重启或断电。

6 附录

Return Code

名称 描述
LVX_RET_SUCCESS 0x00 执行成功
LVX_RET_FAILURE 0x01 执行失败
LVX_RET_NOT_PERMIT_NOW 0x02 当前状态不支持
LVX_RET_OUT_OF_RANGE 0x03 设置值超出范围
LVX_RET_PARAM_NOTSUPPORT 0x20 参数不支持
LVX_RET_PARAM_REBOOT_EFFECT 0x21 参数需重启生效
LVX_RET_PARAM_RD_ONLY 0x22 参数只读,不支持写入
LVX_RET_PARAM_INVALID_LEN 0x23 请求参数长度错误,或ack数据包超过最大长度
LVX_RET_PARAM_KEY_NUM_ERR 0x24 参数key_num和key_list不匹配
LVX_RET_UPGRADE_PUB_KEY_ERROR 0x30 公钥签名验证错误
LVX_RET_UPGRADE_DIGEST_ERROR 0x31 固件摘要签名验证错误
LVX_RET_UPGRADE_FW_TYPE_ERROR 0x32 固件类型不匹配
LVX_RET_UPGRADE_FW_OUT_OF_RANGE 0x33 固件长度超出范围

CRC Algorithm

CRC algorithm 格式 宽度 多项式 初始值 结果异或 输入反转 输出反转
CRC-16/CCITT-FALSE x^16^ + x^12^ + x^5^ + 1 16 0x1021 0xFFFF 0x0000 false false
CRC-32 x^32^ + x^26^ + x^23^ + x^22^ + x^16^ + x^12^ + x^11^ + x^10^ + x^8^ + x^7^ + x^5^ + x^4^ + x^2^ + x + 1 32 0x04C11DB7 0xFFFFFFFF 0xFFFFFFFF true true

Communication Protocol

o HAP 中文

o HAP English

Livox-Viewer2

o Color Coding Strategy

Clone this wiki locally