Repository navigation
Firmware v3.0.25-beta.8 — USB modems, 4G sticks, USB Ethernet and tethering
Pre-releaseFirmware v3.0.25-beta.8 — USB modems, 4G sticks, USB Ethernet and tethering
Beta for testing. The USB connections below have not been tested with real
modems, sticks, adapters or phones yet. Please report your board, cable and
device: the Network page shows the device as vendor:product.
Changes since beta.7
- Clear power warnings. When you choose USB for Ethernet or the mobile
network, first-boot setup and the Network page show how to power the device:
the board does not supply 5 V on its USB port; use a powered OTG Y-cable or
the device's own supply; bridging the USB-OTG pad is for experts only; LTE
modems draw up to 2 A in bursts. A link opens the USB guide. - The Wi-Fi trade-off is explained. While a USB connection is on, the Wi-Fi
keeps 16 receive buffers instead of 24 to leave internal RAM for the device:
bursts of Wi-Fi traffic, such as a speed test from a phone on the gateway's
access point, can be slower or lose more packets. Ordinary use was unchanged
in measurements; with the pins nothing changes. - In first-boot setup a titled step ("How is Ethernet connected?", "How is the
modem connected?") now separates the choice of uplink from the choice of
pins or USB. - New guide in docs/USB-DEVICES.md
and the README, with suggested devices for a first test (an RTL8153 USB
Ethernet adapter, a Huawei E3372h-320 stick or a SIMCom SIM7600 USB dongle,
a powered OTG Y-cable). The website page follows the stable release. - Fewer Wi-Fi drops. Some routers pause their beacons for a few seconds
at regular intervals (for example every 12 hours for a channel scan). The
gateway gave up after 6 s, which caused a short drop, a Tailnet reconnect
and a warning about twice a day, also with 3.0.24. It now waits 15 s, so
such pauses pass without a drop./api/statusshowssta.beacon_timeout_s. - With notifications on Problems, a short Wi-Fi drop is no longer sent by
itself; an uplink that stays down is still reported after the grace period.
All events still sends every drop.
Changes since beta.6
- No internal RAM for USB while it is off. The USB driver's transfer code
now runs from flash and the USB, cellular and Ethernet state is kept in
PSRAM. On a fully configured gateway (MQTT, ntfy, Telegram, Service Gateway,
Tailscale exit node) with the USB connections off, 51.4 KB of internal RAM
stayed free: about 0.6 KB more than 3.0.24 (50.8 KB) and 3.2 KB more than
beta.6 (48.2 KB). - Serial USB modems use a different receive buffer (same size, kept in PSRAM).
- Measured on the same gateway with the USB connections off: ping over LAN and
Tailnet, page loads over LAN and Tailnet and errors were the same as 3.0.24
or slightly better. The 8–10 % slower LAN page loads seen once with beta.6
did not repeat in an alternating comparison with 3.0.24.
Changes since beta.5
- Notification messages (ntfy test sent or failed, saved, connection errors,
restarting and reloading) are shown in the chosen language. - The connection guide no longer blames the gateway for large pings that a
computer's own network path truncates. - Compared with 3.0.24 on a fully configured gateway with the USB connections
off: ping over LAN and Tailnet (median and loss) and page loads over Tailnet
were the same. The USB driver code took about 2.6 KB of internal RAM
even when USB was off (fixed in beta.7).
Changes since beta.4
- More internal RAM for USB devices, only while USB is in use. When the
cellular or Ethernet uplink is set to the USB port, the gateway's Wi-Fi keeps
16 receive buffers instead of 24, which leaves about 12.8 KB more internal RAM
for the USB device. Wi-Fi traffic peaks can be a little slower in that case.
With the pins, or with these uplinks off, the Wi-Fi is configured exactly as
before. - Measured on a fully configured gateway (MQTT, ntfy, Telegram, Service
Gateway, Tailscale exit node): with USB on, 57.8 KB of internal RAM stayed
free (44.3 KB with beta.3), enough for every USB device at full speed; MQTT
stayed connected, ntfy and Telegram delivered test messages, Tailnet stayed
up, LAN ping and page loads were unchanged. - The simple-mode note ("N advanced sections are hidden") is translated.
Changes since beta.3
- Measured on a configured gateway: starting the USB host costs about 3.3 KB of
internal RAM. When little internal RAM is left, a USB device now runs with
one transfer per direction (slower) instead of being refused; it is refused
only if even that would leave less than 40 KB for the rest of the gateway. - The Cellular and Ethernet cards show their states and messages in the chosen
language, and a "Waiting" badge between attempts (for example while no USB
device is plugged in) instead of "Connecting".
Changes since beta.2
- The USB connection now fits gateways that already use many features. Beta.2
required 56–64 KB of free internal RAM, more than a typical configured board
has, so it would not start there. Serial modems no longer use Espressif's
CDC-ACM driver, whose task needed 4 KB of internal RAM; transfers are
smaller. The USB connection starts whenever 40 KB stay free for the rest of
the gateway, and otherwise the card says how much is needed and free. - The API reports the internal RAM the USB connection uses (
usb.internal_ram).
New
- Mobile network (SIM) over USB. The SIM modem can still be wired to the
board's pins, or now plugged into the board's USB port:- USB LTE modems with AT commands (PPP, with the same SIM PIN, APN and
registration handling as a wired modem); - 4G sticks with their own web page (RNDIS, CDC-ECM or CDC-NCM), which
connect by themselves; - sticks that start as a CD-ROM are switched to modem mode automatically.
- USB LTE modems with AT commands (PPP, with the same SIM PIN, APN and
- Ethernet over USB. Besides the W5500 module on the pins: USB Ethernet
adapters (Realtek RTL8152/RTL8153/RTL8156 and other CDC-ECM/CDC-NCM devices)
and Android USB tethering. - You choose pins or USB on the Network page (How the modem is connected,
How Ethernet is connected) and in first-boot setup. Devices are recognised
by their USB interface classes, not a fixed list; a list of expected and
unsupported devices is on the page. - Every Web UI string is translated into Italian, German, French, Spanish and
Chinese.
Connecting and powering a USB device
Read Connecting USB devices before plugging anything in. In short:
- Use the board's USB port for the device (not the COM port). After
the restart that port is a USB host; flash, logs and power go through COM. - Use a USB-C to USB-A OTG adapter; plain USB-C to USB-C cables usually do
not work. One device at a time, no USB hubs. - The board does not supply 5 V on its USB port. Power the device with one of:
- a powered OTG Y-cable with a 5 V charger (at least 2.5 A for a modem):
the simplest way; - the device's own 5 V supply (modem boards), with grounds connected and
5 V on the device's USB VBUS; - the board's USB-OTG solder pad bridged, only with a strong 5 V supply
and never with the USB port connected to a computer.
- a powered OTG Y-cable with a 5 V charger (at least 2.5 A for a modem):
- LTE modems draw up to 2 A in bursts: a computer's USB port is not enough
(symptoms: modem resets, reset reason BROWNOUT). - Speed over USB is about 10 Mbit/s at most (USB full speed).
Unchanged
With the pins, or with these uplinks off, the gateway behaves as in 3.0.24.
Nothing USB-related runs while off; a modem on pins and a W5500 are saved in
the 3.0.24 format, so going back to 3.0.24 keeps them. USB settings are not
read by older firmware (that uplink stays off there).
Install
Upload firmware.bin from the device Web UI (System → Update) on an
ESP32-S3 already running 3.x, or receive it through the beta update channel.
Check its SHA-256 against SHA256SUMS.txt. For a fresh installation, use
the stable release and its browser installer, then update.