Skip to content

Commit 88c02cd

Browse files
jfischer-nojfischer-no
committed
shields: add generic shield to use CDC ACM UART as backend
Add generic shields that provide devicetree and configuration overlays, and configure USB device stack so that CDC ACM UART can be used as backend for console, logging, or shell. This approach allows us to avoid many identical overlays in samples and tests directories, and cumbersome board configurations. These shields use Kconfig option CONFIG_USB_DEVICE_INITIALIZE_AT_BOOT and is mainly intended to be used with boards like nrf52840dongle_nrf52840 or bl654_usb. Signed-off-by: Johann Fischer <[email protected]>
1 parent 75479f5 commit 88c02cd

File tree

7 files changed

+187
-0
lines changed

7 files changed

+187
-0
lines changed

‎boards/shields/cdc_acm/Kconfig.defconfig‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Copyright (c) 2021 Nordic Semiconductor ASA
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
if SHIELD_CDC_ACM_CONSOLE || SHIELD_CDC_ACM_SHELL || SHIELD_CDC_ACM_BT_C2H
5+
6+
# TEST_LOGGING_DEFAULTS option sets all log levels to INF,
7+
# including the USB_CDC_ACM_LOG_LEVEL and that can not work.
8+
config TEST_LOGGING_DEFAULTS
9+
default n
10+
11+
config SERIAL
12+
default y
13+
14+
config UART_LINE_CTRL
15+
default y
16+
17+
config USB_DEVICE_STACK
18+
default y
19+
20+
config USB_DEVICE_INITIALIZE_AT_BOOT
21+
default y
22+
23+
endif #if SHIELD_CDC_ACM_CONSOLE || SHIELD_CDC_ACM_SHELL || ...
24+
25+
if SHIELD_CDC_ACM_CONSOLE
26+
27+
config CONSOLE
28+
default y
29+
30+
config UART_CONSOLE
31+
default y
32+
33+
endif #if SHIELD_CDC_ACM_CONSOLE
34+
35+
if SHIELD_CDC_ACM_SHELL
36+
37+
config SHELL_BACKEND_SERIAL_CHECK_DTR
38+
default y
39+
40+
config LOG_PRINTK
41+
default y
42+
43+
endif #if SHIELD_CDC_ACM_SHELL

‎boards/shields/cdc_acm/Kconfig.shield‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Copyright (c) 2021
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
config SHIELD_CDC_ACM_CONSOLE
5+
def_bool $(shields_list_contains,cdc_acm_console)
6+
7+
config SHIELD_CDC_ACM_SHELL
8+
def_bool $(shields_list_contains,cdc_acm_shell)
9+
10+
config SHIELD_CDC_ACM_BT_C2H
11+
def_bool $(shields_list_contains,cdc_acm_bt_c2h)

‎boards/shields/cdc_acm/cdc_acm_bt_c2h.overlay‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
/*
2+
* Copyright (c) 2021 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: Apache-2.0
5+
*/
6+
7+
/ {
8+
chosen {
9+
zephyr,bt-c2h-uart = &bt_c2h_cdc_acm_uart0;
10+
};
11+
};
12+
13+
&zephyr_udc0 {
14+
bt_c2h_cdc_acm_uart0: bt_c2h_cdc_acm_uart0 {
15+
compatible = "zephyr,cdc-acm-uart";
16+
label = "BT_C2H_CDC_ACM_0";
17+
};
18+
};

‎boards/shields/cdc_acm/cdc_acm_console.overlay‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
/*
2+
* Copyright (c) 2021 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: Apache-2.0
5+
*/
6+
7+
/ {
8+
chosen {
9+
zephyr,console = &console_cdc_acm_uart0;
10+
};
11+
};
12+
13+
&zephyr_udc0 {
14+
console_cdc_acm_uart0: console_cdc_acm_uart0 {
15+
compatible = "zephyr,cdc-acm-uart";
16+
label = "CONSOLE_CDC_ACM_0";
17+
};
18+
};

‎boards/shields/cdc_acm/cdc_acm_shell.overlay‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
/*
2+
* Copyright (c) 2021 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: Apache-2.0
5+
*/
6+
7+
/ {
8+
chosen {
9+
zephyr,shell-uart = &shell_cdc_acm_uart0;
10+
};
11+
};
12+
13+
&zephyr_udc0 {
14+
shell_cdc_acm_uart0: shell_cdc_acm_uart0 {
15+
compatible = "zephyr,cdc-acm-uart";
16+
label = "SHELL_CDC_ACM_0";
17+
};
18+
};

‎boards/shields/cdc_acm/doc/index.rst‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
.. _cdc_acm_shield:
2+
3+
Generic shields for CDC ACM UART
4+
################################
5+
6+
Overview
7+
********
8+
9+
This is a generic shield that provides devicetree and configuration overlays,
10+
and configures USB device stack so that CDC ACM UART can be used as backend
11+
for console, logging, and shell. It is mainly intended to be used with boards
12+
that do not have a debug adapter or native UART, but do have a USB device
13+
controller.
14+
This approach allows us to avoid many identical overlays in samples and tests
15+
directories (see :ref:`usb_device_cdc_acm` for more details).
16+
It also simplifies the configuration of the above mentioned boards,
17+
they can stay with the minimal configuration which minimizes the conflicts
18+
especially with different in-tree samples.
19+
20+
These shields enable :kconfig:`CONFIG_USB_DEVICE_INITIALIZE_AT_BOOT` and
21+
configure USB device stack so that it is automatically initialized.
22+
This is important for the boards like :ref:`nrf52840dongle_nrf52840`,
23+
otherwise in-tree samples, that do not enable USB device support, are
24+
not usable. But it also means that in-tree samples, like :ref:`usb_cdc-acm`,
25+
that initialize USB device support themselves cannot be used with these shields.
26+
This is a good compromise which provides maximum coverage of usable samples for
27+
these specific USB dongles.
28+
29+
Current supported chosen properties
30+
===================================
31+
32+
+------------------------+---------------------+
33+
| Chosen property | Shield Designation |
34+
| | |
35+
+========================+=====================+
36+
| ``zephyr,console`` | ``cdc_acm_console`` |
37+
+------------------------+---------------------+
38+
| ``zephyr,shell-uart`` | ``cdc_acm_shell`` |
39+
+------------------------+---------------------+
40+
| ``zephyr,bt-c2h-uart`` | ``cdc_acm_bt_c2h`` |
41+
+------------------------+---------------------+
42+
43+
Requirements
44+
************
45+
46+
This shield can only be used with a board which provides a USB device
47+
controller.
48+
49+
Programming
50+
***********
51+
52+
Set ``-DSHIELD=cdc_acm_shell`` when you invoke ``west build``. For example:
53+
54+
.. zephyr-app-commands::
55+
:zephyr-app: samples/subsys/shell/shell_module
56+
:board: nrf52840dongle_nrf52840
57+
:shield: cdc_acm_shell
58+
:goals: build
59+
60+
Or ``-DSHIELD=cdc_acm_console``, for example:
61+
62+
.. zephyr-app-commands::
63+
:zephyr-app: samples/basic/threads
64+
:board: nrf52840dongle_nrf52840
65+
:shield: cdc_acm_console
66+
:goals: build
67+
68+
With ``-DSHIELD=cdc_acm_bt_c2h``, :ref:`bluetooth-hci-uart-sample` can use
69+
CDC ACM UART as interface to the host:
70+
71+
.. zephyr-app-commands::
72+
:zephyr-app: samples/bluetooth/hci_uart
73+
:board: nrf52840dongle_nrf52840
74+
:shield: cdc_acm_bt_c2h
75+
:goals: build

‎doc/services/usb/uds_cdc_acm.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,3 +103,7 @@ CDC ACM UART as backend for a subsystem or application:
103103
* ``zephyr,shell-uart`` used by shell for serial backend,
104104
for example see :zephyr_file:`samples/subsys/shell/shell_module`
105105
* ``zephyr,uart-mcumgr`` used by :ref:`smp_svr_sample`
106+
107+
In-tree samples that do not require any USB device classes other than
108+
CDC ACM UART for console, logging, or shell should be built with
109+
:ref:`cdc_acm_shield`.

0 commit comments

Comments
 (0)