micropython · andrewleech · Jun 21, 2025 · Jun 21, 2025
diff --git a/docs/library/network.USB_NET.rst b/docs/library/network.USB_NET.rst
@@ -0,0 +1,82 @@
+.. currentmodule:: network
+.. _network.USB_NET:
+
+class USB_NET -- USB NCM network interface
+==========================================
+
+This class provides a network interface over USB using the NCM (Network
+Control Model) protocol.  The host computer sees this device as a USB
+Ethernet adapter and assigns it an IP address via DHCP (served by the
+MicroPython device).
+
+.. note:: ``network.USB_NET`` requires a port with TinyUSB and NCM support
+          enabled (``MICROPY_HW_NETWORK_USBNET``).  On stm32 this is
+          automatically enabled when LWIP networking is enabled.  The USB
+          NCM class must also be active - either compiled as the default or
+          enabled in ``boot.py`` via
+          ``machine.USBDevice.BUILTIN_FLAG_NCM``.
+
+Example usage::
+
+    import network
+
+    nic = network.USB_NET()
+    nic.active(True)
+    # wait for USB host to configure the NCM interface
+    while not nic.isconnected():
+        pass
+
+    print(nic.ipconfig("addr4"))
+
+Constructors
+------------
+
+.. class:: USB_NET()
+
+   Create and return a USB_NET object.  This initialises the NCM network
+   interface if it has not already been initialised.  Only one instance
+   exists (singleton).
+
+Methods
+-------
+
+.. method:: USB_NET.active([is_active])
+
+   Activate or deactivate the network interface.  Without argument returns
+   current state as a bool.
+
+.. method:: USB_NET.isconnected()
+
+   Returns ``True`` if the USB host has configured the NCM interface,
+   ``False`` otherwise.
+
+   When USB is disconnected, this returns ``False`` and network traffic
+   stops. The interface remains registered with lwIP and can resume when
+   the host reconnects and re-enumerates the device.
+
+.. method:: USB_NET.status()
+
+   Returns the link status as an integer: ``1`` if the interface is up,
+   ``0`` otherwise.
+
+.. method:: USB_NET.ipconfig('param')
+            USB_NET.ipconfig(param=value, ...)
+
+   See `AbstractNIC.ipconfig`.
+
+.. method:: USB_NET.ifconfig([(ip, subnet, gateway, dns)])
+
+   See `AbstractNIC.ifconfig`.
+
+Notes
+-----
+
+**Link-local IP address:** The device IP (169.254.x.1) is derived
+deterministically from the device MAC address. RFC 3927 ARP probe/announce
+(conflict detection) is not implemented, so if two devices happen to derive
+the same address on the same network segment, the conflict will go undetected.
+
+**MAC address uniqueness:** The device and host-side MAC addresses are derived
+from the value returned by ``mp_hal_get_mac()``. If two boards have the same
+hardware MAC (e.g. the port does not use a hardware UID), they will present
+the same network addresses and cause ARP conflicts.
diff --git a/docs/library/network.rst b/docs/library/network.rst
@@ -193,6 +193,7 @@ provide a way to control networking interfaces of various kinds.
    network.WIZNET5K.rst
    network.LAN.rst
    network.PPP.rst
+   network.USB_NET.rst
 
 Network functions
 =================

diff --git a/extmod/extmod.cmake b/extmod/extmod.cmake
@@ -53,6 +53,7 @@ set(MICROPY_SOURCE_EXTMOD
     ${MICROPY_EXTMOD_DIR}/network_lwip.c
     ${MICROPY_EXTMOD_DIR}/network_ninaw10.c
     ${MICROPY_EXTMOD_DIR}/network_ppp_lwip.c
+    ${MICROPY_EXTMOD_DIR}/network_ncm.c
     ${MICROPY_EXTMOD_DIR}/network_wiznet5k.c
     ${MICROPY_EXTMOD_DIR}/os_dupterm.c
     ${MICROPY_EXTMOD_DIR}/vfs.c

diff --git a/extmod/extmod.mk b/extmod/extmod.mk
@@ -56,6 +56,7 @@ SRC_EXTMOD_C += \
 	extmod/network_lwip.c \
 	extmod/network_ninaw10.c \
 	extmod/network_ppp_lwip.c \
+	extmod/network_ncm.c \
 	extmod/network_wiznet5k.c \
 	extmod/os_dupterm.c \
 	extmod/vfs.c \

diff --git a/extmod/modnetwork.c b/extmod/modnetwork.c
@@ -55,6 +55,11 @@ extern const struct _mp_obj_type_t mod_network_nic_type_nina;
 extern const struct _mp_obj_type_t mod_network_esp_hosted_type;
 #endif
 
+#if MICROPY_PY_NETWORK_NCM
+extern const struct _mp_obj_type_t mod_network_nic_type_ncm;
+#include "extmod/network_ncm.h"
+#endif
+
 #ifdef MICROPY_PY_NETWORK_INCLUDEFILE
 #include MICROPY_PY_NETWORK_INCLUDEFILE
 #endif
@@ -75,6 +80,11 @@ char mod_network_hostname_data[MICROPY_PY_NETWORK_HOSTNAME_MAX_LEN + 1] = MICROP
 
 void mod_network_init(void) {
     mp_obj_list_init(&MP_STATE_PORT(mod_network_nic_list), 0);
+    #if MICROPY_PY_NETWORK_NCM
+    // Initialise the USB NCM netif early so it is ready when TinyUSB starts
+    // receiving packets during USB enumeration (before any Python code runs).
+    ncm_auto_init();
+    #endif
 }
 
 void mod_network_deinit(void) {
@@ -205,6 +215,10 @@ static const mp_rom_map_elem_t mp_module_network_globals_table[] = {
     { MP_ROM_QSTR(MP_QSTR_WLAN), MP_ROM_PTR(&mod_network_esp_hosted_type) },
     #endif
 
+    #if MICROPY_PY_NETWORK_NCM
+    { MP_ROM_QSTR(MP_QSTR_USB_NCM), MP_ROM_PTR(&mod_network_nic_type_ncm) },
+    #endif
+
     // Allow a port to take mostly full control of the network module.
     #ifdef MICROPY_PY_NETWORK_MODULE_GLOBALS_INCLUDEFILE
     #include MICROPY_PY_NETWORK_MODULE_GLOBALS_INCLUDEFILE