[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:
67 files changed
+1142
-412
No files matched your search
@@ -1,3 +1,5 @@
|
||||
<FlashEnvironmentSelector
|
||||
boardsUrl="/boards-info.json"
|
||||
firmwareBaseUrl="firmware_build/" />
|
||||
|
||||
<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>
|
||||
@@ -1,18 +0,0 @@
|
||||
# (Option 4) Build from the web
|
||||
|
||||
To build OpenMQTTGateway from the web and download the binary, follow these steps:
|
||||
|
||||
1. Use Gitpod by clicking on the link below:
|
||||
[https://gitpod.io#https://github.com/1technophile/OpenMQTTGateway/tree/development](https://gitpod.io#https://github.com/1technophile/OpenMQTTGateway/tree/development)
|
||||
|
||||
2. This will generate a development environment in your browser and install [platformio](https://platformio.org/) as a build environment.
|
||||
|
||||
3. A first build for `esp32dev-ble` will be launched automatically. To modify the environment configuration, go to the environments.ini file in the root folder and launch the command like the one shown at the bottom of the image below:
|
||||
`platformio run -e <environment name>`
|
||||
|
||||
|
||||
|
||||
4. Wait for the server to build the binary. Once you see [SUCCESS], you can go to `.pio/build/<environment name>` and download `firmware.bin` and `partitions.bin` by right-clicking on each and selecting "Download."
|
||||
|
||||
|
||||
5. Finally, follow [Option 2](binaries.md) to upload the binary.
|
||||
+159
-79
@@ -1,79 +1,159 @@
|
||||
# Upload
|
||||
|
||||
OpenMQTTGateway provides several installation approaches suited for different use cases. The quickest path uses pre-built binaries that work with standard configurations. For custom parameters or specific gateway module combinations, you can build firmware using your development environment. Alternatively, you can flash devices directly from your web browser without installing any software.
|
||||
|
||||
<p align="center">
|
||||
<img src="../img/upload.png" alt="Firmware upload process">
|
||||
</p>
|
||||
|
||||
## Choosing Your Upload Method
|
||||
|
||||
### Web-Based Installation
|
||||
|
||||
The [web installation](web-install.md) method represents the easiest way to get started with OpenMQTTGateway. You can flash your device directly from your browser without downloading files or installing development tools. This method works on Windows, macOS, and Linux with Chrome, Edge, or Opera browsers.
|
||||
|
||||
The web installer displays available environments for different boards and gateway configurations. Select your board type, connect via USB, and click the connect button. The installer handles everything automatically, including erasing old firmware and writing the new one. The web installer uses [ESP Web Tools](https://esphome.github.io/esp-web-tools/) technology to communicate directly with your ESP device.
|
||||
|
||||
### Ready-to-Go Binary Installation
|
||||
|
||||
[Downloading and installing pre-built binaries](binaries.md) offers control over the flashing process using desktop tools. Download the binary files for your board from the [GitHub releases page](https://github.com/1technophile/OpenMQTTGateway/releases).
|
||||
|
||||
For ESP32 devices, you need the firmware binary, bootloader, and boot application partition files written to specific memory addresses. Windows users can use the ESP32 Flash Download Tool from Espressif. On Linux and macOS, the esptool.py command-line utility provides a straightforward upload method.
|
||||
|
||||
This method works well for standard configurations without modifying source code. After flashing, you can still configure WiFi, MQTT broker settings, and basic parameters through the configuration portal.
|
||||
|
||||
### Custom Build and Upload
|
||||
|
||||
[Building from source](builds.md) becomes necessary when you need specific pin assignments, custom MQTT topics, or particular gateway module combinations not available in pre-built binaries.
|
||||
|
||||
[PlatformIO](https://platformio.org/) provides the recommended build environment. After downloading the [source code from GitHub](https://github.com/1technophile/OpenMQTTGateway), you will find a `platformio.ini` file defining build environments for various hardware combinations.
|
||||
|
||||
The configuration system uses a layering approach where default values from [`User_config.h`](https://github.com/1technophile/OpenMQTTGateway/blob/development/main/User_config.h) and [`config_XX.h`](https://github.com/1technophile/OpenMQTTGateway/tree/development/main) files can be overridden by build flags in `platformio.ini` or `environments.ini`. You can embed WiFi credentials and MQTT settings at build time for automatic connection on first boot.
|
||||
|
||||
### Browser-Based Building with Gitpod
|
||||
|
||||
For those who want to build custom firmware without setting up a local development environment, [Gitpod](gitpod.md) offers a cloud-based solution. By clicking on the [Gitpod link](https://gitpod.io#https://github.com/1technophile/OpenMQTTGateway/tree/development), you get a complete development environment running in your browser with PlatformIO already installed and configured.
|
||||
|
||||
After the automatic initial build completes, modify the environment configuration by editing `environments.ini` and run build commands in the browser terminal. Download the generated firmware files and flash them using the binary installation method.
|
||||
|
||||
## Configuring Network and MQTT Settings
|
||||
|
||||
After flashing firmware, configure network connectivity and MQTT broker settings using either runtime or build-time approaches.
|
||||
|
||||
### Runtime Configuration Portal
|
||||
|
||||
When you power on a freshly flashed device, it creates a WiFi access point named OpenMQTTGateway or starting with OMG_. You can find detailed information about the [configuration portal here](portal.md).
|
||||
|
||||
Connecting to this access point opens a portal where you configure your WiFi network, MQTT broker details, and optional security settings including TLS encryption and certificates. For devices with Ethernet, access the portal through the LAN IP address and configure WiFi as fallback connectivity.
|
||||
|
||||
The portal accepts broker IP addresses or hostnames with mDNS support like homeassistant.local. Set a gateway password to protect future configuration changes, OTA updates, and web interface access.
|
||||
|
||||
### Build-Time Configuration
|
||||
|
||||
Alternatively, embed network and MQTT settings directly in firmware during the build process. Set parameters in `User_config.h` or add them as build flags in your PlatformIO environment definition. Store sensitive information in a separate `_env.ini` file excluded from version control.
|
||||
|
||||
## Advanced Configuration Options
|
||||
|
||||
Beyond basic connectivity, OpenMQTTGateway supports several [advanced features](advanced-configuration.md) that enhance security and integration capabilities.
|
||||
|
||||
### Secure MQTT Connections
|
||||
|
||||
For deployments over the internet or public networks, enable TLS encryption to secure communication between the gateway and MQTT broker. Configure your broker with a valid certificate and obtain the Certificate Authority certificate. The gateway can verify server identity against this certificate or connect with encryption without validation.
|
||||
|
||||
Provide the CA certificate at build time in `default_server_cert.h` or paste it into the configuration portal. The gateway supports both self-signed certificates and those from public certificate authorities.
|
||||
|
||||
### Home Assistant Auto-Discovery
|
||||
|
||||
When you use [Home Assistant](https://www.home-assistant.io/) as your home automation platform, OpenMQTTGateway automatically creates device entries and sensors through Home Assistant's MQTT discovery protocol, enabled by default in all standard builds.
|
||||
|
||||
Enable discovery in your Home Assistant MQTT integration settings and create a dedicated MQTT user. The gateway registers itself as a device and creates sensor entities automatically, appearing in Configuration → Devices section.
|
||||
|
||||
### Topic Customization
|
||||
|
||||
The gateway publishes messages to MQTT topics following the format `home/OpenMQTTGateway/GATEWAYtoMQTT`. Enable the `valueAsATopic` feature to append received values to the topic path, making topic-based filtering easier and avoiding warnings in certain controllers.
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successfully uploading firmware and configuring your gateway, you can proceed to configure specific gateway modules for [RF](../setitup/rf.md), [IR](../setitup/ir.md), [Bluetooth](../setitup/ble.md), [LoRa](../setitup/lora.md), or other protocols you want to use. Each module has configuration options adjustable through MQTT commands or the web interface without rebuilding firmware.
|
||||
|
||||
The [troubleshooting section](troubleshoot.md) covers common issues, but if you encounter problems not addressed here, the [OpenMQTTGateway community forum](https://community.openmqttgateway.com) provides an active place to ask questions and share solutions with other users.
|
||||
# Upload
|
||||
|
||||
Getting OpenMQTTGateway onto your board takes three steps, whichever method you pick:
|
||||
|
||||
<div class="omg-journey">
|
||||
<div class="omg-step">
|
||||
<span class="omg-step-num">1</span>
|
||||
<strong>Flash the firmware</strong>
|
||||
<span class="omg-step-sub">pick a method below</span>
|
||||
</div>
|
||||
<span class="omg-step-arrow">→</span>
|
||||
<div class="omg-step">
|
||||
<span class="omg-step-num">2</span>
|
||||
<strong>Configure WiFi & MQTT</strong>
|
||||
<span class="omg-step-sub">through the <a href="./portal.html">portal</a></span>
|
||||
</div>
|
||||
<span class="omg-step-arrow">→</span>
|
||||
<div class="omg-step">
|
||||
<span class="omg-step-num">3</span>
|
||||
<strong>Verify</strong>
|
||||
<span class="omg-step-sub">gateway appears on your <a href="../getting-started.html#step-4-check-that-it-works">broker & controller</a></span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
## Choose your installation method
|
||||
|
||||
<div class="omg-methods">
|
||||
<a class="omg-method" href="./web-install.html">
|
||||
<span class="omg-method-badge">Easiest</span>
|
||||
<h3>1. Web installer</h3>
|
||||
<p><strong>Choose this if</strong> you want the fastest path: flash directly from your browser, nothing to install.</p>
|
||||
<p class="omg-method-req">Needs Chrome, Edge or Opera and a data USB cable. Standard configurations only.</p>
|
||||
</a>
|
||||
<a class="omg-method" href="./binaries.html">
|
||||
<h3>2. Ready-to-go binaries</h3>
|
||||
<p><strong>Choose this if</strong> you prefer a desktop flashing tool (esptool.py, Espressif Flash Download Tool), or web flashing doesn't work for you.</p>
|
||||
<p class="omg-method-req">Same pre-built firmware as the web installer, flashed from your computer.</p>
|
||||
</a>
|
||||
<a class="omg-method" href="./builds.html">
|
||||
<h3>3. Build from source</h3>
|
||||
<p><strong>Choose this if</strong> you need custom pin assignments, module combinations, or credentials embedded at build time.</p>
|
||||
<p class="omg-method-req">Needs <a href="https://platformio.org/">PlatformIO</a>. Full control over the configuration.</p>
|
||||
</a>
|
||||
</div>
|
||||
|
||||
| | Web installer | Binaries | From source |
|
||||
|--------------------------|:---:|:---:|:---:|
|
||||
| No software to install | ✅ | ❌ | ❌ |
|
||||
| Custom configuration | ❌ | ❌ | ✅ |
|
||||
| Difficulty | Easiest | Easy | Advanced |
|
||||
|
||||
## After flashing: configure your gateway
|
||||
|
||||
However you flashed, a freshly installed gateway starts its own WiFi access point (named `OpenMQTTGateway` or starting with `OMG_`). Connect to it and the [configuration portal](portal.md) lets you set your WiFi network, MQTT broker, and optional security settings — no rebuild needed.
|
||||
|
||||
If you build from source you can alternatively [embed the network and MQTT settings at build time](builds.md), so the gateway connects automatically on first boot.
|
||||
|
||||
## Going further
|
||||
|
||||
* [Advanced configuration](advanced-configuration.md) — TLS-secured MQTT connections, certificates, OTA updates.
|
||||
* [Home Assistant integration](../integrate/home_assistant.md) — auto-discovery is enabled by default; your gateway and sensors appear automatically.
|
||||
* [Gateway configuration](../use/gateway.md) — MQTT topic structure and runtime commands per module.
|
||||
|
||||
Stuck? Check the [troubleshooting page](troubleshoot.md), or ask on the [community forum](https://community.openmqttgateway.com).
|
||||
|
||||
<style scoped>
|
||||
.omg-journey {
|
||||
display: flex;
|
||||
align-items: stretch;
|
||||
gap: 8px;
|
||||
margin: 24px 0;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
.omg-step {
|
||||
flex: 1 1 150px;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: center;
|
||||
text-align: center;
|
||||
gap: 4px;
|
||||
background: var(--vp-c-bg-soft);
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 12px;
|
||||
padding: 16px 12px;
|
||||
}
|
||||
.omg-step-num {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
width: 28px;
|
||||
height: 28px;
|
||||
border-radius: 50%;
|
||||
background: var(--vp-c-brand-1);
|
||||
color: var(--vp-c-white, #fff);
|
||||
font-weight: 700;
|
||||
font-size: 14px;
|
||||
}
|
||||
.omg-step-sub {
|
||||
color: var(--vp-c-text-2);
|
||||
font-size: 13px;
|
||||
}
|
||||
.omg-step-arrow {
|
||||
align-self: center;
|
||||
color: var(--vp-c-brand-1);
|
||||
font-size: 20px;
|
||||
font-weight: 700;
|
||||
}
|
||||
.omg-methods {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
|
||||
gap: 16px;
|
||||
margin: 16px 0 24px;
|
||||
}
|
||||
.omg-method {
|
||||
position: relative;
|
||||
display: block;
|
||||
background: var(--vp-c-bg-soft);
|
||||
border: 1px solid var(--vp-c-divider);
|
||||
border-radius: 12px;
|
||||
padding: 20px;
|
||||
text-decoration: none !important;
|
||||
color: var(--vp-c-text-1);
|
||||
transition: border-color 0.2s ease, transform 0.2s ease;
|
||||
}
|
||||
.omg-method:hover {
|
||||
border-color: var(--vp-c-brand-1);
|
||||
transform: translateY(-2px);
|
||||
}
|
||||
.omg-method h3 {
|
||||
margin: 0 0 8px;
|
||||
font-size: 16px;
|
||||
font-weight: 600;
|
||||
color: var(--vp-c-brand-1);
|
||||
}
|
||||
.omg-method p {
|
||||
margin: 0 0 8px;
|
||||
font-size: 14px;
|
||||
line-height: 1.5;
|
||||
}
|
||||
.omg-method-req {
|
||||
color: var(--vp-c-text-2);
|
||||
font-size: 13px !important;
|
||||
}
|
||||
.omg-method-badge {
|
||||
position: absolute;
|
||||
top: -10px;
|
||||
right: 12px;
|
||||
background: var(--vp-c-brand-1);
|
||||
color: var(--vp-c-white, #fff);
|
||||
border-radius: 10px;
|
||||
padding: 2px 10px;
|
||||
font-size: 12px;
|
||||
font-weight: 600;
|
||||
}
|
||||
@media (max-width: 640px) {
|
||||
.omg-journey { flex-direction: column; }
|
||||
.omg-step-arrow { transform: rotate(90deg); }
|
||||
}
|
||||
</style>
|
||||
@@ -1,7 +1,7 @@
|
||||
# Troubleshooting
|
||||
|
||||
## Compilation/build error
|
||||
This badge [](https://github.com/1technophile/OpenMQTTGateway/actions?query=branch%3Amaster+workflow%3ABuild) show you the state of the compilation of the master and this one [](https://github.com/1technophile/OpenMQTTGateway/actions?query=branch%3Adevelopment+workflow%3ABuild) for the development branch.
|
||||
This badge [](https://github.com/1technophile/OpenMQTTGateway/actions?query=branch%3Adevelopment+workflow%3ABuild) show you the state of the compilation of the development branch, from which the releases are made.
|
||||
If you see a green badge this means that the code compilation is OK with the configuration given in the `docs/platformio.ini`.
|
||||
Check your environment, boards , libraries before submitting an issue or a question.
|
||||
|
||||
|
||||
+25
-14
@@ -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).
|
||||
|
||||
Reference in new issue
Block a user