Skip to content

examples/uvc_cam: add UVC camera streaming app#3438

Open
JianyuWang0623 wants to merge 1 commit intoapache:masterfrom
JianyuWang0623:examples_uvc_cam
Open

examples/uvc_cam: add UVC camera streaming app#3438
JianyuWang0623 wants to merge 1 commit intoapache:masterfrom
JianyuWang0623:examples_uvc_cam

Conversation

@JianyuWang0623
Copy link
Contributor

Summary

Add a UVC camera streaming example application (examples/uvc_cam) that captures frames from a V4L2 camera sensor and streams them to a USB host via the UVC gadget driver.

The application:

  • Queries the sensor's native pixel format, resolution, and frame rate dynamically via VIDIOC_ENUM_FMT, VIDIOC_ENUM_FRAMESIZES, and VIDIOC_ENUM_FRAMEINTERVALS — no hardcoded video parameters.
  • Initializes/deinitializes the UVC gadget through boardctl(BOARDIOC_USBDEV_CONTROL).
  • Uses poll() with POLLOUT to wait for the USB host to start streaming, and to detect host disconnect/reconnect.
  • Supports optional positional arguments: uvc_cam [nframes] [video_dev] [uvc_dev].
  • Supports configurable frame count via Kconfig (CONFIG_EXAMPLES_UVC_CAM_NFRAMES, 0 = infinite).

Depends on the nuttx UVC gadget class driver (apache/nuttx#18609).

Impact

New example application only. No impact on existing code or build.

Adds Kconfig symbol CONFIG_EXAMPLES_UVC_CAM (depends on USBUVC), with sub-options for program name, priority, stack size, and frame count.

Testing

  • Host: Ubuntu 22.04 x86_64, GCC 13.2.0 (Xtensa esp32s3 cross-compiler)
  • Target: xtensa lckfb-szpi-esp32s3:uvc
  • Build: make distclean && ./tools/configure.sh lckfb-szpi-esp32s3:uvc && make -j$(nproc) — clean build, zero warnings.
  • Runtime: Flashed to ESP32-S3 board with GC0308 camera sensor. Verified 320×240 YUYV streaming to Linux host — frames displayed correctly via ffplay -f v4l2 -video_size 320x240 -i /dev/video1. Verified host disconnect/reconnect recovery.

#
# SPDX-License-Identifier: Apache-2.0
#
# ##############################################################################
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done, thank you

#
# SPDX-License-Identifier: Apache-2.0
#
############################################################################
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ditto

Comment on lines +2 to +5
# apps/examples/uvc_cam/Makefile
#
# SPDX-License-Identifier: Apache-2.0
#
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ditto

Comment on lines +3 to +5
*
* SPDX-License-Identifier: Apache-2.0
*
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ditto

@@ -0,0 +1,32 @@
#
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JianyuWang0623 I'm not sure if apps/examples is the best place to add this app. Maybe it should be inside apps/videoutils. What do you think?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess the idea is to provide example code to serve as uvc_cam.. but videoutils can be a good place too :-)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@acassis @cederom I'd lean toward keeping it under examples/ since it's a standalone demo app (similar to examples/camera) rather than a reusable library, which is what videoutils/ typically hosts (openh264, x264). That said, I'm open to moving it if you feel videoutils/ is a better fit — happy to discuss.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for me examples/uvc_cam is okay :-)

@cederom
Copy link
Contributor

cederom commented Mar 26, 2026

Awesome! @JianyuWang0623 could you also please add Documentation on how to use this application as part of documentation in apache/nuttx#18609 bundle? :-)

Usage: uvc_cam [nframes] [video_dev] [uvc_dev]

V4L2 capture -> write UVC gadget device.
Uses boardctl to initialize/deinitialize UVC gadget.
Queries sensor pixel format, resolution and frame rate via V4L2.
Uses poll() to wait for USB host streaming state.
Supports optional device path arguments (default /dev/video0, /dev/uvc0).
Supports configurable frame count (0=infinite).

Signed-off-by: wangjianyu3 <wangjianyu3@xiaomi.com>
@JianyuWang0623
Copy link
Contributor Author

Awesome! @JianyuWang0623 could you also please add Documentation on how to use this application as part of documentation in apache/nuttx#18609 bundle? :-)

@cederom Will do! I’ve just added the usage documentation here: https://github.com/apache/nuttx/compare/9d2ec9642d7bf0c41699f104c06948febeac64b4..e4babac55082a02feef90ad9ed128a5c5ad84648

@cederom
Copy link
Contributor

cederom commented Mar 27, 2026

Awesome! @JianyuWang0623 could you also please add Documentation on how to use this application as part of documentation in apache/nuttx#18609 bundle? :-)

@cederom Will do! I’ve just added the usage documentation here: https://github.com/apache/nuttx/compare/9d2ec9642d7bf0c41699f104c06948febeac64b4..e4babac55082a02feef90ad9ed128a5c5ad84648

TANK U SIR! =)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants