Repository navigation
Releases
Firmware v3.0.29 — USB SIM sticks on the home network, DNS over the SIM
Firmware v3.0.29 — USB SIM sticks on the home network, DNS over the SIM
Fixed
- A USB SIM stick that uses the same addresses as the home network
(for example 192.168.1.x on both sides, common with router-style sticks
whose range cannot be changed) no longer cuts the gateway off from the home
devices. Home addresses go through Wi-Fi or Ethernet; only the stick's own
addresses, and its gateway while it carries the Internet traffic, go to the
stick. Diagnostics → Route lookup shows the reason. - With mobile data as the main Internet uplink, name lookups use it too.
Before, the gateway could keep asking the home router's DNS through the
stick: names did not resolve and Tailscale kept disconnecting and
reconnecting every few minutes. The home router's DNS comes back when
Wi-Fi or Ethernet carries the traffic again; a DNS server you chose outside
the home network (for example 1.1.1.1) is kept. - System → Updates links the RecoveryGateway repository and shows the
release-notes link again for its releases.
Website
- After a browser install, the install page shows the next step and an
optional tip button. - On phones the top bar stays visible while scrolling, and the open menu no
longer covers the page.
Everything of 3.0.28 is included.
Install: web installer, Easy Install package, or OTA (System → Updates).
Verify the files against SHA256SUMS.txt.
Firmware v3.0.28 — RecoveryGateway
Firmware v3.0.28 — new name: RecoveryGateway
Changed
- ESP32 Tailnet Gateway is now RecoveryGateway — Mattboxx Edition. Same
firmware, same settings: nothing to reconfigure. The web interface, Home
Assistant device, notifications, logo and release files carry the new name.
A new device's first-boot Wi-Fi is nowRecoveryGateway-Setup-XXXX. - New addresses: this repository is now
Mattboxx/RecoveryGatewayand the
website is https://mattboxx.github.io/RecoveryGateway/. Old website links
open the same page at the new address. - The updater looks for releases here first. Gateways on 3.0.27 or older
still find this release with Check for updates: the old repository name
keeps a copy of 3.0.28 for them, and later updates come from here.
Website
- A "Which board?" button leads to the tested ESP32-S3 boards.
Everything of 3.0.27 is included.
Install: web installer, Easy Install package, or OTA (System → Updates).
Verify the files against SHA256SUMS.txt.
Firmware v3.0.27 — one more case that could block the tunnel is fixed
Firmware v3.0.27 — one more case that could block the tunnel is fixed
Fixed
- A device whose key expiry carries a time zone offset (for example
"+01:00", possible with some control servers) or a year after 2099 made the
gateway refuse the whole device list and block the tunnel, like the 64-bit
ID issue fixed in 3.0.26. These times are now read correctly; malformed
ones are still refused. The gateway's own key expiry shown on the Tailscale
page also honours the offset. - The user ID of the registration is read exactly (shown in the log).
Everything of 3.0.26 is included: the fix for tailnets with recently added
devices, Headscale with a private CA, first connection without DNS, ACL
"cap:" rules, two relays to other regions, up to 5 devices per LAN → Tailnet
rule and configuration profiles for every first-boot goal.
Install: web installer, Easy Install package, or OTA (System → Updates).
Verify the files against SHA256SUMS.txt.
Firmware v3.0.26 — fix for tunnels blocked by new devices, Headscale with a private CA, profiles for every goal
Firmware v3.0.26 — fix for tunnels blocked by new devices, Headscale with a private CA, profiles for every goal
Fixed
- Tunnel blocked in tailnets with recently added devices. The log showed
"Authorization/peer update needs a full refresh; tunnel data blocked
(stage=policy reason=peer-id ...)". Tailscale device IDs are 64-bit numbers;
devices added recently have IDs larger than the gateway's JSON reader could
hold exactly, so the gateway refused the whole device list and blocked the
tunnel. IDs are now read exactly, also in device updates and removals.
Added
- Headscale with a private CA or a self-signed certificate: a Login
server certificate field on the Tailscale page, trusted only for the login
server and its relays, from the next restart (the server name is still
checked; updates, MQTT and notifications keep public certificates only). - First connection without working DNS: the Tailscale control server is
found through a Tailscale relay at a built-in address, as the official
client does. - ACL rules with "cap:" sources admit the devices that hold that
capability. - Two relays to other regions at once for devices without a direct path.
- LAN → Tailnet: up to 5 allowed devices per rule, and a guide to share
one of your services with another network:docs/SERVICE-GATEWAY.md. - Configuration profiles for every first-boot goal (System → General):
two new ones (LAN → Tailnet services, Home Assistant), in the setup's
order, the goals chosen at first boot marked "chosen at setup", guided
steps for everything added since 3.0. Profiles never open access, change
routes or send data by themselves. - Date and time in the pre-crash log.
Still open: IPv6 inside the tailnet (use a device's 100.x address) and very
large tailnets above about 250-500 devices.
Install: web installer, Easy Install package, or OTA (System → Updates).
Verify the files against SHA256SUMS.txt.
Firmware v3.0.26-beta.2 — fix for tunnels blocked by new devices, Headscale with a private CA
Firmware v3.0.26-beta.2 — fix for tunnels blocked by new devices, Headscale with a private CA, first connection without DNS
Beta for testing. It builds on 3.0.25 (the current stable release) and
extends what the gateway can reach in a tailnet. New behaviour that could
change your setup is off by default or only used when you set it.
Tailnet
- Fixed: tunnel blocked in tailnets with recently added devices. The log
showed "Authorization/peer update needs a full refresh; tunnel data blocked
(stage=policy reason=peer-id ...)". Tailscale device IDs are 64-bit numbers;
devices added recently have IDs larger than the gateway's JSON reader could
hold exactly, so the gateway refused the whole device list and blocked the
tunnel. IDs are now read exactly, also in device updates and removals.
This affects 3.0.25 and earlier. - Headscale with a private CA or a self-signed certificate. The Tailscale
page has a Login server certificate field: paste the CA (or the server
certificate) as PEM text. It is trusted only for the login server and its
relays, from the next restart and only while a login server is set. The
server name and validity are still checked; firmware updates, MQTT and
notifications keep using public certificates only. Saving or removing it
needs the admin password. - First connection without working DNS. When the Tailscale control
server's name cannot be resolved and no working address is known yet, the
gateway asks a Tailscale relay at a built-in address for it over a verified
TLS connection, as the official client does. The address is kept in memory
only, and the server is still verified by its certificate and key. - ACL rules with "cap:" sources work. Such a rule now admits the devices
that hold that capability (from their tailnet addresses), instead of nobody. - Two relays to other regions at once. Devices homed on two different
relay regions, both without a direct path, are reachable at the same time
(one extra relay before). Each extra relay opens only when needed and closes
after a minute without traffic.
LAN → Tailnet
- Up to 5 allowed devices per rule ("192.168.1.20, 192.168.1.30"), next to
one device or a whole subnet. - New guide: share one service with another network. A gateway placed in
a friend's home, joined to your tailnet with a tagged key, lets a few of
their devices use one of your services (one address and port) and nothing
else: your tailnet ACL limits what the gateway reaches, the rule limits who
may use it. Seedocs/SERVICE-GATEWAY.md.
Other
- The pre-crash log shows date and time for the lines of the crashed run
when that run had the clock; the crash header no longer shows the time twice. - The optional UDP helpers of the VPN library call the network stack from its
own thread, and a full network queue can no longer use up the zero-copy send
slots.
Still open (docs/TAILNET-ACCESS-AUDIT.md): IPv6 inside the tailnet (use a
device's 100.x address) and very large tailnets above about 250-500 devices.
Install: web installer or OTA (System → Updates with "Include beta /
pre-release updates" on). Verify firmware.bin against SHA256SUMS.txt.
Firmware v3.0.25 — Tailscale access fixes, clearer status, LAN → Tailnet redesign
Firmware v3.0.25
Fixed: Tailscale and Headscale access
- Single-use auth keys no longer take the gateway offline. The default key of the Tailscale admin console is single-use; the gateway presented it again at every reconnect and restart, the control server refused it ("invalid key") and the device stayed offline. The key is now used only to log in, as the official client does.
- No 16-peer limit. A tailnet with more than 16 other devices (stale ones count) was refused as a whole and every tunnel was blocked. The tailnet size is no longer limited; 20 tunnels are in use at a time and go to the peers that need them.
- Other cases where the tailnet could not be used: a gateway alone in its tailnet, ACL rules with node capabilities, large ACL policies, peers with more than one advertised subnet, networks that block port 80 (TLS on 443 is used) or NTP (time from the control server), DNS failures, auth keys pasted with spaces, an expired node key, peers homed on another relay region without a direct path, peer key renewal, and a Headscale server that changed its key.
- WireGuard handshakes and keepalives are sent from the network thread, and a direct path that stopped working is given up after 30 s.
- Large DNS answers no longer reach access-point clients cut (DNS over TCP and proper truncation).
- Far fewer flash writes for the peer cache.
Added
- Clear Tailscale status: why the gateway is not connected (key refused or needed, waiting for approval, key expired), node key expiry with a warning 14 days ahead and renewal with a new auth key, Tailnet Lock with the signing command, messages from the control server, peers and tunnels in use, and why the control server refused a connection.
- Leave tailnet button: logs out at the control server (as
tailscale logout), deletes the auth key and identity, turns Tailscale off. - Logs with date and time (live view and microSD files).
- USB uplinks (experimental, not yet tested with real devices): USB LTE modems and 4G sticks with a SIM, USB Ethernet adapters and phone tethering. Read the connection and power guide in the README or on the website first. Off by default.
- Monthly mobile data limit, traffic per access-point device, and administration limited to the tailnet and the access point (all off by default).
Changed
- LAN → Tailnet tab redesigned: each rule has a simple "Stays open" choice (no time limit, 15 minutes … 7 days) applied with Save; clearer field names; one LAN device can be entered as a plain address.
- Web sessions are bound to the address that logged in; the SNMP community is write-only.
- The Max peers setting is gone: it no longer limited anything.
Update from System → Firmware. Keep a configuration backup before upgrading. Full list: CHANGELOG.
Firmware v3.0.25-beta.24 — Tailnet access fixes, simpler LAN → Tailnet tab
Firmware v3.0.25-beta.24 — Tailnet access fixes, simpler LAN → Tailnet tab
Beta for testing. It contains the Tailnet fixes found after a user's
report on 3.0.24 (official Tailscale, 18 devices, "invalid key"), a review of
the whole Tailnet path for other cases where access could fail, and a
redesigned LAN → Tailnet tab. USB modems and adapters (since beta.5) are still
untested with real devices; please report your board and device. New
behaviour that could change your setup is off by default.
Tailnet: cases where the gateway could not be used
- Single-use auth keys no longer take the gateway offline. The default key
in the Tailscale admin console is single-use; the gateway sent it again at
every reconnect and restart, the control server refused it, and the device
stayed offline with "invalid key". The key is now used only to log in, as the
official client does. A refused key is retried once without it; a device
deleted in the console stops with "enter a new auth key". - No 16-peer limit. A tailnet with more than 16 other devices (stale ones
count) was refused as a whole and every tunnel was blocked. Maps, policy and
peer table are sized by the tailnet (host tests with 300 and 2000 peers). 20
tunnel slots are in use at a time; when they are full, a peer that needs one
takes the slot of an offline or idle peer, and a peer that reaches out gets
one at once. - A gateway alone in its tailnet (or the first device) works: the first
map without peers was treated as incomplete and blocked the tunnel. - ACL rules with "cap:" sources no longer block all traffic.
- No limit on ACL rules (was 128 expanded rules); every advertised subnet
of a peer is reachable (was its own address plus one route). - Networks that block port 80 use TLS on port 443, as the official client.
- Networks that block NTP: the clock is taken from the control server.
- DNS failures: the last working address of the control server is used
(also for Headscale and HTTPS login servers), and relay nodes are reached by
the address in the DERP map. - Peers homed on another relay region are reachable from the gateway even
without a direct path: when the home relay reports a peer missing, the
gateway opens one more relay connection to that peer's region (closed after
60 s idle), as the official client does. - Expired node key: shown with a warning 14 days ahead; entering a valid
auth key renews it for the same device, without a reset. The expired state
no longer loops. - Peer key renewal applies at once, without a full refresh.
- Headscale: a server that got a new key is picked up without restarting
the gateway. - Auth keys pasted with spaces or line breaks are accepted; a registered
gateway starts without a saved auth key.
Easier to understand
- The Tailscale page says why the gateway is not connected (key refused or
needed, waiting for approval, key expired), shows Tailnet Lock with the
command to sign this gateway, messages from the control server, peers and
tunnels in use, and why the control server refused a connection (client
version, wrong URL or proxy, access refused, rate limit, server error). - LAN → Tailnet tab redesigned. Three steps explain what a rule does. Each
rule shows on one line whether it has a time limit and when it closes, with
one choice: "Stays open: No time limit, 15 minutes, 1 hour, 8 hours, 1 day,
7 days", applied with Save. Before, the timer lived in a separate section,
and after it had been used once, every new or edited rule silently stopped
forwarding until confirmed there. A rule closed by its time limit now says
so. One LAN device can be entered as a plain address.
Other
- Far fewer flash writes: the peer cache was rewritten (about 7.7 KB) for every
peer at every reconnect; now only when a peer changes. - The control and relay connections accept the protocol upgrade only on a real
"101" status.
Open limitations are listed in docs/TAILNET-ACCESS-AUDIT.md (very large
tailnets above about 250-500 devices, IPv6 inside the tailnet, private-CA
certificates for HTTPS login servers).
Install: web installer or OTA (System → Updates with "Include beta /
pre-release updates" on). Verify firmware.bin against SHA256SUMS.txt.
Firmware v3.0.25-beta.15 — cleaner boot and log, safer web access, DNS fixes, mobile data limit
Firmware v3.0.25-beta.15 — cleaner boot and log, safer web access, DNS fixes, mobile data limit
Beta for testing. USB modems, sticks, adapters and phones are still not
tested with real devices; please report your board and device (the Network
page shows it as vendor:product). Everything below is off by default unless
it says otherwise.
Changes since beta.13
- No microSD probe at boot while the SD recorder is off. Boards without a
card logged three SD errors on every boot. The card is now looked for only
when the recorder is on, the first time its status is shown, or when you
enable it (a card inserted later is still found). - MQTT waits for a network address before its first connection attempt,
which always failed at boot with "Host is unreachable". An address on the
LAN side (for a broker on your local network) or on the Internet uplink
(also mobile) is enough. - Refused web connections are closed silently. With administration
limited to the tailnet and the access point, every connection to the web
page from the LAN logged an error ("session creation failed"), so a device
retrying filled the log. It is now closed at once, without reading the
request and without a log line; System reports the count as
admin_refused.
The first two were found in the serial log of the maintainer's gateway while
comparing 3.0.24 with beta.13 (present in both): same speed (page, status,
tailnet and forwarding pings within noise, no packet loss), same free memory,
no crash or restart. The third came from testing the new administration
scope on the same gateway.
Changes since beta.8 (summary of beta.13)
Fixed
- Large DNS answers no longer reach devices cut. The gateway's DNS relay
used to pass answers above 1 KB on cut and cache them (present since its
first version). It now asks resolvers for at most 1 KB, turns a longer
answer into a proper "truncated" reply, never caches truncated answers, and
also answers DNS over TCP (answers up to 16 KB), asking the resolver over
UDP with room for 4 KB first. Note: many home routers answer DNS with at most 512 bytes and refuse
TCP; with such a router, large answers (long TXT records, some services)
cannot be resolved by any device, with or without the gateway. Setting a
resolver that supports TCP in the DNS relay settings solves it. - USB network sessions: sending a frame while the USB device was
unplugged could write into memory already freed. Fixed. - PPP over a USB modem no longer blocks the gateway's network core while
the modem is slow: frames are queued instead of waited for.
Security
- Web sessions are bound to the device that logged in. The web page uses
plain HTTP; a session cookie copied off the local network or the access
point no longer works from another device. Changing network asks for the
password again. - Administration can be limited to the tailnet and the access point
(System → Access, off by default). While the gateway is not connected to the
tailnet, the local network keeps access, so you cannot lock yourself out. - The SNMP community is no longer shown by the web page or API (an empty
field keeps the saved one), and the card warns while it is still "public". - A security event is recorded when the plain-TCP remote console listens on
the local network or the access point.
Added
- Monthly mobile data limit (Network → Cellular uplink): counts mobile
data, warns at a chosen percentage and at the limit, and can stop using
mobile data until the next month. The month can start on any day 1–28.
Nothing is counted or written while it is off. - Traffic per access-point device (Network → Clients): what each device
sent and received through the gateway. - Events when mobile data starts or stops carrying the Internet traffic
(a warning in failover mode, where it means Wi-Fi and Ethernet are down). - Signal and operator for Huawei HiLink 4G sticks in USB network mode
(experimental, not tested with a real stick). - DNS diagnostics show queries over TCP and oversized answers.
Changed
- Health & resources moved to Diagnostics → Hardware.
- Telegram and ntfy remote commands are laid out the same way, with the
command reference at the end of each card; command options look inactive
while commands are off. - The settings search finds the new functions, also by synonyms and in every
language. - The DNS cache keeps two entries per slot, so busy names evict each other
less.
Tested
- Offline: the full validation campaign (host tests of the actual firmware
code, browser tests of the web page, build and image provenance). - On the maintainer's ESP32-S3 over Tailscale: install with saved settings
unchanged, the new settings and API fields, the access limit (the local
address refused while the tailnet address works), DNS answers over UDP and
TCP (TCP through a resolver that supports it), the web page answering for
3 minutes. Settings changed for the tests were restored. - Not tested: real USB modems, sticks, adapters and phones; HiLink signal.
Install
Use System → Updates with "Include beta / pre-release updates", or
System → Firmware with firmware.bin below. The stable release stays
v3.0.24.
Firmware v3.0.25-beta.13 — safer web access, DNS fixes, mobile data limit
Firmware v3.0.25-beta.13 — safer web access, DNS fixes, mobile data limit
Beta for testing. USB modems, sticks, adapters and phones are still not
tested with real devices; please report your board and device (the Network
page shows it as vendor:product). Everything below is off by default unless
it says otherwise.
Changes since beta.8
Fixed
- Large DNS answers no longer reach devices cut. The gateway's DNS relay
used to pass answers above 1 KB on cut and cache them (present since its
first version). It now asks resolvers for at most 1 KB, turns a longer
answer into a proper "truncated" reply, never caches truncated answers, and
also answers DNS over TCP (answers up to 16 KB), asking the resolver over
UDP with room for 4 KB first. Note: many home routers answer DNS with at most 512 bytes and refuse
TCP; with such a router, large answers (long TXT records, some services)
cannot be resolved by any device, with or without the gateway. Setting a
resolver that supports TCP in the DNS relay settings solves it. - USB network sessions: sending a frame while the USB device was
unplugged could write into memory already freed. Fixed. - PPP over a USB modem no longer blocks the gateway's network core while
the modem is slow: frames are queued instead of waited for.
Security
- Web sessions are bound to the device that logged in. The web page uses
plain HTTP; a session cookie copied off the local network or the access
point no longer works from another device. Changing network asks for the
password again. - Administration can be limited to the tailnet and the access point
(System → Access, off by default). While the gateway is not connected to the
tailnet, the local network keeps access, so you cannot lock yourself out. - The SNMP community is no longer shown by the web page or API (an empty
field keeps the saved one), and the card warns while it is still "public". - A security event is recorded when the plain-TCP remote console listens on
the local network or the access point.
Added
- Monthly mobile data limit (Network → Cellular uplink): counts mobile
data, warns at a chosen percentage and at the limit, and can stop using
mobile data until the next month. The month can start on any day 1–28.
Nothing is counted or written while it is off. - Traffic per access-point device (Network → Clients): what each device
sent and received through the gateway. - Events when mobile data starts or stops carrying the Internet traffic
(a warning in failover mode, where it means Wi-Fi and Ethernet are down). - Signal and operator for Huawei HiLink 4G sticks in USB network mode
(experimental, not tested with a real stick). - DNS diagnostics show queries over TCP and oversized answers.
Changed
- Health & resources moved to Diagnostics → Hardware.
- Telegram and ntfy remote commands are laid out the same way, with the
command reference at the end of each card; command options look inactive
while commands are off. - The settings search finds the new functions, also by synonyms and in every
language. - The DNS cache keeps two entries per slot, so busy names evict each other
less.
Tested
- Offline: the full validation campaign (host tests of the actual firmware
code, browser tests of the web page, build and image provenance). - On the maintainer's ESP32-S3 over Tailscale: install with saved settings
unchanged, the new settings and API fields, the access limit (the local
address refused while the tailnet address works), DNS answers over UDP and
TCP (TCP through a resolver that supports it), the web page answering for
3 minutes. Settings changed for the tests were restored. - Not tested: real USB modems, sticks, adapters and phones; HiLink signal.
Install
Use System → Updates with "Include beta / pre-release updates", or
System → Firmware with firmware.bin below. The stable release stays
v3.0.24.
Firmware v3.0.25-beta.8 — USB modems, 4G sticks, USB Ethernet and tethering
Firmware 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.