Add USB CDC-ECM Host support by dlizewski · Pull Request #18815 · apache/nuttx

dlizewski · 2026-04-27T17:58:10Z

Summary

Added support for USB CDC-ECM host class. This host class is used for many USB-Ethernet adaptors as well as USB modems.
I also added support to select different configurations since the USB-Ethernet adaptor I have only presents CDC-ECM as the 2nd configuration. I split this into a separate commit.
New configuration with functional demo at nucleo-h563zi:nshusbnet.

Impact

Added a new USB CDC-ECM host class.
Adds ability to sleect different USB configurations.
All changes behind Kconfigs so changes will only be seen if enabled.

Testing

I have tested with with a few Quectel Modems that support CDC-ECM as well as a USB Ethernet adaptor I had.
In the attached logs I used newly created nucleo-h563zi:nshusbnet configuration and connected the USB-Ethernet adaptor nucleo-h563zi:nshusbnet (A Realtek RTL8153 Gigabit Ethernet Adaptor with integrated hub). I then enabled the interface, set DHCP, verified it got an IP, then pinged 8.8.8.8 with no packet loss.

Commands run:

telnetd [4:100]
usbhost_enumerate: ERROR: usbhost_classbind failed -22

NuttShell (NSH) NuttX-12.13.0
nsh> ifconfig
eth0	Link encap:Ethernet HWaddr 4c:e1:73:42:27:5e at RUNNING mtu 1500
	inet addr:0.0.0.0 DRaddr:0.0.0.0 Mask:0.0.0.0

nsh> ifup eth0
ifup eth0...OK
nsh> ifconfig eth0 dhcp
nsh> ifconfig
eth0	Link encap:Ethernet HWaddr 4c:e1:73:42:27:5e at RUNNING mtu 1500
	inet addr:192.168.0.249 DRaddr:192.168.0.1 Mask:255.255.0.0

nsh> ping 8.8.8.8
PING 8.8.8.8 56 bytes of data
56 bytes from 8.8.8.8: icmp_seq=0 time=20.0 ms
56 bytes from 8.8.8.8: icmp_seq=1 time=10.0 ms
56 bytes from 8.8.8.8: icmp_seq=2 time=20.0 ms
56 bytes from 8.8.8.8: icmp_seq=3 time=10.0 ms
56 bytes from 8.8.8.8: icmp_seq=4 time=20.0 ms
56 bytes from 8.8.8.8: icmp_seq=5 time=10.0 ms
56 bytes from 8.8.8.8: icmp_seq=6 time=10.0 ms
56 bytes from 8.8.8.8: icmp_seq=7 time=20.0 ms
56 bytes from 8.8.8.8: icmp_seq=8 time=10.0 ms
56 bytes from 8.8.8.8: icmp_seq=9 time=20.0 ms
10 packets transmitted, 10 received, 0% packet loss, time 10100 ms
rtt min/avg/max/mdev = 10.000/15.000/20.000/5.000 ms

ecm_log.txt

cederom · 2026-04-27T20:30:36Z

Wow, very cool, thank you @dlizewski, and congratulations on your first contribution to the NuttX RTOS :-)

Could you please provide also a documentation for the new functionality? :-)

Pozdrawiam :-)

cederom · 2026-04-28T17:11:13Z

Builds fine for me, but I have no board to test, tried on NUCLEO-H755ZI but I had problem flashing :-P

% uname -a
FreeBSD hexagon 14.4-RELEASE-p2 FreeBSD 14.4-RELEASE-p2 GENERIC amd64

% git checkout dlizewski/feature/dl.usbecm
HEAD is now at 38866d8497e drivers/usbhost/usbhost_cdcecm.c: Added support for Host CDC-ECM
hexagon% git log -1
commit 38866d8497e8c8c26e8f0e48b17f2954afe623dc (HEAD, dlizewski/feature/dl.usbecm)
Author: daniellizewski
Date:   Thu Apr 9 13:49:50 2026 -0400

    drivers/usbhost/usbhost_cdcecm.c: Added support for Host CDC-ECM

    Added support for USB host to use an USB CDC-ECM device.
    This class is used for usb-ethernet adapters as well as many modems.

    Signed-off-by: daniellizewski <daniellizewski@geotab.com>

% ./tools/configure.sh -B nucleo-h563zi:nshusbnet
  Copy files
  Select CONFIG_HOST_BSD=y
  Refreshing...
(..)
#
# configuration written to .config
#

hexagon% gmake -j
Create version.h
LN: platform/board to /XXX/nuttx/pr/nuttx-apps.git/platform/dummy
Register: telnetd
Register: ping
Register: dd
Register: nsh
Register: sh
LD: nuttx
Memory region         Used Size  Region Size  %age Used
           flash:      330308 B         2 MB     15.75%
            sram:       22656 B       256 KB      8.64%
CP: nuttx.bin

% openocd -f  interface/stlink.cfg -f target/stm32h7x.cfg -c 'program nuttx.bin 0x08000000; reset run; exit'
Open On-Chip Debugger 0.12.0
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "hla_swd". To override use 'transport select <transport>'.
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
Info : clock speed 1800 kHz
Info : STLINK V3J15M6 (API v3) VID:PID 0483:3754
Info : Target voltage: 3.280690
Info : [stm32h7x.cpu0] Cortex-M7 r1p1 processor detected
Info : [stm32h7x.cpu0] target has 8 breakpoints, 4 watchpoints
Info : starting gdb server for stm32h7x.cpu0 on 3333
Info : Listening on port 3333 for gdb connections
[stm32h7x.cpu0] halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0x08001fbc msp: 0x20006080
Info : Unable to match requested speed 4000 kHz, using 3300 kHz
Info : Unable to match requested speed 4000 kHz, using 3300 kHz
** Programming Started **
Info : Device: STM32H74x/75x
Info : flash size probed value 2048k
Info : STM32H7 flash has dual banks
Info : Bank (0) size is 1024 kb, base address is 0x08000000
Info : Padding image section 0 at 0x08050a44 with 28 bytes (bank write end alignment)
Warn : Adding extra erase range, 0x08050a60 .. 0x0805ffff
Error: error writing to flash at address 0x08000000 at offset 0x00000000
embedded:startup.tcl:1516: Error: ** Programming Failed **
in procedure 'program'
in procedure 'program_error' called at file "embedded:startup.tcl", line 1581
at file "embedded:startup.tcl", line 1516

cederom

Thank you @dlizewski :-)

Please add documentation in a free moment :-)

dlizewski · 2026-04-28T19:40:19Z

Wow, very cool, thank you @dlizewski, and congratulations on your first contribution to the NuttX RTOS :-)

Could you please provide also a documentation for the new functionality? :-)

Pozdrawiam :-)

Added docs for the new config and for CDC-ECM host driver

acassis · 2026-05-04T15:22:09Z

@xiaoxiang781216 @cederom PTAL

dlizewski · 2026-05-04T17:46:20Z

The pipeline is failing on weact-stm32h750:nsh

But I checked master and that configuration also fails to build on master

acassis · 2026-05-04T19:07:08Z

The pipeline is failing on weact-stm32h750:nsh

But I checked master and that configuration also fails to build on master

@dlizewski yes, I just tested locally and found the guilt: the author submitted the defconfig with CONFIG_DEBUG_NOOPT=y. I will submit a fix.

lupyuen · 2026-05-05T07:39:47Z

Please Rebase your PR with the Master Branch, we just fixed weact-stm32h750 thanks :-)

boards/weact-stm32h750: Don't disable compilation optimization #18850

Added support for selecting a different USB configuration. Certain USB devices offer different classes using different configurations. This allows a board file to provide a callback to select the proper configuration for a given USB device. Signed-off-by: daniellizewski <daniellizewski@geotab.com>

Added support for USB host to use an USB CDC-ECM device. This class is used for usb-ethernet adapters as well as many modems. Signed-off-by: daniellizewski <daniellizewski@geotab.com>

Converted USB Host CDC-ECM to a lower half driver. Removed existing full network driver callbacks and replaced with lower half. Signed-off-by: daniellizewski <daniellizewski@geotab.com>

The host interrupt callback was incorrectly using the wrong IRQ for disconnected. In host mode the same IRQ is used for connect/disconnected and it must check a status bit to know which one. When a USB device was unplugged, the host channels were free'd, but if they happen to be mid-transfer, that transfer was never cancelled so the USB hardware might still be trying to perfrom a transfer after was free'd. Fixed by cancelling any transfers on free. Signed-off-by: daniellizewski <daniellizewski@geotab.com>

dlizewski · 2026-05-05T16:53:15Z

our PR with the Master Branch, we just fixe

Rebased and now the pipeline passes, thanks!

cederom

Thank you @dlizewski amazing work! :-)

dlizewski requested review from jerpelea, johannes-nivus and yamt as code owners April 27, 2026 17:58

github-actions Bot added Size: XL The size of the change in this PR is very large. Consider breaking down the PR into smaller pieces. Area: USB Board: arm labels Apr 27, 2026

acassis previously approved these changes Apr 27, 2026

View reviewed changes

acassis requested review from cederom, linguini1 and raiden00pl April 27, 2026 19:57

cederom previously approved these changes Apr 28, 2026

View reviewed changes

xiaoxiang781216 reviewed Apr 28, 2026

View reviewed changes

dlizewski dismissed stale reviews from cederom and acassis via 40ea04c April 28, 2026 19:37

dlizewski force-pushed the feature/dl.usbecm branch from 38866d8 to 40ea04c Compare April 28, 2026 19:37

dlizewski requested review from gustavonihei and yf13 as code owners April 28, 2026 19:37

github-actions Bot added Area: Documentation Improvements or additions to documentation and removed Area: USB labels Apr 28, 2026

acassis previously approved these changes Apr 29, 2026

View reviewed changes

dlizewski dismissed acassis’s stale review via 5f6656f May 4, 2026 15:08

github-actions Bot added the Arch: arm Issues related to ARM (32-bit) architecture label May 4, 2026

dlizewski force-pushed the feature/dl.usbecm branch from 5f6656f to 46a966e Compare May 4, 2026 15:23

daniel-geotab added 4 commits May 5, 2026 08:18

drivers/usbhost/usbhost_cdcecm.c: Added support for Host CDC-ECM

59a5c3a

Added support for USB host to use an USB CDC-ECM device. This class is used for usb-ethernet adapters as well as many modems. Signed-off-by: daniellizewski <daniellizewski@geotab.com>

drivers/usbhost/usbhost_cdcecm.c: Converted CDC-ECM to lower half

a3c364b

Converted USB Host CDC-ECM to a lower half driver. Removed existing full network driver callbacks and replaced with lower half. Signed-off-by: daniellizewski <daniellizewski@geotab.com>

dlizewski force-pushed the feature/dl.usbecm branch from 46a966e to 1470dce Compare May 5, 2026 12:19

xiaoxiang781216 approved these changes May 5, 2026

View reviewed changes

cederom approved these changes May 5, 2026

View reviewed changes

lupyuen approved these changes May 5, 2026

View reviewed changes

lupyuen merged commit 0b0769f into apache:master May 5, 2026
27 checks passed

Conversation

dlizewski commented Apr 27, 2026 • edited by cederom Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Impact

Testing

Uh oh!

cederom commented Apr 27, 2026

Uh oh!

cederom commented Apr 28, 2026

Uh oh!

cederom left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dlizewski commented Apr 28, 2026

Uh oh!

acassis commented May 4, 2026

Uh oh!

dlizewski commented May 4, 2026

Uh oh!

acassis commented May 4, 2026

Uh oh!

lupyuen commented May 5, 2026

Uh oh!

dlizewski commented May 5, 2026

Uh oh!

cederom left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

dlizewski commented Apr 27, 2026 •

edited by cederom

Loading