USB modems, sticks and Ethernet adapters
From firmware 3.0.25 the gateway can use one USB device on the board's own USB port: a USB LTE modem or 4G stick for the mobile network (SIM) uplink, or a USB Ethernet adapter or Android USB tethering for the Ethernet uplink. The W5500 module and the modem wired to the pins keep working as before.
Experimental. These USB connections have not been tested with real devices yet. If you try one, report your board, cable and device: the Network page shows the device as vendor:product.
1. Which port
Most ESP32-S3 N8R8/N16R8 boards have two USB-C sockets:
| Label (varies) | What it is | Use it for |
|---|---|---|
| COM, UART, CH343, CP2102 | a USB-serial chip | flashing, logs, the browser installer, powering the board |
| USB, OTG, ESP32-S3 | the chip's own USB (GPIO19/20) | the USB device |
When a USB connection is enabled, the firmware turns the USB port into a USB host at boot. From then on, flash, read logs and power the board through the COM port or the 5V/GND pins. A computer plugged into the USB port no longer sees the board.
- USB-A devices (most sticks and adapters): a short USB-C (male) to USB-A (female) OTG adapter.
- USB-C devices and phones: the same OTG adapter plus the device's own USB-A to USB-C cable. A plain USB-C to USB-C cable usually does not work.
- One device at a time, no USB hubs.
2. Power: get this right first
The board does not supply 5 V on its USB port. Without its own power the device stays off. A modem without enough current resets in a loop or restarts the gateway; two 5 V sources connected together can damage the board, a computer or a charger.
| Device | Typical current |
|---|---|
| USB Ethernet adapter | 150–350 mA |
| Phone (USB tethering) | 0–500 mA or more (it may try to charge) |
| 4G stick | 300–800 mA, peaks above 1 A |
| LTE modem (SIM7600, EC25 …) | peaks up to 2 A |
A computer's USB port gives 500–900 mA: not enough for a modem or 4G stick. Too little current shows up as modem resets, failed data calls or the gateway restarting with reset reason BROWNOUT (System page).
A. Powered OTG Y-cable (recommended, no soldering)
5 V charger (at least 2.5 A for a modem or stick, 1 A otherwise)
| power input
v
[ Y-cable ]-- USB-C plug --> board's USB port (data + 5 V)
[ ]-- USB-A socket <-- modem / stick / adapter / phone cable
- The cable must pass data to the USB-C plug and power to the USB-A socket. Charge-only splitters do not work.
- The charger powers the device and usually the board too. The COM port can stay connected to a computer for logs.
B. The device's own 5 V supply
- Power the modem board from a 5 V supply able to deliver 2 A peaks.
- Connect its USB D+, D− and GND to the board's USB port; the modem's USB VBUS must see 5 V from the same supply, or it never shows up on USB.
- Always connect the grounds of the supply, the modem and the board.
C. Bridging the board's USB-OTG pad (experts only)
Many boards have a solder jumper labelled USB-OTG that connects the board's 5 V to the USB port. Only bridge it if your board's documentation says so, if the board is powered by a 5 V supply strong enough for board and device together, and if you will never connect that USB port to a computer or charger while it is bridged. Leave the IN-OUT jumper as it is.
Never
- Power an LTE modem from the board's 3.3 V pin.
- Use a USB hub to inject power (hubs are not supported).
- Use long, thin cables for a modem: they drop voltage at 2 A.
3. Wi-Fi while a USB connection is on
The USB transfers must use the chip's internal RAM, the same RAM where the Wi-Fi keeps its receive buffers. So, only while the cellular or Ethernet uplink is set to the USB port, the Wi-Fi starts with 16 receive buffers instead of 24, about 12.8 KB of internal RAM for the USB device.
- Bursts of incoming Wi-Fi traffic fill the buffers sooner; extra frames are dropped and TCP resends them: short speed dips and higher latency peaks.
- It shows most with speed tests or large uploads from devices on the gateway's own access point, several devices sending at once, or a weak signal.
- Ordinary use (Web UI, MQTT, notifications, Tailnet, ping) was unchanged in the measurements.
- The USB uplink itself tops out at about 10 Mbit/s (USB full speed), so it is usually the narrower point.
With the pins, or with both uplinks off, the Wi-Fi keeps 24 buffers exactly as before. The System page and /api/status report it as wifi_rx_lean_for_usb.
4. Setting it up
- In first-boot setup choose Ethernet cable or Mobile network (SIM) and then the USB option; on an installed gateway use Network → Ethernet or Network → Cellular, How … is connected → USB port. Save.
- Restart the gateway.
- Plug the device, powered as above. The card shows the device, the USB network type (RNDIS, CDC-ECM, CDC-NCM) or serial port in use, a mode switch of a stick that started as a CD-ROM, or why it cannot be used.
Only one of the two uplinks can use the USB port. To go back, choose the pins option, save and restart.
5. Devices
| Ethernet over USB | Mobile network over USB | |
|---|---|---|
| Expected | Realtek RTL8152, RTL8153, RTL8156 adapters; CDC-ECM and CDC-NCM adapters and docks | SIMCom SIM7600; Quectel EC25, EG25-G, EC21, EG91, EG95, BG96; modems with a standard CDC-ACM port |
| Likely | Android USB tethering (RNDIS or NCM) | SIMCom A7670, SIM7070/7080; Quectel EC200, EG800; Huawei E3372h and E8372h HiLink, ZTE MF79U and MF833, Alcatel Link Key and other RNDIS/ECM/NCM sticks |
| Not supported | ASIX AX88179/AX88772, Microchip LAN78xx, iPhone tethering | modems with only MBIM or QMI and no AT port |
For a first test: a TP-Link UE300 or another USB-A adapter with an RTL8153 chip, or a USB-C 2.5 Gbit/s adapter with an RTL8156BG chip plus a passive USB-A to USB-C adapter (whether a USB 3 adapter works on the full-speed port is part of the test); a Huawei E3372h-320 stick or a SIMCom SIM7600 USB dongle; a USB-C OTG Y-cable with a power input and a 5 V 3 A charger.
6. Troubleshooting
| What you see | Try |
|---|---|
| No USB device on the USB port | the device has no 5 V, it is on the COM port, or a charge-only cable or adapter is in the way |
| The device appears and disappears | not enough current: stronger supply, shorter cable, or solution B |
| Gateway restarts, reset reason BROWNOUT | the modem draws from the board's supply: power it separately |
| Stick stays in storage mode | switch it once to modem mode on a computer and report its vendor:product |
| Adapter "not supported (vendor-only chip)" | use an RTL8152/RTL8153 or a CDC-ECM/NCM adapter |
| Wi-Fi speed tests through the access point slower | expected while USB is on (section 3) |
Full wiring details, including a bare module wired to GPIO19/20: docs/USB-DEVICES.md.