发布: 02_摄像头控制接口

IMX6ULL/doc_pic/13_V4L2/01_V4L2应用程序开发.md

@@ -7,7 +7,11 @@
 * 这2个源码都放在GIT仓库里：
   ![image-20230617173258521](pic/04_demo.png)
 
+* UVC文档
+  ![image-20230725082351792](pic/06_uvc_specific.png)
 
+* 参考文章：https://www.xjx100.cn/news/700965.html?action=onClick
+  
 
 ## 1. 数据采集流程
 
@@ -71,3 +75,228 @@ APP也会周而复始地做如下事情：
 
 ## 2. 控制流程
 
+使用摄像头时，我们可以调整很多参数，比如：
+
+* 对于视频流本身：
+  * 设置格式：比如V4L2_PIX_FMT_YUYV、V4L2_PIX_FMT_MJPEG、V4L2_PIX_FMT_RGB565
+  * 设置分辨率：1024*768等
+
+* 对于控制部分：
+  * 调节亮度
+  * 调节对比度
+  * 调节色度
+
+### 2.1 APP接口
+
+就APP而言，对于这些参数由3套接口：查询或枚举(Query/Enum)、获得(Get)、设置(Set)。
+
+#### 2.1.1 数据格式
+
+以设置数据格式为例，可以先枚举：
+
+```c
+struct v4l2_fmtdesc fmtdesc;
+fmtdesc.index = 0;  // 比如从0开始
+fmtdesc.type  = V4L2_BUF_TYPE_VIDEO_CAPTURE;  // 指定type为"捕获"
+ioctl(vd->fd, VIDIOC_ENUM_FMT, &fmtdesc);
+```
+
+还可以获得当前的格式：
+
+```c
+struct v4l2_format currentFormat;
+memset(&currentFormat, 0, sizeof(struct v4l2_format));
+currentFormat.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ioctl(vd->fd, VIDIOC_G_FMT, &currentFormat);
+```
+
+也可以设置当前的格式：
+
+```c
+struct v4l2_format fmt;
+memset(&fmt, 0, sizeof(struct v4l2_format));
+fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+fmt.fmt.pix.width = 1024;
+fmt.fmt.pix.height = 768;
+fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_MJPEG;
+fmt.fmt.pix.field = V4L2_FIELD_ANY;
+int ret = ioctl(vd->fd, VIDIOC_S_FMT, &fmt);
+```
+
+
+
+#### 2.1.2 选择输入源
+
+可以获得当期输入源、设置当前输入源：
+
+```c
+int value;
+ioctl(h->fd,VIDIOC_G_INPUT,&value);  // 读到的value从0开始, 0表示第1个input源
+
+int value = 0;  // 0表示第1个input源
+ioctl(h->fd,VIDIOC_S_INPUT,&value)
+```
+
+
+
+#### 2.1.3 其他参数
+
+如果每一参数都提供一系列的ioctl cmd，那使用起来很不方便。
+
+对于这些参数，APP使用对应ID来选中它，然后使用VIDIOC_QUERYCTRL、VIDIOC_G_CTRL、VIDIOC_S_CTRL来操作它。
+
+不同参数的ID值不同。
+
+以亮度Brightness为例，有如下调用方法:
+
+* 查询：
+
+```c
+struct v4l2_queryctrl   qctrl;
+memset(&qctrl, 0, sizeof(qctrl));
+qctrl.id = V4L2_CID_BRIGHTNESS; // V4L2_CID_BASE+0;
+ioctl(fd, VIDIOC_QUERYCTRL, &qctrl);
+
+/*  Used in the VIDIOC_QUERYCTRL ioctl for querying controls */
+struct v4l2_queryctrl {
+	__u32		     id;
+	__u32		     type;	/* enum v4l2_ctrl_type */
+	__u8		     name[32];	/* Whatever */
+	__s32		     minimum;	/* Note signedness */
+	__s32		     maximum;
+	__s32		     step;
+	__s32		     default_value;
+	__u32                flags;
+	__u32		     reserved[2];
+};
+
+```
+
+* 获得当前值
+
+```c
+struct v4l2_control c;
+c.id = V4L2_CID_BRIGHTNESS; // V4L2_CID_BASE+0;
+ioctl(h->fd, VIDIOC_G_CTRL, &c);
+
+
+/*
+ *	C O N T R O L S
+ */
+struct v4l2_control {
+	__u32		     id;
+	__s32		     value;
+};
+```
+
+* 设置
+
+```c
+struct v4l2_control c;
+c.id = V4L2_CID_BRIGHTNESS; // V4L2_CID_BASE+0;
+c.value = 99;
+ioctl(h->fd, VIDIOC_S_CTRL, &c);
+```
+
+
+
+### 2.2 理解接口
+
+#### 2.2.1 概念
+
+以USB摄像头为例，它的内部结构如下：
+
+![image-20230725082453370](pic/07_uvc_topology.png)
+
+一个USB摄像头必定有一个VideoControl接口，用于控制。有0个或多个VideoStreaming接口，用于传输视频。
+
+在VideoControl内部，有多个Unit或Terminal，上一个Unit或Terminal的数据，流向下一个Unit或Terminal，多个Unit或Terminal组成一个完整的UVC功能设备。
+
+* 只有一个输出引脚
+  ![image-20230725083717206](pic/11_unit_example.png)
+
+* 可以Fan-out，不能Fan-in
+  ![image-20230725084117149](pic/12_fanout_fanin.png)
+
+* Terminal：位于边界，用于联通外界。有：IT(Input Terminal)、OT(Output Terminal)、CT(Camera Terminal)。模型如下，有一个输出引脚：
+
+  ![image-20230725082942680](pic/08_itot.png)
+
+* Unit：位于VideoControl内部，用来进行各种控制
+  * SU：Selector Unit(选择单元)，从多路输入中选择一路，比如设备支持多种输入源，可以通过SU进行选择切换。模型如下
+    ![image-20230725083123895](pic/09_su.png)
+  * PU：Porocessing Unit(处理单元)，用于调整亮度、对比度、色度等，有如下控制功能：
+    * User Controls
+      * Brightness 背光
+      * Hue 色度
+      * Saturation 饱和度
+      * Sharpness 锐度
+      * Gamma 伽马
+      * Digital Multiplier (Zoom) 数字放大
+    * Auto Controls
+      * White Balance Temperature 白平衡色温
+      * White Balance Component 白平衡组件
+      * Backlight Compensation 背光补偿
+      * Contrast 对比度
+    * Other
+      * Gain 增益
+      * Power Line Frequency 电源线频率
+      * Analog Video Standard 模拟视频标准
+      * Analog Video Lock Status 模拟视频锁状态
+    * 模型如下
+      ![image-20230725083301071](pic/10_pu.png)
+  * EU：Encoding Unit(编码单元)，对采集所得的数据进行个性化处理的功能。编码单元控制编码器的属性，该编码器对通过它流式传输的视频进行编码。它具有如下功能：
+    ![image-20230725084636672](pic/13_eu_functions.png)
+  * 模型如下
+    ![image-20230725084743426](pic/14_eu.png)
+
+* XU：Extension Unit(扩展单元)，厂家可以在XU上提供自定义的操作，模型如下：
+  ![image-20230725084952604](pic/15_xu.png)
+
+
+
+#### 2.2.2 操作方法
+
+我们使用ioctl操作设备节点"/dev/video0"时，不同的ioctl操作的可能是VideoControl接口，或者VideoStreaming接口。
+
+跟视频流相关的操作，比如：VIDIOC_ENUM_FMT、VIDIOC_G_FMT、VIDIOC_S_FMT、VIDIOC_STREAMON、VIDIOC_STREAMOFF，是操作VideoStreaming接口。
+
+
+
+其他ioctl，大多都是操作VideoControl接口。
+
+从底层驱动和硬件角度看，要操作VideoControl接口，需要指明：
+
+* entity：你要操作哪个Terminal或Unit，比如PU
+* Control Selector：你要操作entity里面的哪个控制项？比如亮度PU_BRIGHTNESS_CONTROL
+* 控制项里哪些位：比如CT(Camera Terminal)里的CT_PANTILT_RELATIVE_CONTROL控制项对应32位的数据，其中前16位对应PAN控制(左右转动)，后16位对应TILE控制(上下转动)
+
+但是APP不关注这些细节，使用一个ID来指定entity、Control Selector、哪些位：
+
+```c
+/*
+ *	C O N T R O L S
+ */
+struct v4l2_control {
+	__u32		     id;
+	__s32		     value;
+};
+```
+
+驱动程序里，会解析APP传入的ID，找到entity、Control Selector、那些位。
+
+
+
+但是有了上述知识后，我们才能看懂mjpg-streamer的如下代码：
+
+* XU：使用比较老的UVC驱动时，需要APP传入厂家的XU信息；新驱动里可以解析出XU信息，无需APP传入
+  ![image-20230725091551391](pic/16_logitech_xu.png)
+
+* mapping：无论新老UVC驱动，都需要提供更细化的mapping信息
+
+  ![image-20230725092210341](pic/17_logitech_mapping.png)
+
+* 代码如下
+  ![image-20230725092349892](pic/18_add_control_mapping.png)
+
+## 3. 编写APP

IMX6ULL/doc_pic/13_V4L2/02_摄像头控制接口.md

@@ -0,0 +1,87 @@
+# V4L2应用程序开发 #
+
+参考资料：
+
+* mjpg-streamer：https://github.com/jacksonliam/mjpg-streamer
+* video2lcd：这是百问网编写的APP，它可以在LCD上直接显示摄像头的图像
+* 这2个源码都放在GIT仓库里：
+  ![image-20230617173258521](pic/04_demo.png)
+
+
+
+## 1. 
+
+To be able to manipulate the physical properties of a video function, its functionality must be
+divided into addressable entities. The following two generic entities are identified:
+
+* Units：Selector Unit  、Processing Unit  、Encoding Unit  、Extension Unit  
+*  Terminals ：Input Terminal (IT)   、Output Terminal (OT)  、Camera Terminal (CT)  
+  * A Camera Terminal is always represented as an
+    Input Terminal with a single output pin. It provides support for the following features  
+    * Scanning Mode (Progressive or Interlaced)
+    *  Auto-Exposure Mode
+    *  Auto-Exposure Priority
+    *  Exposure Time
+    *  Focus
+    *  Auto-Focus
+    *  Simple Focus
+    *  Iris
+    *  Zoom  
+    * Pan
+    *  Roll
+    *  Tilt
+    *  Digital Windowing
+    *  Region of Interest  
+
+Controls have attributes, which might include:  
+
+* Current setting
+*  Minimum setting
+*  Maximum setting
+*  Resolution
+*  Size
+*  Default  
+
+Processing Unit  
+
+* User Controls  
+  * Brightness
+  *  Hue
+  *  Saturation
+  *  Sharpness
+  *  Gamma
+  *  Digital Multiplier (Zoom)  
+* Auto Controls  
+  * White Balance Temperature
+  *  White Balance Component
+  *  Backlight Compensation  
+  * Contrast  
+* Other  
+  * Gain
+  *  Power Line Frequency
+  *  Analog Video Standard
+  *  Analog Video Lock Status  
+
+
+
+Extension Unit  
+
+
+
+
+
+对于每一个entity(IT,PU,SU,OT等)
+
+* IT: input terminal
+* OT：output terminal
+* VC: video control
+* 
+
+video function：含有几个interface，每个video function含有一个VC(video control)、多个VS(video streaming)，它们被称为VIC。
+
+
+
+参考资料：
+
+https://www.php1.cn/detail/CSS_YangShiGuiZe_218a96fe.html
+

README.md

@@ -768,6 +768,18 @@ git clone https://e.coding.net/weidongshan/linux/doc_and_source_for_drivers.git
   15.2_使用Buildroot移植ADB
   ```
 
+* 2023.06.18 发布"摄像头驱动"
+
+  ```shell
+  01_V4L2应用程序开发_数据采集流程
+  ```
+
+* 2023.06.18 发布"摄像头驱动"
+
+  ```shell
+  02_摄像头控制接口
+  ```
+
   
 
 

STM32MP157/doc_pic/13_V4L2/01_V4L2应用程序开发.md

@@ -7,7 +7,11 @@
 * 这2个源码都放在GIT仓库里：
   ![image-20230617173258521](pic/04_demo.png)
 
+* UVC文档
+  ![image-20230725082351792](pic/06_uvc_specific.png)
 
+* 参考文章：https://www.xjx100.cn/news/700965.html?action=onClick
+  
 
 ## 1. 数据采集流程
 
@@ -71,3 +75,228 @@ APP也会周而复始地做如下事情：
 
 ## 2. 控制流程
 
+使用摄像头时，我们可以调整很多参数，比如：
+
+* 对于视频流本身：
+  * 设置格式：比如V4L2_PIX_FMT_YUYV、V4L2_PIX_FMT_MJPEG、V4L2_PIX_FMT_RGB565
+  * 设置分辨率：1024*768等
+
+* 对于控制部分：
+  * 调节亮度
+  * 调节对比度
+  * 调节色度
+
+### 2.1 APP接口
+
+就APP而言，对于这些参数由3套接口：查询或枚举(Query/Enum)、获得(Get)、设置(Set)。
+
+#### 2.1.1 数据格式
+
+以设置数据格式为例，可以先枚举：
+
+```c
+struct v4l2_fmtdesc fmtdesc;
+fmtdesc.index = 0;  // 比如从0开始
+fmtdesc.type  = V4L2_BUF_TYPE_VIDEO_CAPTURE;  // 指定type为"捕获"
+ioctl(vd->fd, VIDIOC_ENUM_FMT, &fmtdesc);
+```
+
+还可以获得当前的格式：
+
+```c
+struct v4l2_format currentFormat;
+memset(&currentFormat, 0, sizeof(struct v4l2_format));
+currentFormat.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+ioctl(vd->fd, VIDIOC_G_FMT, &currentFormat);
+```
+
+也可以设置当前的格式：
+
+```c
+struct v4l2_format fmt;
+memset(&fmt, 0, sizeof(struct v4l2_format));
+fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE;
+fmt.fmt.pix.width = 1024;
+fmt.fmt.pix.height = 768;
+fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_MJPEG;
+fmt.fmt.pix.field = V4L2_FIELD_ANY;
+int ret = ioctl(vd->fd, VIDIOC_S_FMT, &fmt);
+```
+
+
+
+#### 2.1.2 选择输入源
+
+可以获得当期输入源、设置当前输入源：
+
+```c
+int value;
+ioctl(h->fd,VIDIOC_G_INPUT,&value);  // 读到的value从0开始, 0表示第1个input源
+
+int value = 0;  // 0表示第1个input源
+ioctl(h->fd,VIDIOC_S_INPUT,&value)
+```
+
+
+
+#### 2.1.3 其他参数
+
+如果每一参数都提供一系列的ioctl cmd，那使用起来很不方便。
+
+对于这些参数，APP使用对应ID来选中它，然后使用VIDIOC_QUERYCTRL、VIDIOC_G_CTRL、VIDIOC_S_CTRL来操作它。
+
+不同参数的ID值不同。
+
+以亮度Brightness为例，有如下调用方法:
+
+* 查询：
+
+```c
+struct v4l2_queryctrl   qctrl;
+memset(&qctrl, 0, sizeof(qctrl));
+qctrl.id = V4L2_CID_BRIGHTNESS; // V4L2_CID_BASE+0;
+ioctl(fd, VIDIOC_QUERYCTRL, &qctrl);
+
+/*  Used in the VIDIOC_QUERYCTRL ioctl for querying controls */
+struct v4l2_queryctrl {
+	__u32		     id;
+	__u32		     type;	/* enum v4l2_ctrl_type */
+	__u8		     name[32];	/* Whatever */
+	__s32		     minimum;	/* Note signedness */
+	__s32		     maximum;
+	__s32		     step;
+	__s32		     default_value;
+	__u32                flags;
+	__u32		     reserved[2];
+};
+
+```
+
+* 获得当前值
+
+```c
+struct v4l2_control c;
+c.id = V4L2_CID_BRIGHTNESS; // V4L2_CID_BASE+0;
+ioctl(h->fd, VIDIOC_G_CTRL, &c);
+
+
+/*
+ *	C O N T R O L S
+ */
+struct v4l2_control {
+	__u32		     id;
+	__s32		     value;
+};
+```
+
+* 设置
+
+```c
+struct v4l2_control c;
+c.id = V4L2_CID_BRIGHTNESS; // V4L2_CID_BASE+0;
+c.value = 99;
+ioctl(h->fd, VIDIOC_S_CTRL, &c);
+```
+
+
+
+### 2.2 理解接口
+
+#### 2.2.1 概念
+
+以USB摄像头为例，它的内部结构如下：
+
+![image-20230725082453370](pic/07_uvc_topology.png)
+
+一个USB摄像头必定有一个VideoControl接口，用于控制。有0个或多个VideoStreaming接口，用于传输视频。
+
+在VideoControl内部，有多个Unit或Terminal，上一个Unit或Terminal的数据，流向下一个Unit或Terminal，多个Unit或Terminal组成一个完整的UVC功能设备。
+
+* 只有一个输出引脚
+  ![image-20230725083717206](pic/11_unit_example.png)
+
+* 可以Fan-out，不能Fan-in
+  ![image-20230725084117149](pic/12_fanout_fanin.png)
+
+* Terminal：位于边界，用于联通外界。有：IT(Input Terminal)、OT(Output Terminal)、CT(Camera Terminal)。模型如下，有一个输出引脚：
+
+  ![image-20230725082942680](pic/08_itot.png)
+
+* Unit：位于VideoControl内部，用来进行各种控制
+  * SU：Selector Unit(选择单元)，从多路输入中选择一路，比如设备支持多种输入源，可以通过SU进行选择切换。模型如下
+    ![image-20230725083123895](pic/09_su.png)
+  * PU：Porocessing Unit(处理单元)，用于调整亮度、对比度、色度等，有如下控制功能：
+    * User Controls
+      * Brightness 背光
+      * Hue 色度
+      * Saturation 饱和度
+      * Sharpness 锐度
+      * Gamma 伽马
+      * Digital Multiplier (Zoom) 数字放大
+    * Auto Controls
+      * White Balance Temperature 白平衡色温
+      * White Balance Component 白平衡组件
+      * Backlight Compensation 背光补偿
+      * Contrast 对比度
+    * Other
+      * Gain 增益
+      * Power Line Frequency 电源线频率
+      * Analog Video Standard 模拟视频标准
+      * Analog Video Lock Status 模拟视频锁状态
+    * 模型如下
+      ![image-20230725083301071](pic/10_pu.png)
+  * EU：Encoding Unit(编码单元)，对采集所得的数据进行个性化处理的功能。编码单元控制编码器的属性，该编码器对通过它流式传输的视频进行编码。它具有如下功能：
+    ![image-20230725084636672](pic/13_eu_functions.png)
+  * 模型如下
+    ![image-20230725084743426](pic/14_eu.png)
+
+* XU：Extension Unit(扩展单元)，厂家可以在XU上提供自定义的操作，模型如下：
+  ![image-20230725084952604](pic/15_xu.png)
+
+
+
+#### 2.2.2 操作方法
+
+我们使用ioctl操作设备节点"/dev/video0"时，不同的ioctl操作的可能是VideoControl接口，或者VideoStreaming接口。
+
+跟视频流相关的操作，比如：VIDIOC_ENUM_FMT、VIDIOC_G_FMT、VIDIOC_S_FMT、VIDIOC_STREAMON、VIDIOC_STREAMOFF，是操作VideoStreaming接口。
+
+
+
+其他ioctl，大多都是操作VideoControl接口。
+
+从底层驱动和硬件角度看，要操作VideoControl接口，需要指明：
+
+* entity：你要操作哪个Terminal或Unit，比如PU
+* Control Selector：你要操作entity里面的哪个控制项？比如亮度PU_BRIGHTNESS_CONTROL
+* 控制项里哪些位：比如CT(Camera Terminal)里的CT_PANTILT_RELATIVE_CONTROL控制项对应32位的数据，其中前16位对应PAN控制(左右转动)，后16位对应TILE控制(上下转动)
+
+但是APP不关注这些细节，使用一个ID来指定entity、Control Selector、哪些位：
+
+```c
+/*
+ *	C O N T R O L S
+ */
+struct v4l2_control {
+	__u32		     id;
+	__s32		     value;
+};
+```
+
+驱动程序里，会解析APP传入的ID，找到entity、Control Selector、那些位。
+
+
+
+但是有了上述知识后，我们才能看懂mjpg-streamer的如下代码：
+
+* XU：使用比较老的UVC驱动时，需要APP传入厂家的XU信息；新驱动里可以解析出XU信息，无需APP传入
+  ![image-20230725091551391](pic/16_logitech_xu.png)
+
+* mapping：无论新老UVC驱动，都需要提供更细化的mapping信息
+
+  ![image-20230725092210341](pic/17_logitech_mapping.png)
+
+* 代码如下
+  ![image-20230725092349892](pic/18_add_control_mapping.png)
+
+## 3. 编写APP

STM32MP157/doc_pic/13_V4L2/02_摄像头控制接口.md

@@ -0,0 +1,87 @@
+# V4L2应用程序开发 #
+
+参考资料：
+
+* mjpg-streamer：https://github.com/jacksonliam/mjpg-streamer
+* video2lcd：这是百问网编写的APP，它可以在LCD上直接显示摄像头的图像
+* 这2个源码都放在GIT仓库里：
+  ![image-20230617173258521](pic/04_demo.png)
+
+
+
+## 1. 
+
+To be able to manipulate the physical properties of a video function, its functionality must be
+divided into addressable entities. The following two generic entities are identified:
+
+* Units：Selector Unit  、Processing Unit  、Encoding Unit  、Extension Unit  
+*  Terminals ：Input Terminal (IT)   、Output Terminal (OT)  、Camera Terminal (CT)  
+  * A Camera Terminal is always represented as an
+    Input Terminal with a single output pin. It provides support for the following features  
+    * Scanning Mode (Progressive or Interlaced)
+    *  Auto-Exposure Mode
+    *  Auto-Exposure Priority
+    *  Exposure Time
+    *  Focus
+    *  Auto-Focus
+    *  Simple Focus
+    *  Iris
+    *  Zoom  
+    * Pan
+    *  Roll
+    *  Tilt
+    *  Digital Windowing
+    *  Region of Interest  
+
+Controls have attributes, which might include:  
+
+* Current setting
+*  Minimum setting
+*  Maximum setting
+*  Resolution
+*  Size
+*  Default  
+
+Processing Unit  
+
+* User Controls  
+  * Brightness
+  *  Hue
+  *  Saturation
+  *  Sharpness
+  *  Gamma
+  *  Digital Multiplier (Zoom)  
+* Auto Controls  
+  * White Balance Temperature
+  *  White Balance Component
+  *  Backlight Compensation  
+  * Contrast  
+* Other  
+  * Gain
+  *  Power Line Frequency
+  *  Analog Video Standard
+  *  Analog Video Lock Status  
+
+
+
+Extension Unit  
+
+
+
+
+
+对于每一个entity(IT,PU,SU,OT等)
+
+* IT: input terminal
+* OT：output terminal
+* VC: video control
+* 
+
+video function：含有几个interface，每个video function含有一个VC(video control)、多个VS(video streaming)，它们被称为VIC。
+
+
+
+参考资料：
+
+https://www.php1.cn/detail/CSS_YangShiGuiZe_218a96fe.html
+