[DOCS] Overhaul new-user onboarding, home page, and upload flow (#2347)

Getting started:
- New 15-minute Getting Started guide featuring the two most popular
  tracks (BLE on esp32dev-ble, RF on lilygo-rtl_433), with broker setup
  and a verification step
- Sidebar restructured around the new-user journey; upload options
  numbered by ease; Gitpod upload method removed

Home page:
- VitePress hero with clear actions, larger hero image
- How-it-works pipeline diagram shared as a component (responsive via
  container queries), use-case grid, bigger video tiles without the
  image lightbox, refreshed press coverage list, functions pills
- Support section pointing to Theengs Bridge and
  github.com/sponsors/1technophile

Upload flow:
- Decision-oriented upload landing page (journey strip, method cards,
  comparison table)
- Pre-flight checklist and driver troubleshooting on the web installer
- Guided environment picker (bridge + hardware wizard) replacing the
  filter chips, with manifest-verified recommendations
- Post-flash next-steps card linking to the portal and verification

Board images:
- custom_img key in environments.ini and board photos for all
  web-flashable environments (licenses recorded); private prod_env.ini
  environments excluded from boards-info.json

Corrections:
- RF frequency coverage stated as 433/315/868/915MHz
- Removed references to the retired compatible.openmqttgateway.com
  site (BLE list is decoder.theengs.io), the discontinued Theengs
  Plug, and the private sponsor forum


Claude-Session: https://claude.ai/code/session_01TYysQW8tpmt1dWWuzKhTLi

Co-authored-by: Florian <1technophile@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
authored and GitHub committed 2026-08-03 10:23:43 -05:00
1 parent 382aae8353
commit f5b33104ef
67 files changed
+1142 -412

No files matched your search

+25 -14
View File
@@ -2,6 +2,27 @@
aside: false
---
# (Option 1) Upload from the web
This is the easiest way to install OpenMQTTGateway: no software to download, no development environment.
## Before you flash
* Use a **data** USB cable — many cables are charge-only and the board won't show up with one.
* Use **Chrome, Edge or Opera** — Firefox and Safari don't support web flashing.
* Most boards need a **USB serial driver**. Recent operating systems often include it; if your board doesn't appear in the port list, see below.
::: details My board doesn't show up in the port list
1. Try another USB cable (data, not charge-only) and another USB port.
2. Install the driver matching your board's USB chip (check the board's product page if unsure):
* **CP210x** (Silicon Labs): [driver download](https://www.silabs.com/developer-tools/usb-to-uart-bridge-vcp-drivers)
* **CH340 / CH341** (WCH): [driver download](https://www.wch-ic.com/downloads/CH341SER_ZIP.html)
* **CH9102** (WCH): [macOS driver](https://github.com/WCHSoftGroup/ch34xser_macos), [Windows driver](https://www.wch-ic.com/downloads/CH343SER_ZIP.html)
3. On macOS, complete the driver installation by confirming it in the **Security** section of **System Preferences**, then restart. For a LilyGo LoRa32 V2.1 board, the correct port to select is `/dev/cu.wchusbserialXXXXXXXXXXX`.
4. Some boards need the **BOOT** button held down while plugging in the cable to enter flash mode.
5. On Linux, add your user to the `dialout` group (`sudo usermod -a -G dialout $USER`) and log in again.
:::
## Select your firmware
To upload firmware to your ESP device directly from this page, first connect your ESP device to a USB port on your computer. Then, choose the appropriate firmware from the available options. Next, click the **Connect** button and select the USB port where your ESP is plugged in. Wait for the upload process to finish. After the upload completes, you can set up your [WiFi and MQTT credentials](portal.md).
@@ -10,25 +31,15 @@ To upload firmware to your ESP device directly from this page, first connect you
selectorPath="/upload/board-selector.html"
/>
<small style="color: var(--vp-c-text-3);">Board photos courtesy of their manufacturers. ESP32 Feather photo © <a href="https://www.adafruit.com/product/3405">Adafruit Industries</a>, <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA</a>.</small>
::: tip Running on a tablet or phone
If you want to use the BLE decoding capabilities of OpenMQTTGateway with a tablet or smartphone you can use [Theengs App](https://app.theengs.io/).
:::
::: warning Note
If you are on macOS and have a LilyGo LoRa32 V2.1 board, make sure you have the [correct driver for the CH9102 Serial Chip](https://github.com/WCHSoftGroup/ch34xser_macos) installed and selected in the popup when initiating the web install.
To finalise the driver installation don't forget the confirmation in the **Security** section of **System Preferences** after the restart.
The correct driver to then select in the popup of this web install is
`/dev/cu.wchusbserialXXXXXXXXXXX`
:::
## Next step
## Using OpenMQTTGateway ?
Support open-source development through sponsorship and gain exclusive access to our private forum. Your questions, issues, and feature requests will receive priority attention, plus you'll gain insider access to our roadmap.
<div style="text-align: center;">
<iframe src="https://github.com/sponsors/theengs/button" title="Sponsor Theengs" height="32" width="228" style="border: 0; border-radius: 6px;"></iframe>
</div>
Once the upload is complete, connect the gateway to your WiFi network and MQTT broker through the [configuration portal](portal.md).