RecoveryGateway

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 isUse it for
COM, UART, CH343, CP2102a USB-serial chipflashing, logs, the browser installer, powering the board
USB, OTG, ESP32-S3the 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.

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.

DeviceTypical current
USB Ethernet adapter150–350 mA
Phone (USB tethering)0–500 mA or more (it may try to charge)
4G stick300–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

B. The device's own 5 V supply

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

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.

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

  1. 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.
  2. Restart the gateway.
  3. 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 USBMobile network over USB
ExpectedRealtek RTL8152, RTL8153, RTL8156 adapters; CDC-ECM and CDC-NCM adapters and docksSIMCom SIM7600; Quectel EC25, EG25-G, EC21, EG91, EG95, BG96; modems with a standard CDC-ACM port
LikelyAndroid 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 supportedASIX AX88179/AX88772, Microchip LAN78xx, iPhone tetheringmodems 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 seeTry
No USB device on the USB portthe 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 disappearsnot enough current: stronger supply, shorter cable, or solution B
Gateway restarts, reset reason BROWNOUTthe modem draws from the board's supply: power it separately
Stick stays in storage modeswitch 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 slowerexpected while USB is on (section 3)

Full wiring details, including a bare module wired to GPIO19/20: docs/USB-DEVICES.md.

Support Mattboxx Edition

Enjoying the gateway? Choose where to leave a tip or support its development.

GitHub SponsorsSupport via GitHub Ko-fiLeave a tip on Ko-fi

Entirely optional. The firmware and all features stay free. Payments are handled on your chosen provider's website.