diff --git a/README.md b/README.md index abf09f4..0723b96 100644 --- a/README.md +++ b/README.md @@ -132,7 +132,7 @@ For the historical 3.0.2 notice bundles, see [their separate checksums](licenses ## Supported hardware

-ESP32-S3 N16R8 or N8R8 board, independent USB power, optional microSD and optional W5500 Ethernet. +ESP32-S3 N16R8 or N8R8 board. Tested 4G setup: one charger on an OTG Y-cable powers the board and a TCL LinkKey IK41 SIM stick; computer on the COM port optional; optional microSD, W5500 Ethernet and UART modem.

Firmware 3.x runs on **ESP32-S3 with 8 MB octal PSRAM and at least 8 MB of @@ -182,13 +182,17 @@ 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 - device's own 5 V supply with grounds connected. LTE modems draw **up to 2 A** + device's own 5 V supply with grounds connected. **Tested:** a single charger + on the Y-cable's power input runs both the board and a TCL LinkKey IK41 + stick (cable plug in the board's USB port, stick in the cable's socket), + with nothing on the COM port. LTE modems draw **up to 2 A** in bursts: a computer's USB port is not enough (modem resets, reset reason BROWNOUT). - Never connect two 5 V sources together: if you bridge the board's USB-OTG pad, never plug that port into a computer or charger. -- After the restart the USB port is a USB host: flash, logs and power go - through the COM port. One device, no hubs, about 10 Mbit/s at most. +- After the restart the USB port is a USB host: flash and logs go through the + COM port; power can come from the Y-cable alone. One device, no hubs, about + 10 Mbit/s at most. - **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 diff --git a/assets/diagrams/hardware.svg b/assets/diagrams/hardware.svg index 61ab578..4207bd5 100644 --- a/assets/diagrams/hardware.svg +++ b/assets/diagrams/hardware.svg @@ -1,38 +1 @@ - - Supported hardware - Supported target: an ESP32-S3 N8R8 or N16R8 board with at least 8 MB flash and 8 MB octal PSRAM, powered over USB-C independently from the machines it recovers. Optional microSD card for the log recorder. Optional W5500 SPI Ethernet module, driver in the standard image and off until configured; experimental and not hardware-validated. - - - - - - - ESP32-S3 - - PSRAM - - Flash - - USB-C - - - ESP32-S3 N16R8 or N8R8 - 8–16 MB flash · 8 MB octal PSRAM · 2.4 GHz WiFi - - - Power - Reliable USB supply, separate from the NAS or PC it should wake - - microSD (optional) - Flight recorder for logs; the firmware runs without it - - W5500 SPI Ethernet (optional) - Explicitly wired module; driver off until configured - Experimental: host-tested, not hardware-validated - HARDWARE - +Supported hardwareAn ESP32-S3 board with 8 MB octal PSRAM and two USB-C ports, powered by a 5 V USB charger. Built-in 2.4 GHz Wi-Fi. Everything else is optional: a computer on the COM port for flashing and logs; on the pins a microSD log recorder, W5500 Ethernet (SPI) or a 4G modem with a SIM (UART); on the USB port one device, a 4G USB stick or modem with a SIM, or a USB Ethernet adapter or phone tethering, connected through an OTG Y-cable whose power input takes the charger so one charger powers both. W5500, UART modems and USB Ethernet are implemented but not yet tested on real hardware.HARDWAREOne ESP32-S3 board; add only what you need.NOT YET TESTEDimplementedoptionalUSB-C plugdata + 5 VOR: Y-cable for USB SIM / EthernetUSB-Aflash · logsSDMMCSPIUARTON THE PINS (OPTIONAL)ESP32-S3PSRAM8 MB octalFlash8–16 MBESP32-S3 boardany board with 8 MB octal PSRAMCOM5 V · flashUSB5 V · flashWi-Fi 2.4 GHzuplink and own access pointbuilt inComputeroptional · powers, flashes, logs5 V USB chargerrequired · plug into COM or USBOR Y-cable: USB SIM / EthernetYOTG Y-cableonly for USB SIM / EthernetUSB device (optional) · one of:4G USB stick or modemSIM · main or backup uplinkUSB Ethernet or tetheringNOT YET TESTEDmicroSDlog recorderW5500 EthernetNOT YET TESTED4G modem · SIMNOT YET TESTED diff --git a/docs/USB-DEVICES.md b/docs/USB-DEVICES.md index 923e460..a66c9fc 100644 --- a/docs/USB-DEVICES.md +++ b/docs/USB-DEVICES.md @@ -86,6 +86,9 @@ socket for the device, and one power input for a USB charger. ``` - The charger powers the device and, through the cable, usually the board too. + **Tested** on an ESP32-S3-DevKitC-1 N16R8 with a TCL LinkKey IK41 stick: one + charger on the power input runs both the board and the stick, with nothing + connected to the COM port. - Check the cable's description: it must pass **data** to the USB-C plug and **power** to the USB-A socket. Charge-only splitters do not work. - Keep the COM port free or connected to a computer only for logs; both can be diff --git a/tools/make_hardware_diagram.py b/tools/make_hardware_diagram.py new file mode 100644 index 0000000..034064c --- /dev/null +++ b/tools/make_hardware_diagram.py @@ -0,0 +1,317 @@ +"""Generate the hardware diagram from one description. + +- assets/diagrams/hardware.svg: static image for the README (self-contained, + dark palette in an embedded {body}\n') + + +def page_block(): + svgs = [] + for cls, fn in (('hw hw-wide', wide), ('hw hw-tall', tall)): + W, H, body = fn(True) + svgs.append(f' {body}\n') + figure = ('
\n' + ''.join(svgs) + + '
Choose a part of the diagram to read what it does.
\n
\n') + items = [] + for key in ORDER: + p = PARTS[key] + st = f' {WARN}' if p['status'] == 'warn' else '' + tested = '' + if p.get('tested'): + model, url = p['tested'] + tested = (f'

Tested with: {model} ' + f'(affiliate link).

') + href, text = p['link'] + items.append(f'
' + f'

{p["title"]}{st}

{p["body"]}

{tested}' + f'

{text}

') + details = '
\n' + '\n'.join(items) + '\n
\n' + return f'{START}\n{figure}{details}{END}' + + +def main(): + ap = argparse.ArgumentParser() + ap.add_argument('--check', action='store_true', help='fail if the generated files are out of date') + args = ap.parse_args() + svg = static_svg() + text = PAGE.read_text(encoding='utf-8') + i, j = text.find(START), text.find(END) + if i < 0 or j < i: + sys.exit(f'{PAGE}: hw-diagram markers missing') + new = text[:i] + page_block() + text[j + len(END):] + if args.check: + stale = [str(p) for p, want in ((SVG_OUT, svg), (PAGE, new)) + if p.read_text(encoding='utf-8').replace('\r\n', '\n') != want.replace('\r\n', '\n')] + if stale: + sys.exit('out of date: ' + ', '.join(stale)) + print('hardware diagram up to date') + return + SVG_OUT.write_text(svg, encoding='utf-8', newline='\n') + PAGE.write_text(new, encoding='utf-8', newline='\n') + print('wrote', SVG_OUT.relative_to(ROOT), 'and', PAGE.relative_to(ROOT)) + + +if __name__ == '__main__': + main() diff --git a/website/assets/site.css b/website/assets/site.css index bd5906f..bdc397f 100644 --- a/website/assets/site.css +++ b/website/assets/site.css @@ -240,3 +240,55 @@ summary { cursor: pointer; font-weight: 600; } .release-note { margin: 0 0 2rem; padding: 1rem 1.2rem; border: 1px solid var(--line); border-left: 3px solid #1FC97A; border-radius: 12px; font-size: .94rem; line-height: 1.65; } .release-note strong { display: block; margin-bottom: .3rem; } @media print { .top, .sidebar, .foot, .copy { display: none; } } +/* Interactive hardware diagram (07-hardware, generated by tools/make_hardware_diagram.py). */ +svg.hw { display: block; width: 100%; height: auto; font-family: var(--font); } +svg.hw .hw-bg { fill: var(--surface); } +svg.hw .hw-box, svg.hw .hw-board { fill: var(--card); stroke: var(--line); stroke-width: 1.5; } +svg.hw .hw-opt { fill: var(--card); stroke: var(--muted); stroke-width: 1.2; stroke-dasharray: 5 4; } +svg.hw .hw-chip-pkg { fill: var(--surface); stroke: var(--line); } +svg.hw .hw-chip { fill: var(--bg); stroke: var(--accent); stroke-width: 1.5; } +svg.hw .hw-port { fill: var(--line); stroke: var(--muted); } +svg.hw .hw-port-usb { stroke: var(--accent); stroke-width: 2; } +svg.hw .hw-wire { fill: none; stroke: var(--muted); stroke-width: 2; } +svg.hw .hw-power { stroke: var(--accent); stroke-width: 3; } +svg.hw .hw-alt { stroke: var(--accent); stroke-dasharray: 6 5; } +svg.hw .hw-radio { fill: none; stroke: var(--muted); stroke-width: 2; stroke-dasharray: 2 5; } +svg.hw .hw-y { fill: var(--bg); stroke: var(--accent); stroke-width: 3; } +svg.hw .hw-hit { fill: transparent; } +svg.hw .hw-group { fill: none; stroke: var(--muted); stroke-width: 1.2; stroke-dasharray: 3 5; } +svg.hw .hw-t { font-size: 14px; font-weight: 600; fill: var(--text); } +svg.hw .hw-h { font-size: 15px; font-weight: 650; fill: var(--text); } +svg.hw .hw-s { font-size: 12.5px; fill: var(--muted); } +svg.hw .hw-m { font-size: 13.5px; fill: var(--muted); } +svg.hw .hw-z { font-size: 11.5px; font-weight: 600; letter-spacing: 2px; fill: var(--muted); } +svg.hw .hw-port-t { font-size: 11.5px; font-weight: 700; fill: var(--text); } +svg.hw .hw-y-t { font-size: 13px; font-weight: 700; fill: var(--text); } +svg.hw .hw-badge-ok { fill: var(--accent); } +svg.hw .hw-badge-warn { fill: var(--amber); } +svg.hw .hw-pwr-t { font-size: 11px; font-weight: 700; fill: var(--accent-text); } +svg.hw .hw-badge-t { font-size: 10.5px; font-weight: 700; letter-spacing: .6px; fill: var(--accent-ink); } +.hw-js svg.hw .hw-part { cursor: pointer; outline: none; } +.hw-js svg.hw .hw-part:hover .hw-box, .hw-js svg.hw .hw-part:hover .hw-opt, .hw-js svg.hw .hw-part:hover .hw-board, +.hw-js svg.hw .hw-part:hover .hw-y { stroke: var(--accent); } +.hw-js svg.hw .hw-part:focus-visible .hw-box, .hw-js svg.hw .hw-part:focus-visible .hw-opt, +.hw-js svg.hw .hw-part:focus-visible .hw-board, .hw-js svg.hw .hw-part:focus-visible .hw-y { stroke: var(--accent); stroke-width: 3; } +.hw-js svg.hw .hw-part.is-active .hw-box, .hw-js svg.hw .hw-part.is-active .hw-opt, +.hw-js svg.hw .hw-part.is-active .hw-board, .hw-js svg.hw .hw-part.is-active .hw-y { stroke: var(--accent); stroke-width: 3; stroke-dasharray: none; } +.hw-details { display: grid; gap: 12px; margin: 0 0 24px; } +.hw-detail { border: 1px solid var(--line); background: var(--card); border-radius: 12px; padding: 14px 18px; } +.hw-detail h2 { margin: 0 0 6px; font-size: 18px; } +.hw-detail p { margin: 6px 0; } +.hw-js .hw-detail { display: none; } +.hw-js .hw-detail.is-active { display: block; border-color: var(--accent); } +.hw-status { display: inline-block; margin-left: 8px; padding: 1px 10px; border-radius: 999px; font-size: 12px; + font-weight: 700; vertical-align: middle; color: var(--accent-ink); } +.hw-status-ok { background: var(--accent); } +.hw-status-warn { background: var(--amber); } +svg.hw-tall { display: none; max-width: 460px; margin: 0 auto; } +.hw-tested { color: var(--muted); } +@media (max-width: 700px) { + figure.hw-diagram { overflow-x: visible; } + figure.hw-diagram svg.hw-wide { display: none; } + figure.hw-diagram svg.hw-tall { display: block; } + figure.hw-diagram figcaption::after { content: none; } +} diff --git a/website/assets/site.js b/website/assets/site.js index 6b74399..3dcd46b 100644 --- a/website/assets/site.js +++ b/website/assets/site.js @@ -128,3 +128,34 @@ }); } })(); +/* Interactive hardware diagram: choosing a part shows its details below. + * Without JavaScript every detail stays visible as a list. */ +(function () { + var fig = document.getElementById('hw-diagram'); + if (!fig) return; + var parts = fig.querySelectorAll('.hw-part'); + var details = document.querySelectorAll('.hw-detail'); + if (!parts.length || !details.length) return; + document.documentElement.classList.add('hw-js'); + function select(key, focusDetail) { + for (var i = 0; i < parts.length; i++) { + var on = parts[i].getAttribute('data-part') === key; + parts[i].classList.toggle('is-active', on); + parts[i].setAttribute('aria-pressed', on ? 'true' : 'false'); + } + for (var j = 0; j < details.length; j++) { + details[j].classList.toggle('is-active', details[j].getAttribute('data-part') === key); + } + if (focusDetail && window.matchMedia('(max-width: 700px)').matches) { + var d = document.getElementById('hw-d-' + key); + if (d) d.scrollIntoView({ block: 'nearest', behavior: 'smooth' }); + } + } + for (var i = 0; i < parts.length; i++) { + parts[i].addEventListener('click', function () { select(this.getAttribute('data-part'), true); }); + parts[i].addEventListener('keydown', function (e) { + if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); select(this.getAttribute('data-part'), true); } + }); + } + select(details[0].getAttribute('data-part'), false); +})(); diff --git a/website/pages/07-hardware.html b/website/pages/07-hardware.html index 517cc93..2dcf406 100644 --- a/website/pages/07-hardware.html +++ b/website/pages/07-hardware.html @@ -7,10 +7,25 @@ order: 7 -->

Hardware

-
- ESP32-S3 N16R8 or N8R8 board with USB-C power, optional microSD and optional W5500 SPI Ethernet. -
Reference target and optional modules.
+ +
+ HARDWAREOne ESP32-S3 board; add only what you need.NOT YET TESTEDimplementedoptionalUSB-C plugdata + 5 VOR: Y-cable for USB SIM / EthernetUSB-Aflash · logsSDMMCSPIUARTON THE PINS (OPTIONAL)ESP32-S3PSRAM8 MB octalFlash8–16 MBESP32-S3 boardany board with 8 MB octal PSRAMCOM5 V · flashUSB5 V · flashWi-Fi 2.4 GHzuplink and own access pointbuilt inComputeroptional · powers, flashes, logs5 V USB chargerrequired · plug into COM or USBOR Y-cable: USB SIM / EthernetYOTG Y-cableonly for USB SIM / EthernetUSB device (optional) · one of:4G USB stick or modemSIM · main or backup uplinkUSB Ethernet or tetheringNOT YET TESTEDmicroSDlog recorderW5500 EthernetNOT YET TESTED4G modem · SIMNOT YET TESTED + HARDWAREOne ESP32-S3 board; add only what you need.Wi-Fi 2.4 GHzbuilt in · uplink and own access pointON THE PINS (OPTIONAL)microSDlog recorderW5500 EthernetNOT YET TESTED4G modem · SIMNOT YET TESTEDflash · logsUSB-C plugdata + 5 VUSB-AESP32-S3PSRAM8 MB octalFlash8–16 MBESP32-S3 boardany board with 8 MB octal PSRAMCOM5 V · flashUSB5 V · flashComputeroptional · via COM5 V USB chargerrequired · COM or USBYOR: Y-cablefor USB SIMor EthernetUSB device (optional) · one of:4G USB stick or modemSIM · main or backup uplinkUSB Ethernet or tetheringNOT YET TESTEDNOT YET TESTEDimplementedoptional +
Choose a part of the diagram to read what it does.
+
+

ESP32-S3 board

Any ESP32-S3 board with 8 MB octal PSRAM and at least 8 MB of quad flash (N16R8 or N8R8 modules). It has two USB-C ports: COM, through a USB-to-serial chip, and USB, the chip's own USB. Either port powers the board and can flash it; while a USB device is active, flash and read logs through COM.

Tested with: ESP32-S3-DevKitC-1 N16R8 (affiliate link).

Supported boards

+

5 V USB charger (required)

The board always needs a 5 V supply. Without a USB device, plug the charger straight into either port, COM or USB. With a USB device, put the charger on the Y-cable's power input instead: one charger of at least 2.5 A powers both the board and the device, with nothing on the COM port. Keep it independent of the NAS or PC the gateway should wake.

Powering USB devices

+

Wi-Fi, built in

The built-in 2.4 GHz Wi-Fi connects to your router and, if you want, also runs the gateway's own access point for IoT devices. Both share one radio and one channel.

Network modes

+

Computer on the COM port (optional)

Use the COM port to flash the firmware (browser installer, Easy Install) and to read the logs. Day to day it is not needed: updates arrive over the air from System → Updates. While a USB device is active, flash and read logs through COM, not through USB.

Install the firmware

+

microSD (optional)

An optional microSD card (SDMMC 1-bit on GPIO38/39/40) keeps a flight recorder of the logs. The firmware runs without it.

Pins and wiring

+

W5500 Ethernet on the pins (optional) Not yet tested

A W5500 SPI module, or an ESP32-S3 board with built-in Ethernet and PoE. The driver is in the standard image, off until configured, Wi-Fi-first or Ethernet-first. Ethernet can also use a USB adapter on the USB port. Experimental: not yet validated on real hardware.

Ethernet guide

+

4G modem with a SIM on the pins (optional) Not yet tested

A 4G/LTE modem module wired to UART pins, with its own 5 V supply for 2 A peaks, as the main or backup uplink. A SIM can also use a USB stick or modem on the USB port. Not yet tested with a real modem.

Cellular guide

+

OTG Y-cable with power input (optional)

Needed only for a USB device (4G stick, USB modem, USB Ethernet or a phone). Its USB-C plug goes into the board's USB port (data and 5 V), the device into its USB-A socket, the charger into its power input. It must pass data: charge-only splitters do not work. The board does not supply 5 V on its USB port by itself.

Y-cable guide

+

4G USB stick or modem with a SIM (optional)

A 4G/LTE USB stick or USB modem with a SIM on the USB port, as the main or backup Internet uplink, with failover and an optional monthly data limit: Tailscale runs over mobile data and name lookups go over the SIM. A modem can also be wired to the pins instead (UART).

Tested with: TCL LinkKey IK41 (affiliate link).

USB devices

+

USB Ethernet adapter or phone tethering (optional) Not yet tested

A USB Ethernet adapter (Realtek RTL8152/8153/8156, CDC-ECM/NCM) or Android USB tethering on the USB port, as the main or backup uplink. Ethernet can also use a W5500 module on the pins (SPI). Not yet tested with real devices.

USB devices

+
+

The firmware runs on an ESP32-S3 with 8 MB octal PSRAM and at least 8 MB of quad flash: N8R8 and N16R8 modules. One image serves both; a 16 MB board uses the first 8 MB.

diff --git a/website/pages/25-usb-devices.html b/website/pages/25-usb-devices.html index e8bd36c..f5dea1c 100644 --- a/website/pages/25-usb-devices.html +++ b/website/pages/25-usb-devices.html @@ -47,6 +47,7 @@

A. Powered OTG Y-cable (recommended, no soldering)

B. The device's own 5 V supply