Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Tailscale to use Wake-on-LAN or the backup uplinks.
| Use case | What the ESP32 does |
| --- | --- |
| **Wake and check a NAS or PC — no VPN needed** | Send Wake-on-LAN and verify that the device answers, from a Telegram bot or an ntfy topic. Works with or without Tailscale. [Setup and command reference](https://mattboxx.github.io/RecoveryGateway/remote-recovery/#commands). |
| **Keep IoT devices online** | Use a mobile SIM or wired Ethernet as the main or the backup uplink, with automatic failover and an optional monthly data limit. **SIM:** a 4G/LTE modem wired to the board's pins (UART, e.g. SIM7600 or A7670 modules), or plugged into its USB port (USB LTE modems and 4G sticks, beta). **Ethernet:** a W5500 module on the pins (SPI), or a USB Ethernet adapter or phone tethering on the USB port (beta). [Hardware](https://mattboxx.github.io/RecoveryGateway/hardware/) · [USB devices](docs/USB-DEVICES.md). |
| **Keep IoT devices online** | Use a mobile SIM or wired Ethernet as the main or the backup uplink, with automatic failover and an optional monthly data limit. **SIM:** a 4G/LTE modem wired to the board's pins (UART, e.g. SIM7600 or A7670 modules), or plugged into its USB port (4G USB sticks, tested with a TCL LinkKey IK41, and USB LTE modems). **Ethernet:** a W5500 module on the pins (SPI), or a USB Ethernet adapter or phone tethering on the USB port (beta). [Hardware](https://mattboxx.github.io/RecoveryGateway/hardware/) · [USB devices](docs/USB-DEVICES.md). |
| **Connect devices that cannot run Tailscale** | Forward one TCP or UDP service from the local LAN to a Tailnet peer. Restrict the source by IP/CIDR. |
| **Reach a remote LAN** | Advertise approved subnets to Tailnet clients. Configure the gateway's own Wi-Fi for IoT devices. |
| **Monitor and automate** | Track events and resource trends locally. Optionally use MQTT and Home Assistant, ntfy, Telegram, email or SNMP. |
Expand Down Expand Up @@ -162,14 +162,23 @@ to you. As an Amazon Associate I earn from qualifying purchases.* Any board in t

Details and community reports: [Hardware](docs/HARDWARE.md).

### USB modems, 4G sticks and Ethernet adapters (experimental, from 3.0.25)
### USB 4G sticks, modems and Ethernet adapters (from 3.0.25)

Besides a W5500 module or a modem wired to the pins, the gateway can use one
USB device on the board's **USB** port (not the COM port): a USB LTE modem or
4G stick with a SIM, a USB Ethernet adapter (Realtek RTL8152/8153/8156,
CDC-ECM/NCM) or Android USB tethering. Choose *USB* in first-boot setup or on
the Network page, save, restart, then plug the device. Not yet tested with real
devices.
the Network page, save, restart, then plug the device.

- **Tested:** a [TCL LinkKey IK41 4G USB stick](https://link.amazon/B08rO5Fv3) with a SIM, as the main
Internet uplink: Tailscale stays connected over mobile data, name lookups
use the SIM, and home devices stay reachable even though the stick uses
the same 192.168.1.x range as the home router (from 3.0.29).
- **Not yet tested with real devices:** USB modems in serial (AT/PPP) mode,
USB Ethernet adapters and phone tethering. Reports are welcome.

*Affiliate link: buying through it supports the project at no extra cost to
you. As an Amazon Associate I earn from qualifying purchases.*

- **The board does not supply 5 V on its USB port.** Use a powered USB-C OTG
Y-cable with a 5 V charger (at least 2.5 A for a modem or stick), or the
Expand Down
6 changes: 4 additions & 2 deletions docs/CELLULAR.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Cellular uplink (GSM/LTE with a SIM) — experimental
# Cellular uplink (GSM/LTE with a SIM)

Firmware 3.0 can use an external cellular modem as its Internet uplink: as the
main uplink, or only while WiFi and Ethernet are down (failover). The modem
Expand Down Expand Up @@ -113,7 +113,9 @@ modem's own default context (or the stick's settings) is used.

### Compatibility

Nothing below has been tested with real hardware yet. "Expected" means the
Tested with real hardware: a **TCL LinkKey IK41 4G USB stick** (`1bbb:0195`, USB
network mode) as the main Internet uplink. Nothing else below has been tested
with real hardware yet. "Expected" means the
device exposes interfaces this firmware drives; firmware variants of the same
model can differ.

Expand Down
2 changes: 1 addition & 1 deletion docs/HARDWARE.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ to you. As an Amazon Associate I earn from qualifying purchases.* Any supported
| Flash layout | 3.x: two 3.5 MB update slots, settings, core dump and a 832 KB storage area (`partitions.csv`). 2.x gateways move with the [migration guide](MIGRATION-3.0.md); settings are kept. |
| Radio | One 2.4 GHz radio shared by uplink and access point. |
| Ethernet | Optional W5500 SPI module, driver in the standard image, off until configured; not validated on real hardware: [ETHERNET.md](ETHERNET.md). |
| Cellular | Optional UART modem with a SIM, off until configured; experimental, not tested with a real modem: [CELLULAR.md](CELLULAR.md). |
| Cellular | Optional 4G USB stick or modem with a SIM, off until configured. Tested: TCL LinkKey IK41 4G USB stick; UART modems not yet tested: [CELLULAR.md](CELLULAR.md). |
| microSD | Optional log recorder on GPIO38/39/40 (SDMMC 1-bit); those pins are reserved. |
| Power | Independent, reliable supply; no power-consumption measurement is claimed. |

Expand Down
6 changes: 4 additions & 2 deletions docs/USB-DEVICES.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,10 @@ explains which port to use, how to wire it and, above all, **how to power the
device**. Which devices are expected to work is listed in
[CELLULAR.md](CELLULAR.md#compatibility) and [ETHERNET.md](ETHERNET.md#usb-adapters-and-tethering).

> Experimental: these connections have not been tested yet with real devices.
> Report your board, cable and device (the card shows its `vendor:product`).
> Tested: a TCL LinkKey IK41 4G USB stick (USB ID `1bbb:0195`, network mode) as the
> main Internet uplink, with Tailscale over mobile data. USB modems in serial
> mode, USB Ethernet adapters and tethering are not yet tested with real
> devices: report your board, cable and device (the card shows its `vendor:product`).

## 1. Which port

Expand Down
2 changes: 1 addition & 1 deletion website/pages/00-home.html
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ <h1>RecoveryGateway</h1>
<h2 id="use-cases">What you can do</h2>
<div class="grid grid-3">
<article class="card"><h3>Wake a NAS or PC — no VPN needed</h3><p>Wake a device and verify that it responds, from a Telegram bot or an ntfy topic. Tailscale is optional: the ESP32 can be just a Wake-on-LAN node.</p><a href="{{root}}remote-recovery/#without-tailnet">Set up Wake-on-LAN</a></article>
<article class="card"><h3>Keep IoT devices online</h3><p>Use a mobile SIM or wired Ethernet as the main or backup uplink, with automatic failover and an optional monthly data limit. Connect a 4G/LTE modem or a W5500 Ethernet module to the board's pins, or plug a USB modem, 4G stick or USB Ethernet adapter into its USB port (USB in beta).</p><a href="{{root}}hardware/">Hardware</a> · <a href="{{root}}usb-devices/">USB devices</a></article>
<article class="card"><h3>Keep IoT devices online</h3><p>Use a mobile SIM or wired Ethernet as the main or backup uplink, with automatic failover and an optional monthly data limit. Connect a 4G/LTE modem or a W5500 Ethernet module to the board's pins, or plug a 4G USB stick (tested with a TCL LinkKey IK41), a USB modem or a USB Ethernet adapter into its USB port.</p><a href="{{root}}hardware/">Hardware</a> · <a href="{{root}}usb-devices/">USB devices</a></article>
<article class="card"><h3>Reach a specific service</h3><p>Give a device on your LAN access to a selected TCP or UDP service on a Tailnet peer. Restrict access by source IP or subnet.</p><a href="{{root}}service-gateway/">Service Gateway</a></article>
<article class="card"><h3>Reach a home or IoT network</h3><p>Advertise approved subnets to Tailnet clients, or give local devices a dedicated Wi-Fi network through the ESP32.</p><a href="{{root}}network-modes/">Network modes</a></article>
<article class="card"><h3>Monitor and automate</h3><p>Review local event history and resource trends. Connect Home Assistant via MQTT, send alerts via Telegram, email or ntfy, or monitor over SNMP.</p><a href="{{root}}automation/">Automation</a> · <a href="{{root}}screenshots/#history">Event history</a></article>
Expand Down
2 changes: 1 addition & 1 deletion website/pages/01-features.html
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ <h2 id="new-3">Capabilities and defaults</h2>
<tr><td>Tailnet names for local devices</td><td>Devices without Tailscale on the gateway's Wi-Fi or your home LAN should reach peers by name (<code>nas</code>, <code>nas.your-tailnet.ts.net</code>). A name is not access: rules and policies still apply.</td><td>Off</td></tr>
<tr><td>Telegram and email notifications</td><td>You want problems or every event on your phone or in your inbox. Email over TLS (465) or STARTTLS (587) with verified certificates; passwords are never sent without TLS.</td><td>Off</td></tr>
<tr><td>Throughput test</td><td>You need to know whether the link is fast enough: the gateway downloads from a URL (a NAS through the tailnet, or the internet), or the browser downloads from the gateway.</td><td>On request</td></tr>
<tr><td>Cellular uplink (experimental)</td><td>A site has no usable Wi-Fi: a UART modem with a SIM as primary or failover uplink. Not yet tested with a real modem.</td><td>Off</td></tr>
<tr><td>Cellular uplink</td><td>A site has no usable Wi-Fi: a 4G USB stick or a modem with a SIM as primary or failover uplink, with an optional monthly data limit. Tested with a TCL LinkKey IK41 USB stick; UART modems not yet tested.</td><td>Off</td></tr>
<tr><td>One image, every language</td><td>English, Italiano, Español, 简体中文, Français and Deutsch in the same firmware, plus the W5500 Ethernet driver (experimental, off until configured).</td><td>—</td></tr>
</tbody>
</table>
Expand Down
2 changes: 1 addition & 1 deletion website/pages/06-getting-started.html
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ <h2 id="before">Before you start</h2>
<ul>
<li>An <strong>ESP32-S3 N8R8 or N16R8</strong>: 8 MB octal PSRAM and at least 8 MB flash. Check <a href="{{root}}hardware/">supported hardware</a>, or get the tested <strong>ESP32-S3-DevKitC-1 N16R8</strong> on Amazon: <a href="https://link.amazon/B0hzOWAlV" rel="sponsored nofollow noopener" target="_blank">link 1</a> · <a href="https://link.amazon/B0891h232" rel="sponsored nofollow noopener" target="_blank">link 2</a> <small>(affiliate links; As an Amazon Associate I earn from qualifying purchases.)</small>.</li>
<li>A USB <strong>data</strong> cable and a computer. The browser installer needs desktop Chrome or Edge; <a href="{{root}}easy-install/">Easy Install</a> supports Windows, macOS and Linux.</li>
<li>A 2.4 GHz Wi-Fi network for the usual Wi-Fi setup. Ethernet and cellular need external hardware and remain experimental.</li>
<li>A 2.4 GHz Wi-Fi network for the usual Wi-Fi setup. Ethernet and cellular need external hardware; a 4G USB stick is tested, Ethernet remains experimental.</li>
<li>Tailscale or Headscale for Tailnet roles. Local administration and <a href="{{root}}remote-recovery/#without-tailnet">Wake-on-LAN over Telegram or ntfy</a> can be used without a Tailnet.</li>
</ul>

Expand Down
6 changes: 4 additions & 2 deletions website/pages/07-hardware.html
Original file line number Diff line number Diff line change
Expand Up @@ -51,9 +51,11 @@ <h2 id="requirements">Requirements</h2>
</table>
<p>Community reports for other ESP32-S3 boards are collected in <a href="{{repo}}/blob/Main/docs/HARDWARE.md">docs/HARDWARE.md</a>; please add yours with the <em>Hardware report</em> issue form.</p>

<h2>W5500 Ethernet and cellular (experimental)</h2>
<h2>Cellular (SIM) and W5500 Ethernet</h2>
<p><strong>Tested 4G USB stick:</strong> a TCL LinkKey IK41 with a SIM, as the main Internet uplink with Tailscale connected over mobile data. <a class="btn" href="https://link.amazon/B08rO5Fv3" rel="sponsored nofollow noopener" target="_blank">TCL LinkKey IK41 4G USB stick on Amazon</a></p>
<p class="note"><small>Affiliate link: buying through it supports the project at no extra cost to you. As an Amazon Associate I earn from qualifying purchases.</small></p>
<p class="note">From 3.0.25 a USB LTE modem, a 4G stick, a USB Ethernet adapter or phone tethering can also use the board's USB port. The board does not power that port: read <a href="{{root}}usb-devices/">USB modems, sticks and Ethernet adapters</a> before plugging anything in.</p>
<p>The standard firmware image includes a driver for an explicitly wired W5500 SPI module: off until configured, explicit pins, DHCP or static IPv4, WiFi-first or Ethernet-first. It is host-tested only and <strong>not validated on real hardware</strong>; wire it as documented in <a href="{{repo}}/blob/Main/docs/ETHERNET.md">docs/ETHERNET.md</a>, or use an ESP32-S3 board with built-in Ethernet and PoE (<a href="#buy">see above</a>). A UART cellular modem with a SIM can be used as a primary or failover uplink, also off until configured and not yet tested with a real modem (<a href="{{repo}}/blob/Main/docs/CELLULAR.md">docs/CELLULAR.md</a>).</p>
<p>The standard firmware image includes a driver for an explicitly wired W5500 SPI module: off until configured, explicit pins, DHCP or static IPv4, WiFi-first or Ethernet-first. It is host-tested only and <strong>not validated on real hardware</strong>; wire it as documented in <a href="{{repo}}/blob/Main/docs/ETHERNET.md">docs/ETHERNET.md</a>, or use an ESP32-S3 board with built-in Ethernet and PoE (<a href="#buy">see above</a>). A UART cellular modem with a SIM can also be used as a primary or failover uplink, off until configured; UART modems are not yet tested with real hardware (<a href="{{repo}}/blob/Main/docs/CELLULAR.md">docs/CELLULAR.md</a>).</p>

<h2>Single radio</h2>
<p>The uplink and the access point share one 2.4 GHz radio and channel. After a roam to a different channel the device realigns the AP, which briefly interrupts AP clients.</p>
2 changes: 1 addition & 1 deletion website/pages/21-compatibility.html
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ <h2 id="hardware">Hardware</h2>
<tr><td>Memory</td><td>At least 8 MB quad flash and 8 MB octal PSRAM: <strong>N8R8</strong> and <strong>N16R8</strong> modules (N16R8 tested). Not 4 MB flash, R2 or no PSRAM, or octal-flash modules — see <a href="{{root}}hardware/#unsupported">Hardware</a></td></tr>
<tr><td>Wi-Fi</td><td>2.4 GHz network, WPA2/WPA3 Personal or WPA2-Enterprise (PEAP/TTLS)</td></tr>
<tr><td>USB</td><td>Native USB or a USB-to-UART chip, with a data cable</td></tr>
<tr><td>USB uplinks</td><td>From 3.0.25, one USB modem, 4G stick, USB Ethernet adapter or phone on the board's USB port, with its own 5 V supply; <strong>experimental, not yet tested with real devices</strong> — see <a href="{{root}}usb-devices/">USB devices</a></td></tr>
<tr><td>USB uplinks</td><td>From 3.0.25, one USB modem, 4G stick, USB Ethernet adapter or phone on the board's USB port, with its own 5 V supply. <strong>Tested: TCL LinkKey IK41 4G USB stick</strong> (mobile data as the main uplink); USB modems in serial mode, USB Ethernet adapters and tethering not yet tested with real devices — see <a href="{{root}}usb-devices/">USB devices</a></td></tr>
<tr><td>Ethernet</td><td>Optional W5500 SPI module, driver in the standard image, off until configured; <strong>experimental, not hardware-qualified</strong></td></tr>
</tbody>
</table>
Expand Down
2 changes: 1 addition & 1 deletion website/pages/25-usb-devices.html
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
-->
<h1>USB modems, sticks and Ethernet adapters</h1>
<p>From firmware 3.0.25 the gateway can use <strong>one USB device</strong> on the board's own USB port: a USB LTE modem or 4G stick for the <strong>mobile network (SIM)</strong> uplink, or a USB Ethernet adapter or Android USB tethering for the <strong>Ethernet</strong> uplink. The W5500 module and the modem wired to the pins keep working as before.</p>
<p class="note"><strong>Experimental.</strong> 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 <code>vendor:product</code>.</p>
<p class="note"><strong>Tested:</strong> a <a href="https://link.amazon/B08rO5Fv3" rel="sponsored nofollow noopener" target="_blank">TCL LinkKey IK41 4G USB stick</a> with a SIM, as the main Internet uplink with Tailscale connected over mobile data. USB modems in serial mode, USB Ethernet adapters and phone tethering have not been tested with real devices yet: if you try one, report your board, cable and device (the Network page shows it as <code>vendor:product</code>). <small>Affiliate link: as an Amazon Associate I earn from qualifying purchases.</small></p>

<h2 id="port">1. Which port</h2>
<p>Most ESP32-S3 N8R8/N16R8 boards have two USB-C sockets:</p>
Expand Down
Loading