drivers: video: Add the video shell

[josuah]

Dependencies:

• Implement video control framework #82158

Replaces:

• drivers: video: shell: initial implementation #82393

Now that we have a nice shell control querying API, it is possible to tab-complete in-depth every control value.

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>]

To test on native_sim with VIDEO_SW_GENERATOR:

west build -t run -b native_sim/native/64 samples/drivers/video/capture -- -DCONFIG_VIDEO_SHELL=y

On another terminal, using your favorite serial console client, and likely COM# on Windows instead of /dev/pts/3:

picocom -b 115200 /dev/pts/3

[josuah]

Because of the limitation of the shell API, a hack was used using LISTIFY() to generate completion functions that have an extra argument (i.e. the device number), so that the tab completion results are aware of the beginning of the line.

This is not expected to take more RAM, only more ROM/Flash.

[josuah]

Force-push:

• Add the capture command mimicking the behavior of yavta -c<num-frames> <device> with video capture <device> <num-frames>.

[josuah]

Tested again with native_sim (64-bit for SDL support) and Arduino Nicla Vision:

west build --board native_sim/native/64 samples/drivers/video/capture/ -- -DCONFIG_VIDEO_SHELL=y

west build -b arduino_nicla_vision/stm32h747xx/m7 samples/drivers/video/capture -- -DCONFIG_VIDEO_SHELL=y

[josuah]

The controls were just tested again with HFLIP/VFLIP and we observe the image being mirrored left/right.

[Copilot]

Pull Request Overview

This PR adds support for a video shell in the video driver by introducing a new API function, video_convert_ctrl_name, which converts human-friendly video control names into canonical identifiers for software use. Additionally, necessary header updates and modifications in the video_ctrls.c file ensure the new function is integrated into the control printing process.

• Added function video_convert_ctrl_name with corresponding documentation in video.h.
• Updated video_ctrls.c to include ctype.h, implement video_convert_ctrl_name, and integrate it into video_print_ctrl.
• Enhanced logging to use converted control names for improved usability.

Reviewed Changes

Copilot reviewed 3 out of 7 changed files in this pull request and generated 1 comment.

File	Description
include/zephyr/drivers/video.h	Adds function declaration and documentation for video_convert_ctrl_name.
drivers/video/video_ctrls.c	Implements video_convert_ctrl_name and updates printing of control names.

Files not reviewed (4)

• drivers/video/CMakeLists.txt: Language not supported
• drivers/video/Kconfig: Language not supported
• drivers/video/Kconfig.shell: Language not supported
• tests/drivers/build_all/video/prj.conf: Language not supported

[josuah]

My bad, here we go again. No complain from:

cmake --build _build --target doxygen
scripts/ci/check_compliance.py -n -c origin/main..HEAD -e ClangFormat

[kartben]

should this be a Kconfig?

[josuah]

I opted for a more global CONFIG_VIDEO_CTRL_NAME_MAX_SIZE if that is fit.

[kartben]

Suggested change

	char namebuf[40];
	char namebuf[VIDEO_SHELL_NAME_MAX_SIZE];

[josuah]

Applied, good point.

[kartben]

Did you test corner cases (including your own example "White Balance, Automatic")?
Using the same index for both strings seems like asking for trouble.

char dest[20];
const char *examples[] = {
    "hello   world",
    "  hello",
    "hello!",
    "White Balance, Automatic",
};

for (int i = 0; i < sizeof(examples) / sizeof(examples[0]); i++) {
    video_convert_ctrl_name(examples[i], dest, sizeof(dest));
    printf("Input: '%s' => Output: '%s'\n", examples[i], dest);
}

/*
Input: 'hello   world' => Output: 'hello_'
Input: '  hello' => Output: 'hehello'
Input: 'hello!' => Output: 'hellol'
Input: 'White Balance, Automatic' => Output: 'white_balance_'
*/

[josuah]

good opportunity to add unit tests...

[kartben]

so trailing special characters are folded into 1 underscore and leading special characters end up being discarded? the lack of symmetry seems odd, maybe?

[josuah]

the lack of symmetry seems odd, maybe?

I agree. This was assuming a control would never be named i.e. Misc +.
Latest push also covers this edge case instead of asserting a mis-handling.