sample: drivers: video: capture: add support for the video shell

Modify the capture sample to only run the video shell when the user
enables it with -DCONFIG_VIDEO_SHELL=y, as an alternative way to trigger
captures.

Signed-off-by: Josuah Demangeon <me@josuah.net>

Author: josuah

drivers/video/video_shell.c

@@ -127,6 +127,22 @@ static int cmd_video_stop(const struct shell *sh, size_t argc, char **argv)
 	return 0;
 }
 
+static void video_shell_print_buffer(const struct shell *sh, struct video_buffer *vbuf,
+				     struct video_format *fmt, int i, uint32_t num_buffer,
+				     uint32_t frmrate_fps, uint32_t frmival_msec)
+{
+	uint32_t line_offset = vbuf->line_offset;
+	uint32_t byte_offset = line_offset * fmt->pitch;
+	uint32_t bytes_in_buf = vbuf->bytesused;
+	uint32_t lines_in_buf = vbuf->bytesused / fmt->pitch;
+
+	shell_print(sh, "Buffer %u/%u at %u ms, Bytes %u-%u/%u, Lines %u-%u/%u, Rate %u FPS %u ms",
+		    /* Buffer */ i + 1, num_buffer, vbuf->timestamp,
+		    /* Bytes */ byte_offset, byte_offset + bytes_in_buf, fmt->height * fmt->pitch,
+		    /* Lines */ line_offset, line_offset + lines_in_buf, fmt->height,
+		    /* Rate */ frmrate_fps, frmival_msec);
+}
+
 static int cmd_video_capture(const struct shell *sh, size_t argc, char **argv)
 {
 	const struct device *dev;
@@ -140,7 +156,7 @@ static int cmd_video_capture(const struct shell *sh, size_t argc, char **argv)
 	uint32_t frmival_msec;
 	uint32_t frmrate_fps;
 	size_t buf_size;
-	unsigned long num_frames;
+	unsigned long num_buffers;
 	int ret;
 
 	dev = device_get_binding(argv[1]);
@@ -155,7 +171,7 @@ static int cmd_video_capture(const struct shell *sh, size_t argc, char **argv)
 		return ret;
 	}
 
-	num_frames = strtoull(arg2, &arg2, 10);
+	num_buffers = strtoull(arg2, &arg2, 10);
 	if (*arg2 != '\0') {
 		shell_error(sh, "Invalid integer '%s' for this type", argv[1]);
 		return -EINVAL;
@@ -180,7 +196,7 @@ static int cmd_video_capture(const struct shell *sh, size_t argc, char **argv)
 		}
 	}
 
-	shell_print(sh, "Starting the capture of %lu frames from %s", num_frames, dev->name);
+	shell_print(sh, "Starting the capture of %lu buffers from %s", num_buffers, dev->name);
 
 	ret = video_stream_start(dev);
 	if (ret != 0) {
@@ -190,7 +206,7 @@ static int cmd_video_capture(const struct shell *sh, size_t argc, char **argv)
 
 	first_uptime = prev_uptime = this_uptime = k_uptime_get_32();
 
-	for (unsigned long i = 0; i < num_frames;) {
+	for (unsigned long i = 0; i < num_buffers;) {
 		ret = video_dequeue(dev, VIDEO_EP_OUT, &vbuf, K_FOREVER);
 		if (ret != 0) {
 			shell_error(sh, "Failed to dequeue this buffer: %s", strerror(-ret));
@@ -202,12 +218,7 @@ static int cmd_video_capture(const struct shell *sh, size_t argc, char **argv)
 		frmrate_fps = (frmival_msec == 0) ? (UINT32_MAX) : (MSEC_PER_SEC / frmival_msec);
 		prev_uptime = this_uptime;
 
-		shell_print(sh, "Frame %3lu/%lu, Bytes %u-%u/%u, Lines %u-%u/%u, %u ms %u FPS",
-			    i, num_frames, vbuf->line_offset * fmt.pitch,
-			    vbuf->line_offset * fmt.pitch + vbuf->bytesused, vbuf->size,
-			    vbuf->line_offset,
-			    vbuf->line_offset + vbuf->bytesused / fmt.pitch, fmt.height,
-			    frmival_msec, frmrate_fps);
+		video_shell_print_buffer(sh, vbuf, &fmt, i, num_buffers, frmrate_fps, frmival_msec);
 
 		/* Only increment the frame counter on the beginning of a new frame */
 		i += (vbuf->line_offset == 0);
@@ -221,10 +232,10 @@ static int cmd_video_capture(const struct shell *sh, size_t argc, char **argv)
 
 	frmival_msec = this_uptime - first_uptime;
 	frmrate_fps =
-		(frmival_msec == 0) ? (UINT32_MAX) : (num_frames * MSEC_PER_SEC / frmival_msec);
+		(frmival_msec == 0) ? (UINT32_MAX) : (num_buffers * MSEC_PER_SEC / frmival_msec);
 
-	shell_print(sh, "Capture of %lu frames in %u ms in total, %u FPS on average, stopping %s",
-		    num_frames, frmival_msec, frmrate_fps, dev->name);
+	shell_print(sh, "Capture of %lu buffers in %u ms in total, %u FPS on average, stopping %s",
+		    num_buffers, frmival_msec, frmrate_fps, dev->name);
 
 end:
 	video_stream_stop(dev);
@@ -1021,8 +1032,8 @@ SHELL_STATIC_SUBCMD_SET_CREATE(sub_video_cmds,
 		"Usage: video stop <device>",
 		cmd_video_stop, 2, 0),
 	SHELL_CMD_ARG(capture, &dsub_video_dev,
-		"Capture a given number of frames from a device\n"
-		"Usage: video capture <device> <num-frames>",
+		"Capture a given number of buffers from a device\n"
+		"Usage: video capture <device> <num-buffers>",
 		cmd_video_capture, 3, 0),
 	SHELL_CMD_ARG(format, &dsub_video_format_dev,
 		"Query or set the video format of a device\n"

samples/drivers/video/capture/README.rst

@@ -83,10 +83,29 @@ using the :ref:`dvp_20pin_ov7670` and :ref:`lcd_par_s035` connected to the board
    :goals: build
    :compact:
 
+For :ref:`native_sim`, build this sample application with the following commands:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/drivers/video/capture
+   :board: native_sim
+   :goals: build
+   :compact:
+
 For testing purpose without the need of any real video capture and/or display hardwares,
 a video software pattern generator is supported by the above build commands without
 specifying the shields.
 
+For controlling the camera device using shell commands instead of continuously capturing the data,
+append ``-DCONFIG_VIDEO_SHELL=y`` to the build command:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/drivers/video/capture
+   :board: mimxrt1064_evk
+   :shield: dvp_fpc24_mt9m114,rk043fn66hs_ctg
+   :gen-args: -DCONFIG_VIDEO_SHELL=y
+   :goals: build
+   :compact:
+
 Sample Output
 =============
 
@@ -118,6 +137,28 @@ Sample Output
 
    <repeats endlessly>
 
+If using the shell, the capture would not start, and instead it is possible to access the shell
+
+.. code-block:: console
+
+   uart:~$ video
+   video - Video driver commands
+   Subcommands:
+     start    : Start a video device and its sources
+                Usage: video start <device>
+     stop     : Stop a video device and its sources
+                Usage: video stop <device>
+     capture  : Capture a given number of frames from a device
+                Usage: video capture <device> <num-frames>
+     format   : Query or set the video format of a device
+                Usage: video format <device> <ep> [<fourcc> <width>x<height>]
+     frmival  : Query or set the video frame rate/interval of a device
+                Usage: video frmival <device> <ep> [<n>fps|<n>ms|<n>us]
+     ctrl     : Query or set video controls of a device
+                Usage: video ctrl <device> [<ctrl> <value>]
+   uart:~$
+
+
 References
 **********
 

samples/drivers/video/capture/sample.yaml

@@ -36,3 +36,21 @@ tests:
     integration_platforms:
       - mimxrt1064_evk
       - mimxrt1170_evk/mimxrt1176/cm7
+  sample.video.capture.shell:
+    tags:
+      - video
+      - samples
+      - shell
+    extra_configs:
+      - CONFIG_VIDEO_SHELL=y
+      - CONFIG_FPU=y
+      - CONFIG_DISPLAY=n
+    harness: console
+    harness_config:
+      type: one_line
+      regex:
+        - "Letting the user control the device with the video shell"
+    platform_allow:
+      - native_sim/native/64
+    integration_platforms:
+      - native_sim/native/64

samples/drivers/video/capture/src/main.c

@@ -100,6 +100,12 @@ int main(void)
 	int i = 0;
 	int err;
 
+	/* When the video shell is enabled, do not run the capture loop */
+	if (IS_ENABLED(CONFIG_VIDEO_SHELL)) {
+		LOG_INF("Letting the user control the device with the video shell");
+		return 0;
+	}
+
 #if DT_HAS_CHOSEN(zephyr_camera)
 	const struct device *const video_dev = DEVICE_DT_GET(DT_CHOSEN(zephyr_camera));