diff --git a/boards/shields/cdc_acm/Kconfig.defconfig b/boards/shields/cdc_acm/Kconfig.defconfig new file mode 100644 index 00000000000000..17b16df163bbce --- /dev/null +++ b/boards/shields/cdc_acm/Kconfig.defconfig @@ -0,0 +1,43 @@ +# Copyright (c) 2021 Nordic Semiconductor ASA +# SPDX-License-Identifier: Apache-2.0 + +if SHIELD_CDC_ACM_CONSOLE || SHIELD_CDC_ACM_SHELL + +# TEST_LOGGING_DEFAULTS option sets all log levels to INF, +# including the USB_CDC_ACM_LOG_LEVEL and that can not work. +config TEST_LOGGING_DEFAULTS + default n + +config SERIAL + default y + +config UART_LINE_CTRL + default y + +config USB_DEVICE_STACK + default y + +config USB_DEVICE_INITIALIZE_AT_BOOT + default y + +endif #if SHIELD_CDC_ACM_CONSOLE || SHIELD_CDC_ACM_SHELL + +if SHIELD_CDC_ACM_CONSOLE + +config CONSOLE + default y + +config UART_CONSOLE + default y + +endif #if SHIELD_CDC_ACM_CONSOLE + +if SHIELD_CDC_ACM_SHELL + +config SHELL_BACKEND_SERIAL_CHECK_DTR + default y + +config LOG_PRINTK + default y + +endif #if SHIELD_CDC_ACM_SHELL diff --git a/boards/shields/cdc_acm/Kconfig.shield b/boards/shields/cdc_acm/Kconfig.shield new file mode 100644 index 00000000000000..51185f6347f05b --- /dev/null +++ b/boards/shields/cdc_acm/Kconfig.shield @@ -0,0 +1,8 @@ +# Copyright (c) 2021 +# SPDX-License-Identifier: Apache-2.0 + +config SHIELD_CDC_ACM_CONSOLE + def_bool $(shields_list_contains,cdc_acm_console) + +config SHIELD_CDC_ACM_SHELL + def_bool $(shields_list_contains,cdc_acm_shell) diff --git a/boards/shields/cdc_acm/cdc_acm_console.overlay b/boards/shields/cdc_acm/cdc_acm_console.overlay new file mode 100644 index 00000000000000..4d5d886c39a16b --- /dev/null +++ b/boards/shields/cdc_acm/cdc_acm_console.overlay @@ -0,0 +1,18 @@ +/* + * Copyright (c) 2021 Nordic Semiconductor ASA + * + * SPDX-License-Identifier: Apache-2.0 + */ + +/ { + chosen { + zephyr,console = &console_cdc_acm_uart0; + }; +}; + +&zephyr_udc0 { + console_cdc_acm_uart0: console_cdc_acm_uart0 { + compatible = "zephyr,cdc-acm-uart"; + label = "CONSOLE_CDC_ACM_0"; + }; +}; diff --git a/boards/shields/cdc_acm/cdc_acm_shell.overlay b/boards/shields/cdc_acm/cdc_acm_shell.overlay new file mode 100644 index 00000000000000..f6a98cba54a41e --- /dev/null +++ b/boards/shields/cdc_acm/cdc_acm_shell.overlay @@ -0,0 +1,18 @@ +/* + * Copyright (c) 2021 Nordic Semiconductor ASA + * + * SPDX-License-Identifier: Apache-2.0 + */ + +/ { + chosen { + zephyr,shell-uart = &shell_cdc_acm_uart0; + }; +}; + +&zephyr_udc0 { + shell_cdc_acm_uart0: shell_cdc_acm_uart0 { + compatible = "zephyr,cdc-acm-uart"; + label = "SHELL_CDC_ACM_0"; + }; +}; diff --git a/boards/shields/cdc_acm/doc/index.rst b/boards/shields/cdc_acm/doc/index.rst new file mode 100644 index 00000000000000..27344bcee2fb4e --- /dev/null +++ b/boards/shields/cdc_acm/doc/index.rst @@ -0,0 +1,64 @@ +.. _cdc_acm_shield: + +Generic shields for CDC ACM UART +################################ + +Overview +******** + +This is a generic shield that provides devicetree and configuration overlays, +and configures USB device stack so that CDC ACM UART can be used as backend +for console, logging, and shell. It is mainly intended to be used with boards +that do not have a debug adapter or native UART, but do have a USB device +controller. +This approach allows us to avoid many identical overlays in samples and tests +directories (see :ref:`usb_device_cdc_acm` for more details). +It also simplifies the configuration of the above mentioned boards, +they can stay with the minimal configuration which minimizes the conflicts +especially with different in-tree samples. + +These shields enable :kconfig:`CONFIG_USB_DEVICE_INITIALIZE_AT_BOOT` and +configure USB device stack so that it is automatically initialized. +This is important for the boards like :ref:`nrf52840dongle_nrf52840`, +otherwise in-tree samples, that do not enable USB device support, are +not usable. But it also means that in-tree samples, like :ref:`usb_cdc-acm`, +that initialize USB device support themselves cannot be used with these shields. +This is a good compromise which provides maximum coverage of usable samples for +these specific USB dongles. + +Current supported chosen properties +=================================== + ++-----------------------+---------------------+ +| Chosen property | Shield Designation | +| | | ++=======================+=====================+ +| ``zephyr,console`` | ``cdc_acm_console`` | ++-----------------------+---------------------+ +| ``zephyr,shell-uart`` | ``cdc_acm_shell`` | ++-----------------------+---------------------+ + +Requirements +************ + +This shield can only be used with a board which provides a USB device +controller. + +Programming +*********** + +Set ``-DSHIELD=cdc_acm_shell`` when you invoke ``west build``. For example: + +.. zephyr-app-commands:: + :zephyr-app: samples/subsys/shell/shell_module + :board: nrf52840dongle_nrf52840 + :shield: cdc_acm_shell + :goals: build + +Or ``-DSHIELD=cdc_acm_console``, for example: + +.. zephyr-app-commands:: + :zephyr-app: samples/basic/threads + :board: nrf52840dongle_nrf52840 + :shield: cdc_acm_console + :goals: build diff --git a/doc/reference/usb/uds_cdc_acm.rst b/doc/reference/usb/uds_cdc_acm.rst index dc0e5b3d973c5b..90e51096d1bd58 100644 --- a/doc/reference/usb/uds_cdc_acm.rst +++ b/doc/reference/usb/uds_cdc_acm.rst @@ -106,3 +106,7 @@ CDC ACM UART as backend for a subsystem or application: * ``zephyr,shell-uart`` used by shell for serial backend, for example see :zephyr_file:`samples/subsys/shell/shell_module` * ``zephyr,uart-mcumgr`` used by :ref:`smp_svr_sample` + +In-tree samples that do not require any USB device classes other than +CDC ACM UART for console, logging, or shell should be built with +:ref:`cdc_acm_shield`.