嵌入式语言运行时编程语言解释器编译器物联网系统编程【免费下载链接】micropythonMicroPython - a lean and efficient Python implementation for microcontrollers and constrained systems项目地址https://gitcode.com/gh_mirrors/mi/micropython点击查看免费下载本指南以 MicroPython 仓库中的 docs/library/network.rst 为主体系统讲解network模块的架构设计、AbstractNIC通用网络适配器接口active/connect/scan/status/ipconfig/config 等的完整方法契约、各具体 NIC 类WLAN、LAN、WIZNET5K、PPP、USBD_NCM 等的差异与用法以及country、hostname、ipconfig、phy_mode等模块级函数的实战细节。读完本文你将掌握在任意带网络能力的 MicroPython 固件上连接网络接口 → 查询/配置 IP → 通过 socket 收发数据的完整技能并能从源码层面理解 hostname 长度限制、IPv6 地址状态位、WiFi 安全等级等底层约定。一、模块定位与使用前提network模块提供网络驱动与路由配置能力。它的使用有一个硬性前提必须安装带网络能力的 MicroPython 变体或构建例如 esp32、esp8266、rp2、mimxrt、stm32 等端口的联网固件。具体硬件的网络驱动以类的形式挂载在本模块内用于配置硬件网络接口配置好的接口所提供的网络服务则通过socket模块对外使用。从源码看模块的组成清晰可见extmod/modnetwork.c 中的mp_module_network_globals_table定义了模块的全局表其中既有通用函数country、hostname、ipconfig也有按端口条件编译注册的驱动类型如WLAN、WIZNET5K、USBD_NCM、PPP以及STA_IF/AP_IF接口常量与STAT_*状态常量。也就是说不同端口暴露的网络类集合是不同的这一点在选择 API 时需要格外留意。二、快速上手从连接接口到 socket 通信文档给出了一个端到端的完整示例先连上网络接口再像桌面 Python 一样使用 socketimport network import time # 创建并激活一个具体网络接口各驱动示例见后文 nic network.Driver(...) if not nic.isconnected(): nic.connect() print(Waiting for connection...) while not nic.isconnected(): time.sleep(1) # 查询 IPv4 地址 print(nic.ipconfig(addr4)) # 现在可以像平时一样使用 socket import socket addr socket.getaddrinfo(micropython.org, 80)[0][-1] s socket.socket() s.connect(addr) s.send(bGET / HTTP/1.1\r\nHost: micropython.org\r\n\r\n) data s.recv(1000) s.close()这个模式是所有 NIC 类的通用骨架实例化 → 激活 → 连接 → 轮询 isconnected → 配置/查询 IP → socket 通信。其中time.sleep(1)的轮询是为了等待 DHCP 或链路建立完成实际项目中常用time.sleep_ms(100)甚至配合超时计数来加快响应。三、通用网络适配器接口AbstractNICnetwork模块的核心设计是一套隐含的抽象基类。MicroPython 并不真正提供一个名为AbstractNIC的类而是约定任何具体 NIC 类都必须实现下述方法。这种鸭子类型约定使得跨端口的网络代码具有高度一致性。3.1 构造与生命周期active()class AbstractNIC(idNone, ...) nic.active([is_active]) # 传布尔值up/down不传查询当前状态构造参数随接口类型而定若同类型接口有多个第一个参数应为id。active(True)把接口拉起来active(False)使其down。大部分其他方法都要求接口处于 active 状态在 inactive 接口上调用它们的行为是未定义的。3.2 连接管理connect()/disconnect()/isconnected()nic.connect([service_id, keyNone, *, ...]) nic.disconnect() nic.isconnected() # True/Falseconnect()是可选方法仅对非常连接型接口存在。无参数时连接默认或唯一服务单参数时该参数是服务的首要标识符如 WiFi 的 SSID可附带key密码。允许额外的关键字参数用于指定替代的服务标识类型或补充连接参数。文档明确推荐的一类WiFi 的bssid关键字用于连接指定 BSSID接入点的 MAC 地址的服务。disconnect()断开网络isconnected()返回连接状态布尔值。3.3 服务扫描scan(*, ...)results nic.scan(...) # 返回服务参数元组的列表扫描可用网络服务返回元组列表。不同介质有各自推荐的元组格式文档给出的 WiFi 格式为(ssid, bssid, channel, RSSI, security, hidden)函数可接收关键字参数来过滤结果如按特定服务、信道、服务集合过滤并影响扫描时长等参数。设计上过滤参数名应尽量与connect()保持一致便于记忆与复用。3.4 动态状态查询status([param])nic.status() # 返回网络链路状态 nic.status(rssi) # WiFi STA查询 AP 信号强度 RSSI nic.status(stations) # WiFi AP查询已连接 STA 列表 [(MAC, RSSI)]无参数时返回链路状态有参数时按字符串名查询特定状态。返回值类型与取值取决于网络介质WiFi STArssi返回 AP 信号强度指示值WiFi APstations返回已连接 STA 的(MAC, RSSI)元组列表。3.5 核心 IP 配置ipconfig(param)/ipconfig(paramvalue, ...)这是文档篇幅最大、也最重要的方法用于获取或设置接口级 IP 配置参数。以下参数是否可用取决于端口和具体接口参数含义与用法dhcp4True/False通过 DHCP 获取 IPv4 地址、网关与 DNS。不阻塞等待地址获取是否已取得地址用只读属性has_dhcp4检查gw4获取/设置 IPv4 默认网关dhcp6True/False通过无状态 DHCPv6 获取 DNS 服务器。当前尚未实现通过 DHCPv6 获取 IPv6 地址autoconf6True/False通过路由器通告RA中的网络前缀获取无状态 IPv6 地址是否已取得用只读属性has_autoconf6检查addr4获取当前 IPv4 地址与子网掩码返回(ip, subnet)元组如192.168.0.4/24也可用于设置静态 IPv4 地址既接受(ip, subnet)元组也接受 CIDR 记法addr6获取当前 IPv6 地址列表返回(ip, state, preferred_lifetime, valid_lifetime)元组含 link-local、slaac 与静态地址preferred_lifetime和valid_lifetime为剩余有效/优先生命周期秒也可设置为静态 IPv6 地址如fe80::1234:5678IPv6 地址state字段取值语义重要常用于判断地址是否可用0x08–0x0f地址处于 tentative暂定状态数值表示已发送的探测次数0x10地址已 deprecated弃用但仍有效0x30地址 preferred优先且有效0x40地址 duplicated重复冲突不可使用。3.6 传统接口ifconfig()已弃用nic.ifconfig() # 返回 (ip, subnet, gateway, dns) 四元组 nic.ifconfig((192.168.0.4, 255.255.255.0, 192.168.0.1, 8.8.8.8)) # 设置注意文档明确标注ifconfig()已弃用请改用ipconfig()。3.7 通用参数配置config(param)/config(paramvalue, ...)用于处理超出标准 IP 配置ipconfig()范畴之外的网络相关与硬件相关参数。设置时用关键字语法、可一次设置多个查询时参数名用字符串、一次只能查一个# 设置 WiFi AP 名称即 SSID与信道 ap.config(ssidMy AP, channel11) # 逐个查询 print(ap.config(ssid)) print(ap.config(channel))四、具体 NIC 类实现一览文档的Specific network class implementations一节列出六个具体实现类并分别有独立子文档network.WLAN内置 WiFinetwork.WLANWiPyWiPy 专用 WiFinetwork.WIZNET5KWIZnet 5x00 以太网network.LAN板载以太网network.PPP串口 PPP 拨号network.USBD_NCMUSB NCM 虚拟网卡下面逐一给出关键构造与差异点。4.1 WLAN内置 WiFi 接口import network nic network.WLAN(network.WLAN.IF_STA) # 或 network.WLAN.IF_AP nic.active(True) nic.connect(your-ssid, your-key) # 之后正常使用 socket构造函数WLAN(interface_id)IF_STA表示站点客户端连接上游 APIF_AP表示接入点允许其他 WiFi 客户端接入。方法可用性随接口类型而异例如只有 STA 接口能connect()到 AP。connect(ssidNone, keyNone, *, bssidNone)bssid用于把连接限定到指定 MAC 的 AP此时必须同时给出ssid。scan()仅 STA 接口可用返回(ssid, bssid, channel, RSSI, security, hidden)元组列表。bssid是二进制形式的硬件地址可用binascii.hexlify()转成 ASCII。security 取值0开放、1WEP、2WPA-PSK、3WPA2-PSK、4WPA/WPA2-PSKhidden 取值0可见、1隐藏。status()无参数时返回链路状态对应network模块中的常量STAT_IDLE无连接无活动、STAT_CONNECTING连接中、STAT_WRONG_PASSWORD密码错误、STAT_NO_AP_FOUND无 AP 响应、STAT_CONNECT_FAIL其他原因失败、STAT_GOT_IP连接成功。status(rssi)STA 模式与status(stations)AP 模式在除 CC3200 外的所有支持 WiFi 的端口可用。isconnected()STA 模式下已连接 AP 且持有有效 IP才返回TrueAP 模式下有站点接入即返回True。config()常用参数可用性取决于技术类型、驱动与端口参数说明macMAC 地址bytesssidWiFi AP 名称stringchannelWiFi 信道整数视端口可能仅 AP 接口支持hiddenSSID 是否隐藏booleansecurity安全协议枚举见模块常量key访问密钥stringhostname发送给 DHCP 的主机名STAmDNS若支持STA/AP 均可。已弃用改用network.hostname()reconnects重连尝试次数整数0不重连-1无限txpower最大发射功率dBm整数或浮点pmWiFi 电源管理设置见下方常量protocol仅 ESP32802.11 低层协议见WLAN.PROTOCOL_DEFAULTbandwidth仅 ESP32信道带宽见WLAN.BANDWIDTH_20等电源管理常量config(pm...)的合法值PM_PERFORMANCE在省电与性能间平衡、PM_POWERSAVE更多省电、性能下降、PM_NONE关闭 WiFi 电源管理。ESP32 协议常量PROTOCOL_DEFAULT芯片默认支持的 802.11 模式位图PROTOCOL_LR乐鑫专有远距离模式与标准 WiFi 不兼容可与标准协议位按位或组合使用支持 ESP-NOW 远距离模式ESP32-C2 不支持。带宽常量BANDWIDTH_20/40/80/160/80_8020/40在 STA 与 AP 模式均可用80/160/80_80多天线 8080MHz仅 AP 模式且未必所有 ESP32 型号支持STA 模式下只能在未连接网络时修改带宽AP 模式随时可改。CSI 方法仅 ESP32需启用 CSI 支持标准 ESP32、ESP32-C3/C5/C6/S3 的默认板卡定义已启用其他构建需在 ESP-IDF 配置中设CONFIG_ESP_WIFI_CSI_ENABLEDy。CSI 基于收到的 WiFi 帧提供逐包物理层信道数据采集需要活动的 WiFi 连接与持续入站流量。方法包括csi_enable(buffer_size16)分配环形缓冲上限由底层 ringbuffer 限制在约 100 帧失败抛OSError、csi_disable()、csi_read([result])返回 22 字段的帧列表含 rssi、channel、mac、timestamp、CSI 原始 I/Q 数据bytearray、rate、mcs、noise_floor 等传入上次结果列表可在原地复用、降低堆碎片、csi_available()、csi_dropped()。仓库自带完整示例可参考 examples/esp32_wifi_csi。4.2 LAN板载以太网import network nic network.LAN(0) print(nic.ipconfig(addr4))构造函数LAN(id, *, phy_typeboard_default, phy_addrboard_default, ref_clk_modeboard_default)id是以太网口编号0 或 1phy_type是 PHY 驱动名多数板用板载 PHY取默认值phy_addr是 PHY 接口地址ref_clk_mode指定数据时钟由谁提供LAN.OUT/Pin.OUT/True表示由以太网控制器驱动LAN.IN/Pin.IN/False表示由 PHY 驱动。示例Seeed Arch Mix 板nic LAN(0, phy_typeLAN.PHY_LAN8720, phy_addr1, ref_clk_modePin.IN)。注意esp32 端口的 LAN 构造参数不同参见 esp32 快速参考 中对应章节。方法active([state])、isconnected()物理链路连通且 up 返回True、status()、ifconfig()、config()。config()可查询的只有 MACmac LAN.config(mac)可设置tracen2跟踪 TX、4跟踪 RX、8完整跟踪与low_powerbool。mimxrt 端口支持PHY_KSZ8081、PHY_DP83825、PHY_DP83848、PHY_LAN8720、PHY_RTL8211F。4.3 WIZNET5K外挂 WIZnet 5x00 以太网模块import network nic network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4) print(nic.ipconfig(addr4))支持基于 W5200/W5500 芯片的以太网适配器固件编译时通过MICROPY_PY_NETWORK_WIZNET5K选项选择芯片esp32 端口对 W5500 走的是network.LAN接口。构造函数WIZNET5K(spi, pin_cs, pin_rst)spi为连接的 SPI 总线MOSI/MISO/SCLKpin_cs接 nSS 引脚pin_rst接 nRESET 引脚。三者都会被驱动初始化无需手动配置。示例接线pyboardMOSI→X8、MISO→X7、SCLK→X6、nSS→X5、nRESET→X4也支持其他 SPI 总线与其他引脚。额外方法regs()转储 WIZnet 寄存器用于调试。4.4 PPP串口 PPP 拨号网络import network ppp network.PPP(uart) ppp.connect() while not ppp.isconnected(): pass print(ppp.ipconfig(addr4)) ppp.disconnect()在串口上建立 PPP 网络连接。默认固件只有 esp32 端口启用stm32、rp2 端口可在自定义构建中设MICROPY_PY_NETWORK_PPP_LWIP1并启用联网支持来开启。构造函数PPP(stream)stream是任意支持流协议的对象最常见是machine.UART必须具有irq()方法与IRQ_RXIDLE常量供connect()使用。connect(securitySEC_NONE, userNone, keyNone)security 取PPP.SEC_NONE、PPP.SEC_PAP或PPP.SEC_CHAP。调用时底层流会执行stream.irq(ppp.poll, stream.IRQ_RXIDLE)只要流上有数据就轮询并送入 PPP 栈连接在后台异步进行。disconnect()必须调用以干净关闭连接另有status()、config()唯一可读写参数是底层流stream PPP.config(stream)、PPP.config(streamstream)、ipconfig()、ifconfig()与poll([irq_arg])通常由 UART 的 RXIDLE 中断自动调用无需手动irq_arg仅为兼容machine.UART.irq的 handler 签名而存在。4.5 USBD_NCMUSB 虚拟以太网NCMimport network nic network.USBD_NCM() nic.active(True) while not nic.isconnected(): pass print(nic.ipconfig(addr4))通过 USB NCMNetwork Control Model协议提供网络接口主机把设备识别为 USB 以太网适配器并由 MicroPython 设备侧提供 DHCP 给主机分配 IP。需要端口具备 TinyUSB 与 NCM 支持构建时定义MICROPY_PY_NETWORK_USBD_NCM默认关闭。从 extmod/modnetwork.c 可见启用后mod_network_init()会在 USB 枚举开始前提前初始化 NCM 网卡ncm_auto_init()确保任何 Python 代码运行前即可收发包。USBD_NCM()是单例active()在 USB 枚举前会自动拉起接口因此开机即返回Trueisconnected()表示 USB 主机是否已配置 NCM 接口——USB 断开时返回False且流量停止但接口仍注册在 lwIP 中主机重连重新枚举后可恢复status()返回整数1up/0down。两个重要注意事项设备 IP169.254.x.1由设备 MAC 确定性推导未实现 RFC 3927 的 ARP 探测/通告冲突检测两台设备若推导出同网段相同地址将无法察觉冲突设备端与主机端 MAC 均由mp_hal_get_mac()推导若两块板卡硬件 MAC 相同如端口未使用硬件 UID会出现相同的网络地址并引发 ARP 冲突。4.6 WLANWiPyWiPy 专用 WiFiWiPy 上的非标准 WLAN 实现在 WiPy 上以network.WLAN名字可用文档中为区分命名为WLANWiPy。构造、init(mode, *, ssid, auth, channel, antenna)、connect(ssid, *, authNone, bssidNone, timeoutNone)、scan()、irq(*, handler, wake)machine.SLEEP模式下由 socket 活动或 WLAN 连接/断开触发回调等详见 network.WLANWiPy.rst。其ipconfig()仅支持dhcp4、addr4、gw4三个参数。安全类型WEP/WPA/WPA2WEP 密钥必须是十六进制字符串如ABC1DE45BF天线选择INT_ANT/EXT_ANTAP 信道范围 1–11。五、模块级函数5.1country([code])获取/设置用于无线电合规的两位 ISO 3166-1 Alpha-2 国家码。传参则设置返回None不传则返回当前值。默认码XX表示全球区域。源码实现extmod/modnetwork.c内部存储为char mod_network_country_code[2] XX;的固定 2 字节缓冲传入字符串长度必须恰为 2否则抛出ValueError设置时取前两个字符写入。该函数在源码中保留为mod_network_country_obj并注释说明其为向后兼容pyb.country而保持非静态。5.2hostname([name])获取/设置设备在网络中标识自身的主机名对所有接口生效用途包括发送到 DHCP 服务器的客户端请求中若使用 DHCP通过 mDNS 广播若启用。关键约束主机名变更通常只在连接时生效——DHCP 请求里携带主机名而多数端口的 mDNS 实现只在连接时初始化一次主机名因此必须在激活/连接网络接口之前设置 hostname长度上限32 字符端口可能为省内存设置更低上限超限抛ValueError默认主机名通常是板卡名称。源码实现extmod/modnetwork.c内部存储为char mod_network_hostname_data[MICROPY_PY_NETWORK_HOSTNAME_MAX_LEN 1]初值来自MICROPY_PY_NETWORK_HOSTNAME_DEFAULT该宏必须在mpconfigport.h或mpconfigboard.h中定义否则编译报错设置时若len MICROPY_PY_NETWORK_HOSTNAME_MAX_LEN直接抛ValueError。5.3ipconfig(param)/ipconfig(paramvalue, ...)获取/设置全局IP 配置参数区别于接口级的AbstractNIC.ipconfig()是否可用取决于端口与接口参数说明dns获取/设置 DNS 服务器同时支持 IPv4 与 IPv6 地址prefer取值4/6指定当域名同时有 A 与 AAAA 记录时返回哪种地址类型。注意不会清空本地 DNS 缓存因此之前已取得的地址可能不会立即变化源码层面该函数仅在LWIP_VERSION_MAJOR 2或启用 NINA W10 驱动时注册extmod/modnetwork.c。5.4phy_mode([mode])获取/设置 PHY 模式仅 ESP8266 端口可用。可选模式常量为MODE_11BIEEE 802.11b、MODE_11GIEEE 802.11g、MODE_11NIEEE 802.11n。六、源码级视角NIC 注册与模块装配从源码可以更完整地理解network模块的装配逻辑extmod/modnetwork.cNIC 注册表mod_network_register_nic()把实例化出的 NIC 追加到全局列表mod_network_nic_list已注册则跳过mod_network_find_nic()按 IP 查找合适的 NICroute函数直接返回该列表extmod/modnetwork.c。条件编译装配模块全局表按MICROPY_PY_NETWORK_*宏决定暴露哪些类型——例如MICROPY_PY_NETWORK_CYW43时注册WLANrp2 等端口使用 CYW43 驱动并导出STAT_*状态常量MICROPY_PY_NETWORK_WIZNET5K时注册WIZNET5KMICROPY_PY_NETWORK_USBD_NCM时注册USBD_NCMMICROPY_PY_NETWORK_PPP_LWIP时注册PPP。接口常量STA_IF/AP_IF在未通过MICROPY_PY_NETWORK_MODULE_GLOBALS_INCLUDEFILE定制时默认导出其值来自MOD_NETWORK_STA_IF/MOD_NETWORK_AP_IF。这意味着你在某个端口固件上能否import network后使用某类、某常量完全由该端口构建时的编译宏决定编写可移植代码时应先探测或查阅对应端口文档。七、实战要点小结先active(True)再connect()并轮询isconnected()等待链路就绪大部分方法在 inactive 接口上行为未定义。IP 配置统一走ipconfig()ifconfig()已弃用IPv4 静态地址既支持(ip, subnet)元组也支持192.168.0.4/24的 CIDR 记法。IPv6 地址要结合state字段判断可用性0x30preferred才是正常可用状态tentative0x08–0x0f、deprecated0x10、duplicated0x40都各有含义。设置network.hostname()必须在连接接口之前且最长 32 字符或端口更低上限。跨端口差异是常态phy_mode()仅 ESP8266protocol/bandwidth仅 ESP32PPP 默认仅 esp32 固件启用WLANWiPy 仅 WiPy。写可移植代码时务必查阅目标端口文档如 docs/esp32/quickref.rst、docs/rp2/quickref.rst 等。各驱动类的完整独立文档可从本指南对应小节进入WLAN、WLANWiPy、WIZNET5K、LAN、PPP、USBD_NCM其文档文件均位于 docs/library 目录。通过本文覆盖的 AbstractNIC 方法契约与六类具体驱动配合socket模块你已具备在 MicroPython 设备上完成从点亮网卡到跑通网络应用的全部基础能力。赞分享嵌入式语言运行时编程语言解释器编译器物联网系统编程【免费下载链接】micropythonMicroPython - a lean and efficient Python implementation for microcontrollers and constrained systems项目地址https://gitcode.com/gh_mirrors/mi/micropython点击查看免费下载相关推荐MicroPython network.LAN 完全指南以太网接口的驱动选择、时钟模式与调试配置MicroPython network.LAN 完全指南以太网接口的驱动选择、时钟模式与调试配置 network.LAN 是 MicroPython 提供的以嵌入式语言运行时编程语言解释器编译器物联网系统编程Wand-Enhancer 完整使用指南免费解锁 WeMod 全部 Pro 功能三步跑通本地补丁工具Wand Enhancer 完整使用指南免费解锁 WeMod 全部 Pro 功能三步跑通本地补丁工具 如果你用过 WeModWand 就是它的新一代客户端桌面应用前端bottom 网络图Network Graph配置完全指南从单位制式到接口过滤bottom 网络图Network Graph配置完全指南从单位制式到接口过滤 bottom 是一款跨平台的图形化进程/系统监控工具Yet anothe运维观测指标监控CLI上一篇bytedance/sonic项目在Go 1.24中的兼容性问题解析下一篇告别卡顿DXVK帧时间优化完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 MicroPython network 模块完全指南：通用网络适配器接口与 NIC 驱动的配置实践
嵌入式语言运行时编程语言解释器编译器物联网系统编程【免费下载链接】micropythonMicroPython - a lean and efficient Python implementation for microcontrollers and constrained systems项目地址https://gitcode.com/gh_mirrors/mi/micropython点击查看免费下载本指南以 MicroPython 仓库中的 docs/library/network.rst 为主体系统讲解network模块的架构设计、AbstractNIC通用网络适配器接口active/connect/scan/status/ipconfig/config 等的完整方法契约、各具体 NIC 类WLAN、LAN、WIZNET5K、PPP、USBD_NCM 等的差异与用法以及country、hostname、ipconfig、phy_mode等模块级函数的实战细节。读完本文你将掌握在任意带网络能力的 MicroPython 固件上连接网络接口 → 查询/配置 IP → 通过 socket 收发数据的完整技能并能从源码层面理解 hostname 长度限制、IPv6 地址状态位、WiFi 安全等级等底层约定。一、模块定位与使用前提network模块提供网络驱动与路由配置能力。它的使用有一个硬性前提必须安装带网络能力的 MicroPython 变体或构建例如 esp32、esp8266、rp2、mimxrt、stm32 等端口的联网固件。具体硬件的网络驱动以类的形式挂载在本模块内用于配置硬件网络接口配置好的接口所提供的网络服务则通过socket模块对外使用。从源码看模块的组成清晰可见extmod/modnetwork.c 中的mp_module_network_globals_table定义了模块的全局表其中既有通用函数country、hostname、ipconfig也有按端口条件编译注册的驱动类型如WLAN、WIZNET5K、USBD_NCM、PPP以及STA_IF/AP_IF接口常量与STAT_*状态常量。也就是说不同端口暴露的网络类集合是不同的这一点在选择 API 时需要格外留意。二、快速上手从连接接口到 socket 通信文档给出了一个端到端的完整示例先连上网络接口再像桌面 Python 一样使用 socketimport network import time # 创建并激活一个具体网络接口各驱动示例见后文 nic network.Driver(...) if not nic.isconnected(): nic.connect() print(Waiting for connection...) while not nic.isconnected(): time.sleep(1) # 查询 IPv4 地址 print(nic.ipconfig(addr4)) # 现在可以像平时一样使用 socket import socket addr socket.getaddrinfo(micropython.org, 80)[0][-1] s socket.socket() s.connect(addr) s.send(bGET / HTTP/1.1\r\nHost: micropython.org\r\n\r\n) data s.recv(1000) s.close()这个模式是所有 NIC 类的通用骨架实例化 → 激活 → 连接 → 轮询 isconnected → 配置/查询 IP → socket 通信。其中time.sleep(1)的轮询是为了等待 DHCP 或链路建立完成实际项目中常用time.sleep_ms(100)甚至配合超时计数来加快响应。三、通用网络适配器接口AbstractNICnetwork模块的核心设计是一套隐含的抽象基类。MicroPython 并不真正提供一个名为AbstractNIC的类而是约定任何具体 NIC 类都必须实现下述方法。这种鸭子类型约定使得跨端口的网络代码具有高度一致性。3.1 构造与生命周期active()class AbstractNIC(idNone, ...) nic.active([is_active]) # 传布尔值up/down不传查询当前状态构造参数随接口类型而定若同类型接口有多个第一个参数应为id。active(True)把接口拉起来active(False)使其down。大部分其他方法都要求接口处于 active 状态在 inactive 接口上调用它们的行为是未定义的。3.2 连接管理connect()/disconnect()/isconnected()nic.connect([service_id, keyNone, *, ...]) nic.disconnect() nic.isconnected() # True/Falseconnect()是可选方法仅对非常连接型接口存在。无参数时连接默认或唯一服务单参数时该参数是服务的首要标识符如 WiFi 的 SSID可附带key密码。允许额外的关键字参数用于指定替代的服务标识类型或补充连接参数。文档明确推荐的一类WiFi 的bssid关键字用于连接指定 BSSID接入点的 MAC 地址的服务。disconnect()断开网络isconnected()返回连接状态布尔值。3.3 服务扫描scan(*, ...)results nic.scan(...) # 返回服务参数元组的列表扫描可用网络服务返回元组列表。不同介质有各自推荐的元组格式文档给出的 WiFi 格式为(ssid, bssid, channel, RSSI, security, hidden)函数可接收关键字参数来过滤结果如按特定服务、信道、服务集合过滤并影响扫描时长等参数。设计上过滤参数名应尽量与connect()保持一致便于记忆与复用。3.4 动态状态查询status([param])nic.status() # 返回网络链路状态 nic.status(rssi) # WiFi STA查询 AP 信号强度 RSSI nic.status(stations) # WiFi AP查询已连接 STA 列表 [(MAC, RSSI)]无参数时返回链路状态有参数时按字符串名查询特定状态。返回值类型与取值取决于网络介质WiFi STArssi返回 AP 信号强度指示值WiFi APstations返回已连接 STA 的(MAC, RSSI)元组列表。3.5 核心 IP 配置ipconfig(param)/ipconfig(paramvalue, ...)这是文档篇幅最大、也最重要的方法用于获取或设置接口级 IP 配置参数。以下参数是否可用取决于端口和具体接口参数含义与用法dhcp4True/False通过 DHCP 获取 IPv4 地址、网关与 DNS。不阻塞等待地址获取是否已取得地址用只读属性has_dhcp4检查gw4获取/设置 IPv4 默认网关dhcp6True/False通过无状态 DHCPv6 获取 DNS 服务器。当前尚未实现通过 DHCPv6 获取 IPv6 地址autoconf6True/False通过路由器通告RA中的网络前缀获取无状态 IPv6 地址是否已取得用只读属性has_autoconf6检查addr4获取当前 IPv4 地址与子网掩码返回(ip, subnet)元组如192.168.0.4/24也可用于设置静态 IPv4 地址既接受(ip, subnet)元组也接受 CIDR 记法addr6获取当前 IPv6 地址列表返回(ip, state, preferred_lifetime, valid_lifetime)元组含 link-local、slaac 与静态地址preferred_lifetime和valid_lifetime为剩余有效/优先生命周期秒也可设置为静态 IPv6 地址如fe80::1234:5678IPv6 地址state字段取值语义重要常用于判断地址是否可用0x08–0x0f地址处于 tentative暂定状态数值表示已发送的探测次数0x10地址已 deprecated弃用但仍有效0x30地址 preferred优先且有效0x40地址 duplicated重复冲突不可使用。3.6 传统接口ifconfig()已弃用nic.ifconfig() # 返回 (ip, subnet, gateway, dns) 四元组 nic.ifconfig((192.168.0.4, 255.255.255.0, 192.168.0.1, 8.8.8.8)) # 设置注意文档明确标注ifconfig()已弃用请改用ipconfig()。3.7 通用参数配置config(param)/config(paramvalue, ...)用于处理超出标准 IP 配置ipconfig()范畴之外的网络相关与硬件相关参数。设置时用关键字语法、可一次设置多个查询时参数名用字符串、一次只能查一个# 设置 WiFi AP 名称即 SSID与信道 ap.config(ssidMy AP, channel11) # 逐个查询 print(ap.config(ssid)) print(ap.config(channel))四、具体 NIC 类实现一览文档的Specific network class implementations一节列出六个具体实现类并分别有独立子文档network.WLAN内置 WiFinetwork.WLANWiPyWiPy 专用 WiFinetwork.WIZNET5KWIZnet 5x00 以太网network.LAN板载以太网network.PPP串口 PPP 拨号network.USBD_NCMUSB NCM 虚拟网卡下面逐一给出关键构造与差异点。4.1 WLAN内置 WiFi 接口import network nic network.WLAN(network.WLAN.IF_STA) # 或 network.WLAN.IF_AP nic.active(True) nic.connect(your-ssid, your-key) # 之后正常使用 socket构造函数WLAN(interface_id)IF_STA表示站点客户端连接上游 APIF_AP表示接入点允许其他 WiFi 客户端接入。方法可用性随接口类型而异例如只有 STA 接口能connect()到 AP。connect(ssidNone, keyNone, *, bssidNone)bssid用于把连接限定到指定 MAC 的 AP此时必须同时给出ssid。scan()仅 STA 接口可用返回(ssid, bssid, channel, RSSI, security, hidden)元组列表。bssid是二进制形式的硬件地址可用binascii.hexlify()转成 ASCII。security 取值0开放、1WEP、2WPA-PSK、3WPA2-PSK、4WPA/WPA2-PSKhidden 取值0可见、1隐藏。status()无参数时返回链路状态对应network模块中的常量STAT_IDLE无连接无活动、STAT_CONNECTING连接中、STAT_WRONG_PASSWORD密码错误、STAT_NO_AP_FOUND无 AP 响应、STAT_CONNECT_FAIL其他原因失败、STAT_GOT_IP连接成功。status(rssi)STA 模式与status(stations)AP 模式在除 CC3200 外的所有支持 WiFi 的端口可用。isconnected()STA 模式下已连接 AP 且持有有效 IP才返回TrueAP 模式下有站点接入即返回True。config()常用参数可用性取决于技术类型、驱动与端口参数说明macMAC 地址bytesssidWiFi AP 名称stringchannelWiFi 信道整数视端口可能仅 AP 接口支持hiddenSSID 是否隐藏booleansecurity安全协议枚举见模块常量key访问密钥stringhostname发送给 DHCP 的主机名STAmDNS若支持STA/AP 均可。已弃用改用network.hostname()reconnects重连尝试次数整数0不重连-1无限txpower最大发射功率dBm整数或浮点pmWiFi 电源管理设置见下方常量protocol仅 ESP32802.11 低层协议见WLAN.PROTOCOL_DEFAULTbandwidth仅 ESP32信道带宽见WLAN.BANDWIDTH_20等电源管理常量config(pm...)的合法值PM_PERFORMANCE在省电与性能间平衡、PM_POWERSAVE更多省电、性能下降、PM_NONE关闭 WiFi 电源管理。ESP32 协议常量PROTOCOL_DEFAULT芯片默认支持的 802.11 模式位图PROTOCOL_LR乐鑫专有远距离模式与标准 WiFi 不兼容可与标准协议位按位或组合使用支持 ESP-NOW 远距离模式ESP32-C2 不支持。带宽常量BANDWIDTH_20/40/80/160/80_8020/40在 STA 与 AP 模式均可用80/160/80_80多天线 8080MHz仅 AP 模式且未必所有 ESP32 型号支持STA 模式下只能在未连接网络时修改带宽AP 模式随时可改。CSI 方法仅 ESP32需启用 CSI 支持标准 ESP32、ESP32-C3/C5/C6/S3 的默认板卡定义已启用其他构建需在 ESP-IDF 配置中设CONFIG_ESP_WIFI_CSI_ENABLEDy。CSI 基于收到的 WiFi 帧提供逐包物理层信道数据采集需要活动的 WiFi 连接与持续入站流量。方法包括csi_enable(buffer_size16)分配环形缓冲上限由底层 ringbuffer 限制在约 100 帧失败抛OSError、csi_disable()、csi_read([result])返回 22 字段的帧列表含 rssi、channel、mac、timestamp、CSI 原始 I/Q 数据bytearray、rate、mcs、noise_floor 等传入上次结果列表可在原地复用、降低堆碎片、csi_available()、csi_dropped()。仓库自带完整示例可参考 examples/esp32_wifi_csi。4.2 LAN板载以太网import network nic network.LAN(0) print(nic.ipconfig(addr4))构造函数LAN(id, *, phy_typeboard_default, phy_addrboard_default, ref_clk_modeboard_default)id是以太网口编号0 或 1phy_type是 PHY 驱动名多数板用板载 PHY取默认值phy_addr是 PHY 接口地址ref_clk_mode指定数据时钟由谁提供LAN.OUT/Pin.OUT/True表示由以太网控制器驱动LAN.IN/Pin.IN/False表示由 PHY 驱动。示例Seeed Arch Mix 板nic LAN(0, phy_typeLAN.PHY_LAN8720, phy_addr1, ref_clk_modePin.IN)。注意esp32 端口的 LAN 构造参数不同参见 esp32 快速参考 中对应章节。方法active([state])、isconnected()物理链路连通且 up 返回True、status()、ifconfig()、config()。config()可查询的只有 MACmac LAN.config(mac)可设置tracen2跟踪 TX、4跟踪 RX、8完整跟踪与low_powerbool。mimxrt 端口支持PHY_KSZ8081、PHY_DP83825、PHY_DP83848、PHY_LAN8720、PHY_RTL8211F。4.3 WIZNET5K外挂 WIZnet 5x00 以太网模块import network nic network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4) print(nic.ipconfig(addr4))支持基于 W5200/W5500 芯片的以太网适配器固件编译时通过MICROPY_PY_NETWORK_WIZNET5K选项选择芯片esp32 端口对 W5500 走的是network.LAN接口。构造函数WIZNET5K(spi, pin_cs, pin_rst)spi为连接的 SPI 总线MOSI/MISO/SCLKpin_cs接 nSS 引脚pin_rst接 nRESET 引脚。三者都会被驱动初始化无需手动配置。示例接线pyboardMOSI→X8、MISO→X7、SCLK→X6、nSS→X5、nRESET→X4也支持其他 SPI 总线与其他引脚。额外方法regs()转储 WIZnet 寄存器用于调试。4.4 PPP串口 PPP 拨号网络import network ppp network.PPP(uart) ppp.connect() while not ppp.isconnected(): pass print(ppp.ipconfig(addr4)) ppp.disconnect()在串口上建立 PPP 网络连接。默认固件只有 esp32 端口启用stm32、rp2 端口可在自定义构建中设MICROPY_PY_NETWORK_PPP_LWIP1并启用联网支持来开启。构造函数PPP(stream)stream是任意支持流协议的对象最常见是machine.UART必须具有irq()方法与IRQ_RXIDLE常量供connect()使用。connect(securitySEC_NONE, userNone, keyNone)security 取PPP.SEC_NONE、PPP.SEC_PAP或PPP.SEC_CHAP。调用时底层流会执行stream.irq(ppp.poll, stream.IRQ_RXIDLE)只要流上有数据就轮询并送入 PPP 栈连接在后台异步进行。disconnect()必须调用以干净关闭连接另有status()、config()唯一可读写参数是底层流stream PPP.config(stream)、PPP.config(streamstream)、ipconfig()、ifconfig()与poll([irq_arg])通常由 UART 的 RXIDLE 中断自动调用无需手动irq_arg仅为兼容machine.UART.irq的 handler 签名而存在。4.5 USBD_NCMUSB 虚拟以太网NCMimport network nic network.USBD_NCM() nic.active(True) while not nic.isconnected(): pass print(nic.ipconfig(addr4))通过 USB NCMNetwork Control Model协议提供网络接口主机把设备识别为 USB 以太网适配器并由 MicroPython 设备侧提供 DHCP 给主机分配 IP。需要端口具备 TinyUSB 与 NCM 支持构建时定义MICROPY_PY_NETWORK_USBD_NCM默认关闭。从 extmod/modnetwork.c 可见启用后mod_network_init()会在 USB 枚举开始前提前初始化 NCM 网卡ncm_auto_init()确保任何 Python 代码运行前即可收发包。USBD_NCM()是单例active()在 USB 枚举前会自动拉起接口因此开机即返回Trueisconnected()表示 USB 主机是否已配置 NCM 接口——USB 断开时返回False且流量停止但接口仍注册在 lwIP 中主机重连重新枚举后可恢复status()返回整数1up/0down。两个重要注意事项设备 IP169.254.x.1由设备 MAC 确定性推导未实现 RFC 3927 的 ARP 探测/通告冲突检测两台设备若推导出同网段相同地址将无法察觉冲突设备端与主机端 MAC 均由mp_hal_get_mac()推导若两块板卡硬件 MAC 相同如端口未使用硬件 UID会出现相同的网络地址并引发 ARP 冲突。4.6 WLANWiPyWiPy 专用 WiFiWiPy 上的非标准 WLAN 实现在 WiPy 上以network.WLAN名字可用文档中为区分命名为WLANWiPy。构造、init(mode, *, ssid, auth, channel, antenna)、connect(ssid, *, authNone, bssidNone, timeoutNone)、scan()、irq(*, handler, wake)machine.SLEEP模式下由 socket 活动或 WLAN 连接/断开触发回调等详见 network.WLANWiPy.rst。其ipconfig()仅支持dhcp4、addr4、gw4三个参数。安全类型WEP/WPA/WPA2WEP 密钥必须是十六进制字符串如ABC1DE45BF天线选择INT_ANT/EXT_ANTAP 信道范围 1–11。五、模块级函数5.1country([code])获取/设置用于无线电合规的两位 ISO 3166-1 Alpha-2 国家码。传参则设置返回None不传则返回当前值。默认码XX表示全球区域。源码实现extmod/modnetwork.c内部存储为char mod_network_country_code[2] XX;的固定 2 字节缓冲传入字符串长度必须恰为 2否则抛出ValueError设置时取前两个字符写入。该函数在源码中保留为mod_network_country_obj并注释说明其为向后兼容pyb.country而保持非静态。5.2hostname([name])获取/设置设备在网络中标识自身的主机名对所有接口生效用途包括发送到 DHCP 服务器的客户端请求中若使用 DHCP通过 mDNS 广播若启用。关键约束主机名变更通常只在连接时生效——DHCP 请求里携带主机名而多数端口的 mDNS 实现只在连接时初始化一次主机名因此必须在激活/连接网络接口之前设置 hostname长度上限32 字符端口可能为省内存设置更低上限超限抛ValueError默认主机名通常是板卡名称。源码实现extmod/modnetwork.c内部存储为char mod_network_hostname_data[MICROPY_PY_NETWORK_HOSTNAME_MAX_LEN 1]初值来自MICROPY_PY_NETWORK_HOSTNAME_DEFAULT该宏必须在mpconfigport.h或mpconfigboard.h中定义否则编译报错设置时若len MICROPY_PY_NETWORK_HOSTNAME_MAX_LEN直接抛ValueError。5.3ipconfig(param)/ipconfig(paramvalue, ...)获取/设置全局IP 配置参数区别于接口级的AbstractNIC.ipconfig()是否可用取决于端口与接口参数说明dns获取/设置 DNS 服务器同时支持 IPv4 与 IPv6 地址prefer取值4/6指定当域名同时有 A 与 AAAA 记录时返回哪种地址类型。注意不会清空本地 DNS 缓存因此之前已取得的地址可能不会立即变化源码层面该函数仅在LWIP_VERSION_MAJOR 2或启用 NINA W10 驱动时注册extmod/modnetwork.c。5.4phy_mode([mode])获取/设置 PHY 模式仅 ESP8266 端口可用。可选模式常量为MODE_11BIEEE 802.11b、MODE_11GIEEE 802.11g、MODE_11NIEEE 802.11n。六、源码级视角NIC 注册与模块装配从源码可以更完整地理解network模块的装配逻辑extmod/modnetwork.cNIC 注册表mod_network_register_nic()把实例化出的 NIC 追加到全局列表mod_network_nic_list已注册则跳过mod_network_find_nic()按 IP 查找合适的 NICroute函数直接返回该列表extmod/modnetwork.c。条件编译装配模块全局表按MICROPY_PY_NETWORK_*宏决定暴露哪些类型——例如MICROPY_PY_NETWORK_CYW43时注册WLANrp2 等端口使用 CYW43 驱动并导出STAT_*状态常量MICROPY_PY_NETWORK_WIZNET5K时注册WIZNET5KMICROPY_PY_NETWORK_USBD_NCM时注册USBD_NCMMICROPY_PY_NETWORK_PPP_LWIP时注册PPP。接口常量STA_IF/AP_IF在未通过MICROPY_PY_NETWORK_MODULE_GLOBALS_INCLUDEFILE定制时默认导出其值来自MOD_NETWORK_STA_IF/MOD_NETWORK_AP_IF。这意味着你在某个端口固件上能否import network后使用某类、某常量完全由该端口构建时的编译宏决定编写可移植代码时应先探测或查阅对应端口文档。七、实战要点小结先active(True)再connect()并轮询isconnected()等待链路就绪大部分方法在 inactive 接口上行为未定义。IP 配置统一走ipconfig()ifconfig()已弃用IPv4 静态地址既支持(ip, subnet)元组也支持192.168.0.4/24的 CIDR 记法。IPv6 地址要结合state字段判断可用性0x30preferred才是正常可用状态tentative0x08–0x0f、deprecated0x10、duplicated0x40都各有含义。设置network.hostname()必须在连接接口之前且最长 32 字符或端口更低上限。跨端口差异是常态phy_mode()仅 ESP8266protocol/bandwidth仅 ESP32PPP 默认仅 esp32 固件启用WLANWiPy 仅 WiPy。写可移植代码时务必查阅目标端口文档如 docs/esp32/quickref.rst、docs/rp2/quickref.rst 等。各驱动类的完整独立文档可从本指南对应小节进入WLAN、WLANWiPy、WIZNET5K、LAN、PPP、USBD_NCM其文档文件均位于 docs/library 目录。通过本文覆盖的 AbstractNIC 方法契约与六类具体驱动配合socket模块你已具备在 MicroPython 设备上完成从点亮网卡到跑通网络应用的全部基础能力。赞分享嵌入式语言运行时编程语言解释器编译器物联网系统编程【免费下载链接】micropythonMicroPython - a lean and efficient Python implementation for microcontrollers and constrained systems项目地址https://gitcode.com/gh_mirrors/mi/micropython点击查看免费下载相关推荐MicroPython network.LAN 完全指南以太网接口的驱动选择、时钟模式与调试配置MicroPython network.LAN 完全指南以太网接口的驱动选择、时钟模式与调试配置 network.LAN 是 MicroPython 提供的以嵌入式语言运行时编程语言解释器编译器物联网系统编程Wand-Enhancer 完整使用指南免费解锁 WeMod 全部 Pro 功能三步跑通本地补丁工具Wand Enhancer 完整使用指南免费解锁 WeMod 全部 Pro 功能三步跑通本地补丁工具 如果你用过 WeModWand 就是它的新一代客户端桌面应用前端bottom 网络图Network Graph配置完全指南从单位制式到接口过滤bottom 网络图Network Graph配置完全指南从单位制式到接口过滤 bottom 是一款跨平台的图形化进程/系统监控工具Yet anothe运维观测指标监控CLI上一篇bytedance/sonic项目在Go 1.24中的兼容性问题解析下一篇告别卡顿DXVK帧时间优化完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考