Add spec docs
This commit is contained in:
John Zhao
parent
4aa6a58797
commit
474126b09c
|
|
@ -790,7 +790,17 @@ WARN_LOGFILE =
|
|||
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
|
||||
# Note: If this tag is empty the current directory is searched.
|
||||
|
||||
INPUT = ../../include
|
||||
INPUT = mainpage.md \
|
||||
specs_data.md \
|
||||
spec_hardware_info.md \
|
||||
spec_image_params.md \
|
||||
spec_imu_params.md \
|
||||
spec_image_data.md \
|
||||
spec_imu_data.md \
|
||||
specs_ctrl.md \
|
||||
spec_control_api.md \
|
||||
spec_control_channel.md \
|
||||
../../include
|
||||
|
||||
# This tag can be used to specify the character encoding of the source files
|
||||
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
|
||||
|
|
|
|||
4
doc/zh-Hans/mainpage.md
Normal file
4
doc/zh-Hans/mainpage.md
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
# MYNT EYE SDK {#mainpage}
|
||||
|
||||
* @subpage specs_data
|
||||
* @subpage specs_ctrl
|
||||
28
doc/zh-Hans/spec_control_api.md
Normal file
28
doc/zh-Hans/spec_control_api.md
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
# 控制 API 说明 {#spec_contorl_api}
|
||||
|
||||
控制有两种实现方式，一是通过 UVC 标准协议，二是通过 UVC 拓展通道自定义协议。
|
||||
|
||||
## 标准协议
|
||||
|
||||
| 名称 | 字段 | 字节数 | 默认值 | 最小值 | 最大值 | 是否储存 | Flash 地址 | 说明 |
|
||||
| :----- | :----- | :-------- | :-------- | :-------- | :-------- | :----------- | :----------- | :----- |
|
||||
| 增益 | gain | 2 | 48 | 0 | 48 | √ | 0x12 | 关闭自动曝光，手动设定的参数 |
|
||||
| 亮度 | brightness/exposure_time | 2 | 120 | 0 | 240 | √ | 0x14 | 关闭自动曝光，手动设定的参数 |
|
||||
| 对比度 | contrast/black_level_calibration | 2 | 127 | 0 | 255 | √ | 0x10 | |
|
||||
|
||||
> UVC 标准协议实现的控制，有现成的 API 进行 Get & Set ，包括 Min, Max, Default 。
|
||||
|
||||
## 自定义协议
|
||||
|
||||
| 名称 | 字段 | 字节数 | 默认值 | 最小值 | 最大值 | 是否储存 | Flash 地址 | 所属通道 | 通道地址 | 说明 |
|
||||
| :----- | :----- | :-------- | :-------- | :-------- | :-------- | :----------- | :----------- | :----------- | :----------- | :----- |
|
||||
| 图像帧率 | frame_rate | 2 | 25 | 10 | 60 | √ | 0x21 | XU_CAM_CTRL | 0x0100 | |
|
||||
| IMU 频率 | imu_frequency | 2 | 200 | 200 | 500 | √ | 0x23 | XU_CAM_CTRL | 0x0100 | |
|
||||
| 曝光模式 | exposure_mode | 1 | 0 | 0 | 1 | √ | 0x0F | XU_CAM_CTRL | 0x0100 | 0：开启自动曝光； 1：关闭 |
|
||||
| 最大增益 | max_gain | 2 | 48 | 0 | 48 | √ | 0x1D | XU_CAM_CTRL | 0x0100 | 开始自动曝光，可设定的阈值 |
|
||||
| 最大曝光时间 | max_exposure_time | 2 | 240 | 0 | 240 | √ | 0x1B | XU_CAM_CTRL | 0x0100 | 开始自动曝光，可设定的阈值 |
|
||||
| 期望亮度 | desired_brightness | 2 | 192 | 0 | 255 | √ | 0x19 | XU_CAM_CTRL | 0x0100 | |
|
||||
| IR 控制 | ir_control | 1 | 0 | 0 | 160? | × | - | XU_CAM_CTRL | 0x0100 | |
|
||||
| HDR 模式 | hdr_mode | 1 | 0 | 0 | 1 | √ | 0x1F | XU_CAM_CTRL | 0x0100 | 0：10-bit；1：12-bit? |
|
||||
| 零漂标定 | zero_drift_calibration | | - | - | - | × | - | XU_HALF_DUPLEX | 0x0200 | |
|
||||
| 擦除芯片 | erase_chip | | - | - | - | × | - | XU_HALF_DUPLEX | 0x0200 | |
|
||||
45
doc/zh-Hans/spec_control_channel.md
Normal file
45
doc/zh-Hans/spec_control_channel.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# 拓展通道说明 {#spec_contorl_channel}
|
||||
|
||||
| 名称 | 字段 | 地址 | 带宽 | 说明 |
|
||||
| :----- | :----- | :----- | :----- | :----- |
|
||||
| 相机控制通道 | XU_CAM_CTRL_CHANNEL | 0x0100 | 3 | |
|
||||
| 半双工通道 | XU_HALF_DUPLEX_CHANNEL | 0x0200 | 20 | |
|
||||
| IMU 请求通道 | XU_IMUDATA_WRITE_CHANNEL | 0x0300 | 5 | |
|
||||
| IMU 响应通道 | XU_IMUDATA_READ_CHANNEL | 0x0400 | 2000 | |
|
||||
| 文件通道 | XU_FILE_CHANNEL | 0x0500 | 2000 | |
|
||||
|
||||
## 相机控制通道
|
||||
|
||||
相机控制通道是那些需要 Get & Set & Query 的控制通道，其中 Query 细分为 Min, Max, Default 。
|
||||
|
||||
## 半双工通道
|
||||
|
||||
半双工通道是那些仅需 Get 或 Set 的控制通道，如请求零漂矫正。
|
||||
|
||||
## IMU 通道
|
||||
|
||||
用来请求和响应 IMU 数据的通道，可参见 @ref spec_imu_data 。
|
||||
|
||||
## 文件通道
|
||||
|
||||
用来读写硬件信息、图像参数、 IMU 参数的通道。
|
||||
|
||||
| Name | Flag | Size | File | Checksum |
|
||||
| :--- | :- | :--- | :--- | :------- |
|
||||
| 字节数 | 1 | 2 | - | 1 |
|
||||
| 类型 | uint8_t | uint16_t | - | uint8_t |
|
||||
| 描述 | 标识 | 数据包大小 | 文件内容 | 校验码（Flag 以外所有包字节异或） |
|
||||
|
||||
| File | Flag 位 | ID |
|
||||
| :----- | :------- | :- |
|
||||
| 硬件信息 | 0 | 0 |
|
||||
| 图像参数 | 1 | 1 |
|
||||
| IMU 参数 | 2 | 2 |
|
||||
|
||||
### 文件内容包
|
||||
|
||||
| Name | ID | Size | Content |
|
||||
| :--- | :- | :--- | :------ |
|
||||
| 字节数 | 1 | 2 | - |
|
||||
| 类型 | uint8_t | uint16_t | - |
|
||||
| 描述 | 内容 ID | 内容包大小 | 内容 |
|
||||
17
doc/zh-Hans/spec_hardware_info.md
Normal file
17
doc/zh-Hans/spec_hardware_info.md
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
# 硬件信息说明 {#spec_hardware_info}
|
||||
|
||||
| 名称 | 字段 | 固定值 | 描述符获取 | 拓展通道获取 | 字节数 | 说明 |
|
||||
| :----- | :----- | :-------- | :-------------- | :----------------- | :-------- | :----- |
|
||||
| VID | vid | 0x04B4 | √ | × | 2 | |
|
||||
| PID | pid | 0x00F9 | √ | × | 2 | |
|
||||
| 设备名称 | name | MYNT-EYE-? | √ | √ | 16 | MYNT-EYE-S1000 |
|
||||
| 序列号 | serial_number | - | √ | √ | 16 | |
|
||||
| 固件版本 | firmware_version | - | √ | √ | 2 | major,minor |
|
||||
| 硬件版本 | hardware_version | - | × | √ | 3 | major,minor,flag |
|
||||
| 协议版本 | spec_version | - | × | √ | 2 | major,minor |
|
||||
| 镜头类型 | lens_type | - | × | √ | 4 | vendor(2),product(2) |
|
||||
| IMU 类型 | imu_type | - | × | √ | 4 | vendor(2),product(2) |
|
||||
| 基线长度 | nominal_baseline | - | × | √ | 2 | 单位 mm |
|
||||
|
||||
* 描述符获取：指通用 USB 设备信息，可用工具查看。
|
||||
* 拓展通道获取：指通过拓展通道（UVC Extension Unit）问硬件获取到的信息，需要读取。
|
||||
24
doc/zh-Hans/spec_image_data.md
Normal file
24
doc/zh-Hans/spec_image_data.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
# 图像数据说明 {#spec_image_data}
|
||||
|
||||
| 名称 | 字段 | 单位 | 字节数 | 说明 |
|
||||
| :----- | :----- | :----- | :-------- | :----- |
|
||||
| 帧 ID | frame_id | - | 2 | uint16_t; [0,65535] |
|
||||
| 时间戳 | timestamp | 10 us | 4 | uint32_t |
|
||||
| 曝光时间 | exposure_time | 10 us | 2 | uint16_t |
|
||||
|
||||
> 图像数据传输方式待调研： frame header 或占用像素末尾。
|
||||
|
||||
## 图像数据包
|
||||
|
||||
> 大端序。如果传输方式是占用像素末尾，则数据包倒序排在尾部。
|
||||
|
||||
| Name | Header | Size | FrameID | Timestamp | ExposureTime | Checksum |
|
||||
| :--- | :----- | :--- | :------ | :-------- | :----------- | :------- |
|
||||
| 字节数 | 1 | 1 | 2 | 4 | 2 | 1 |
|
||||
| 类型 | uint8_t | uint8_t | uint16_t | uint32_t | uint16_t | uint8_t |
|
||||
| 描述 | 0x3B | 0x0B （数据包大小） | 帧 ID | 时间戳 | 曝光时间 | 校验码（Header 以外所有包字节异或） |
|
||||
|
||||
* 数据包校验不过，会丢弃该帧。
|
||||
* 时间的单位精度为： 0.01 ms / 10 us 。
|
||||
* 4 字节能表示的最大时间约是 11.9 小时，溢出后将重累计。
|
||||
* 时间累计是从上电时从开始，而不是从打开时开始。
|
||||
25
doc/zh-Hans/spec_image_params.md
Normal file
25
doc/zh-Hans/spec_image_params.md
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
# 图像参数说明 {#spec_image_params}
|
||||
|
||||
## 图像内参
|
||||
|
||||
| 名称 | 字段 | 单位 | 字节数 | 说明 |
|
||||
| :----- | :----- | :----- | :-------- | :----- |
|
||||
| 宽度 | width | px | 2 | uint16_t; [0,65535] |
|
||||
| 高度 | height | px | 2 | uint16_t; [0,65535] |
|
||||
| 焦距 | fx | - | 8 | double |
|
||||
| ^ | fy | - | 8 | double |
|
||||
| 图像中心 | cx | - | 8 | double |
|
||||
| ^ | cy | - | 8 | double |
|
||||
| 畸变模型 | model | - | 1 | uint8_t; pinhole,... |
|
||||
| 畸变参数 | coeffs[5] | - | 40 | double; k1,k2,p1,p2,k3 |
|
||||
|
||||
> 图像内参不同分辨率会不同。如果多分辨率的话，就会有多个。
|
||||
|
||||
## 图像外参
|
||||
|
||||
Left Image 到 Right Image 的变换矩阵。
|
||||
|
||||
| 名称 | 字段 | 单位 | 字节数 | 说明 |
|
||||
| :----- | :----- | :----- | :-------- | :----- |
|
||||
| 旋转矩阵 | rotation[3][3] | - | 72 | double |
|
||||
| 平移矩阵 | translation[3] | - | 24 | double |
|
||||
42
doc/zh-Hans/spec_imu_data.md
Normal file
42
doc/zh-Hans/spec_imu_data.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
# IMU 数据说明 {#spec_imu_data}
|
||||
|
||||
## IMU 请求数据包
|
||||
|
||||
| Name | Header | Serial Number |
|
||||
| :--- | :----- | :------------ |
|
||||
| 字节数 | 1 | 4 |
|
||||
| 类型 | uint8_t | uint32_t |
|
||||
| 描述 | 0x5A | 首次请求写 0 ，不然写上次响应数据包最后一个 IMU 包的序列号 |
|
||||
|
||||
## IMU 响应数据包
|
||||
|
||||
IMU 响应数据包里会包含多个 IMU 包，而每个 IMU 包又带有多个 IMU 段。
|
||||
|
||||
| Name | Header | State | Size | IMU Packets | Checksum |
|
||||
| :--- | :----- | :---- | :--- | :---------- | :------- |
|
||||
| 字节数 | 1 | 1 | 2 | ... | 1 |
|
||||
| 类型 | uint8_t | uint8_t | uint16_t | - | uint8_t |
|
||||
| 描述 | 0x5B | 正常状态为 0 ，否则错误 | 数据包大小 | 所包含的 IMU 包 | 校验码（Header 以外所有包字节异或） |
|
||||
|
||||
### IMU 包
|
||||
|
||||
IMU 包/小包，是一组 IMU 数据。
|
||||
|
||||
| Name | Serial Number | Timestamp | Count | IMU Datas |
|
||||
| :--- | :------------ | :-------- | :---- | :-------- |
|
||||
| 字节数 | 4 | 4 | 1 | ... |
|
||||
| 类型 | uint32_t | uint32_t | uint8_t | - |
|
||||
| 描述 | 序列号 | IMU 基准时间戳 | IMU 段数量 | 所包含的 IMU 段 |
|
||||
|
||||
### IMU 段
|
||||
|
||||
| Name | Offset | FrameID | Accelerometer | Temperature | Gyroscope |
|
||||
| :--- | :----- | :------ | :------------ | :---------- | :-------- |
|
||||
| 字节数 | 2 | 2 | 6 | 2 | 6 |
|
||||
| 类型 | int16_t | uint16_t | int8_t * 3 | int8_t | int8_t * 3 |
|
||||
| Description | 相对基准时间戳的偏移量 | 图像帧 ID | 加速度计 x y z 三轴的值 | IMU 的温度 | 陀螺仪 x y z 三轴的值 |
|
||||
|
||||
* 加速度计和陀螺仪的计量值换算成物理值公式： **real = data * range / 0x10000** 。
|
||||
* 加速度计量程默认值为 **8 g** ，陀螺仪量程默认值为 **1000 deg/s^2** 。
|
||||
* 温度计量值换算成物理值公式： **real = data / ratio + offset** 。
|
||||
* ``ratio`` 默认值为 **326.8** ， ``offset`` 默认值为 **25℃** 。
|
||||
23
doc/zh-Hans/spec_imu_params.md
Normal file
23
doc/zh-Hans/spec_imu_params.md
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
# IMU 参数说明 {#spec_imu_params}
|
||||
|
||||
## IMU 内参
|
||||
|
||||
| 名称 | 字段 | 单位 | 字节数 | 说明 |
|
||||
| :----- | :----- | :----- | :-------- | :----- |
|
||||
| 比例因子 | acc_scale[3][3] | - | 72 | double |
|
||||
| ^ | gyro_scale[3][3] | - | 72 | double |
|
||||
| 零漂 | acc_drift[3] | - | 24 | double |
|
||||
| ^ | gyro_drift[3] | - | 24 | double |
|
||||
| 噪声密度 | acc_noise[3] | - | 24 | double |
|
||||
| ^ | gyro_noise[3] | - | 24 | double |
|
||||
| 随机游走 | acc_bias[3] | - | 24 | double |
|
||||
| ^ | gyro_bias[3] | - | 24 | double |
|
||||
|
||||
## IMU 外参
|
||||
|
||||
Left Image 到 IMU 的变换矩阵。
|
||||
|
||||
| 名称 | 字段 | 单位 | 字节数 | 说明 |
|
||||
| :----- | :----- | :----- | :-------- | :----- |
|
||||
| 旋转矩阵 | rotation[3][3] | - | 72 | double |
|
||||
| 平移矩阵 | translation[3] | - | 24 | double |
|
||||
4
doc/zh-Hans/specs_ctrl.md
Normal file
4
doc/zh-Hans/specs_ctrl.md
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
# 设备控制说明 {#specs_ctrl}
|
||||
|
||||
* @subpage spec_contorl_api
|
||||
* @subpage spec_contorl_channel
|
||||
7
doc/zh-Hans/specs_data.md
Normal file
7
doc/zh-Hans/specs_data.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
# 设备数据说明 {#specs_data}
|
||||
|
||||
* @subpage spec_hardware_info
|
||||
* @subpage spec_image_params
|
||||
* @subpage spec_imu_params
|
||||
* @subpage spec_image_data
|
||||
* @subpage spec_imu_data
|
||||
Loading…
Reference in New Issue
Block a user