+
+
+
+
+
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 4a4eea071e..0662e7488d 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -1,20 +1,35 @@
+let meta = require('./defaults.json');
+try {
+ meta_overload = require('./meta.json');
+ meta = { ...meta, ...meta_overload };
+} catch (e) {
+ console.warn('meta.json not found or not valid. Using default configuration.');
+}
+
+
+
+const fs = require('fs');
+const path = require('path');
+const commonConfigPath = path.resolve(__dirname, 'public/commonConfig.js');
+if (!fs.existsSync(commonConfigPath)) {
+ throw new Error(`commonConfig.js not found in ${commonConfigPath}.\nPlease download from https://www.theengs.io/commonConfig.js or create this file before you build the documentation.`);
+}
const commonConfig = require('./public/commonConfig');
module.exports = {
...commonConfig,
- title: 'Theengs OpenMQTTGateway version_tag',
- base: '/',
+ title: `${meta.title} - ${meta.version}`,
+ base: meta.url_prefix,
+ dest: meta.dest, // default is generated/site
description: 'One gateway, many technologies: MQTT gateway for ESP8266 or ESP32 with bidirectional 433mhz/315mhz/868mhz, Infrared communications, BLE, LoRa, beacons detection, mi flora / mi jia / LYWSD02/ Mi Scale compatibility, SMS & LORA.',
- head: [
- ...commonConfig.head,
- ['script', {type: 'module', src: 'https://unpkg.com/esp-web-tools@9.4.3/dist/web/install-button.js?module'}]
- ],
+ head: [...commonConfig.head],
themeConfig: {
- repo: '1technophile/OpenMQTTGateway',
- docsDir: 'docs',
...commonConfig.themeConfig,
+ repo: meta.theme_config_repo,
+ docsDir: 'docs',
+ mode: meta.mode,
sidebar: [
- ['/','0 - What is it for 🏠'],
+ ['/', '0 - What is it for 🏠'],
{
title: '1 - Prerequisites🧭', // required
//collapsable: true, // optional, defaults to true
@@ -42,9 +57,10 @@ module.exports = {
},
{
title: '3 - Upload ➡️', // required
+ path: '/upload/',
sidebarDepth: 1, // optional, defaults to 1
children: [
- 'upload/web-install',
+ ['upload/web-install', "(Option 1) Upload from the web"],
'upload/binaries',
'upload/builds',
'upload/gitpod',
@@ -86,23 +102,25 @@ module.exports = {
},
{
title: '6 - Participate 💻', // required
+ path: '/participate/',
sidebarDepth: 1, // optional, defaults to 1
children: [
+ 'participate/quick_start',
'participate/support',
'participate/development',
'participate/adding-protocols',
'participate/community',
- ['https://github.com/1technophile/OpenMQTTGateway/blob/development/LICENSE.txt','License']
+ [meta.url_license_file, 'License']
]
}
- ]
+ ]
},
plugins: {
'sitemap': {
- hostname: 'https://docs.openmqttgateway.com',
+ hostname: meta.hostname,
urls: [
'https://decoder.theengs.io/devices/devices.html',
- 'https://community.openmqttgateway.com/',
+ meta.url_community_forum,
'https://shop.theengs.io/',
'https://shop.theengs.io/products/theengs-plug-smart-plug-ble-gateway-and-energy-consumption',
'https://shop.theengs.io/products/theengs-bridge-esp32-ble-mqtt-gateway-with-ethernet-and-external-antenna',
diff --git a/docs/.vuepress/defaults.json b/docs/.vuepress/defaults.json
new file mode 100644
index 0000000000..2c8ddcaed7
--- /dev/null
+++ b/docs/.vuepress/defaults.json
@@ -0,0 +1,12 @@
+{
+ "title": "Theengs OpenMQTTGateway",
+ "version": "edge",
+ "url_prefix": "/",
+ "dest": "generated/site",
+ "mode": "prod",
+ "url_license_file": "https://github.com/1technophile/OpenMQTTGateway/blob/development/LICENSE.txt",
+ "url_community_forum": "https://community.openmqttgateway.com",
+ "hostname": "https://docs.openmqttgateway.com",
+ "repo": "1technophile/OpenMQTTGateway",
+ "theme_config_repo": "1technophile/OpenMQTTGateway"
+}
\ No newline at end of file
diff --git a/docs/.vuepress/public/img/microcontroller.gif b/docs/.vuepress/public/img/microcontroller.gif
new file mode 100644
index 0000000000..40a9bc2f77
Binary files /dev/null and b/docs/.vuepress/public/img/microcontroller.gif differ
diff --git a/docs/README.md b/docs/README.md
index 7b8fcb9f88..01443ad030 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,3 +1,13 @@
+
+
+
+::: warning Development Version
+This is the edge version of the documentation. It is under active development and may contain bugs, incomplete features, or breaking changes. Use it at your own risk.
+:::
+
+
+
+
OpenMQTTGateway aims to unify various technologies and protocols into a single firmware. This reduces the need for multiple physical bridges and streamlines diverse technologies under the widely-used [MQTT](http://mqtt.org/) protocol.
diff --git a/docs/img/upload.png b/docs/img/upload.png
new file mode 100644
index 0000000000..9ea66169b7
Binary files /dev/null and b/docs/img/upload.png differ
diff --git a/docs/participate/README.md b/docs/participate/README.md
new file mode 100644
index 0000000000..34618ee100
--- /dev/null
+++ b/docs/participate/README.md
@@ -0,0 +1,46 @@
+# Participate in OpenMQTTGateway
+
+OpenMQTTGateway is community-driven: every feature, bug fix, and doc improvement comes from contributors like you. Whether you want to add support for a new sensor, fix a bug, improve documentation, or just help others—there's a place for you here.
+
+## Choose your path
+
+### 🚀 New to the project? Start here
+[**Quick Start Guide**](./quick_start.md) walks you through setting up your development environment, building firmware, and previewing the docs. It covers PlatformIO, VS Code, terminal workflows, and troubleshooting. Perfect if you're new to ESP32/ESP8266 development or just want to get your hands dirty quickly.
+
+**What you'll learn:** Installing tools · Building firmware · Flashing boards · Running tests · Working with the docs
+
+---
+
+### 💻 Ready to contribute code?
+[**Development Contributions**](./development.md) covers the contribution workflow: naming conventions, code quality checks, testing on multiple boards, and opening pull requests. This is your checklist before submitting code.
+
+**What you'll find:** PR workflow · Naming rules (ZgatewayXXX, ZsensorYYY) · QA automation · DCO · CI/CD integration
+
+---
+
+### 🔌 Adding a new protocol or device?
+[**Adding Protocols**](./adding-protocols.md) explains how to integrate RF, IR, or BLE devices. Most protocol work happens upstream (RCSwitch, Pilight, IRRemoteESP8266, Theengs Decoder), and this guide shows you how to wire it into OMG.
+
+**What you'll learn:** Upstream contribution · Protocol integration · Testing decoders · Payload validation
+
+---
+
+### 💬 Join the community
+[**Community Participation**](./community.md) is where you ask questions, share your projects, and help others. The forum is the first stop for feature requests, debugging help, and general IoT/home automation discussion.
+
+**What you can do:** Ask questions · Share builds · Propose features · Help newcomers
+
+---
+
+### ❤️ Support the project
+[**Supporting the Project**](./support.md) lists all the ways you can help beyond code: answering forum questions, improving docs, purchasing Theengs products, sponsoring developers, or creating content about your OMG setup.
+
+**How you can help:** Forum support · Documentation · Sponsorship · Content creation
+
+---
+
+::: tip Not sure where to start?
+- **First time here?** → [Quick Start](./quick_start.md)
+- **Have a fix or feature ready?** → [Development contributions](./development.md)
+- **Need help or want to discuss?** → [Community](./community.md)
+:::
diff --git a/docs/participate/adding-protocols.md b/docs/participate/adding-protocols.md
index 88b174cb09..5a19e993c1 100644
--- a/docs/participate/adding-protocols.md
+++ b/docs/participate/adding-protocols.md
@@ -1,12 +1,22 @@
# Adding protocols
-Adding your device protocol to OpenMQTTGateway enables it to increase interoperability and to create new use cases with your device. Below you will find some guidance to do that.
+Adding your device protocol to OpenMQTTGateway increases interoperability and creates new use cases. Use the steps below to pick the right path and upstream your changes.
+
+::: tip Before you open a PR
+Read the [Development contributions guide](./development.md) for naming rules, QA, and PR steps. It keeps your protocol addition reviewable.
+:::
## RF or IR
-For adding RF and IR protocols to OpenMQTTGateway the best way is to do a pull request to [RCSwitch](https://github.com/1technophile/rc-switch), [Pilight](https://github.com/pilight/pilight) for RF, and [IRRemoteESP8266](https://github.com/crankyoldgit/IRremoteESP8266) for IR.
+1. Implement or extend the protocol in the upstream libs first: [RCSwitch](https://github.com/1technophile/rc-switch) or [Pilight](https://github.com/pilight/pilight) for RF, and [IRRemoteESP8266](https://github.com/crankyoldgit/IRremoteESP8266) for IR.
+2. Once merged (or while your PR is pending), wire it in OMG as a new decoder/mapping.
+3. Add a short test sniff/build locally with the relevant environment (for example `esp32dev-all-test`).
## BLE
-For BLE message decoding OpenMQTTGateway uses the [Theengs Decoder](https://decoder.theengs.io/) library. New device decoder pull requests can be submitted directly to the [GitHub repository](https://github.com/theengs/decoder).
+1. For BLE message decoding, OpenMQTTGateway uses [Theengs Decoder](https://decoder.theengs.io/). Submit new device decoders directly to the [GitHub repository](https://github.com/theengs/decoder).
+2. After the decoder exists, ensure the device is reported correctly through OMG (advertising devices are supported without connection).
+3. Build locally for a BLE-enabled environment and validate the payload.
-Currently we support the reading of advertizing BLE devices, advertizing means that the BLE device broadcasts regularly its sensor data without the need of a BLE connection.
+Notes:
+- We support reading **advertising** BLE devices (they broadcast regularly without a connection).
+- Keep payloads compact and follow existing JSON fields for consistency.
diff --git a/docs/participate/community.md b/docs/participate/community.md
index d8494b6b81..ded39a8523 100644
--- a/docs/participate/community.md
+++ b/docs/participate/community.md
@@ -1,4 +1,9 @@
# Community participation
-The first entry step for participating to OMG is sharing and discussing with the [community](https://community.openmqttgateway.com), by sharing your experiences and answering to other questions you are giving back what the others gave to you.
+The first entry step for participating to OMG is sharing and discussing with the [community](https://community.openmqttgateway.com). By sharing your experiences and answering questions you give back what others gave to you.
-You can use the forum to ask questions, post answers, suggest features and discuss about home automation or Internet of things in a more general way.
\ No newline at end of file
+Use the forum to:
+- Ask questions about hardware, builds, MQTT, BLE/RF/IR, or docs.
+- Share projects, logs, and payload samples that help others.
+- Suggest features or confirm if something already exists.
+
+When you have a change to contribute, follow the [Development contributions guide](./development.md) for the PR flow.
\ No newline at end of file
diff --git a/docs/participate/development.md b/docs/participate/development.md
index f2488c9640..f67a235928 100644
--- a/docs/participate/development.md
+++ b/docs/participate/development.md
@@ -1,30 +1,37 @@
# Development contributions
-We like pull requests from everyone. By participating in this project, you
-agree to follow the code of conduct below
+We like pull requests from everyone and ask you to follow the code of conduct below.
-[code of conduct](https://github.com/1technophile/OpenMQTTGateway/blob/master/CODE_OF_CONDUCT.md)
+* [Code of conduct](https://github.com/1technophile/OpenMQTTGateway/blob/master/CODE_OF_CONDUCT.md)
-[code style guide](https://google.github.io/styleguide/cppguide.html#Formatting)
+* [Code style guide](https://google.github.io/styleguide/cppguide.html#Formatting)
-So as to format automatically your document you have to add the "clang-Format" extension to VSCode, once done, you can format the code by doing a right click into the code file window and clicking "Format document".
+If you need a step-by-step install and build guide, read the [Quick Start to Develop OpenMQTTGateway](./quick_start.md). It explains the tools, PlatformIO, and docs workflow. Use this page as a fast checklist once you know the flow.
-Fork the [development branch](https://github.com/1technophile/OpenMQTTGateway/tree/development), then clone the repo
+**Quick checklist**
+1. Fork the [development branch](https://github.com/1technophile/OpenMQTTGateway/tree/development) and clone the repo.
+2. Make your changes and follow the naming rules:
+ * New gateway: `ZgatewayXXX` where `XXX` is the protocol name.
+ * New sensor: `ZsensorYYY` where `YYY` is the sensor type.
+ * New actuator: `ZactuatorZZZ` where `ZZZ` is the actuator type.
+3. Review your code and compile for ESP32 and ESP8266.
+4. Test on your hardware.
+5. Open a pull request, verify the GitHub Actions CI build, and request a review.
-Make your modification,
-* If you want to add a new gateway, name it `ZgatewayXXX`, `XXX` replaced by your gateway communication type, can be more than three letters
-* If you want to add a new sensor, name it `ZsensorYYY`, `YYY` replaced by your sensor type, can be more than three letters
-* If you want to add a new actuator, name it `ZactuatorZZZ`, `ZZZ` replaced by your actuator type, can be more than three letters
+## Automated Testing and CI
-Review your code, compile it for ESP32 and ESP8266
+Your pull request will be automatically tested by GitHub Actions. If you want to run the same checks locally before pushing, you can use the `ci.sh` script in the scripts folder.
-Test it locally on your hardware config
+**Need help with the ci.sh commands?** See [section 5 in Quick Start](./quick_start.md#5-firmware-development-from-the-terminal-with-cish) for detailed examples of running QA checks and builds from the terminal.
-Emit a pull request
+For more details on how CI works and available scripts, see the [CI documentation](https://github.com/1technophile/OpenMQTTGateway/blob/development/scripts) in the scripts folder.
-Verify the GitHub Actions CI compilation results
+For a comprehensive overview of all GitHub Actions workflows used in this project, check the [Workflows README](https://github.com/1technophile/OpenMQTTGateway/tree/development/.github/workflows).
+
+## Code Quality
+
+To format your code automatically, add the "clang-Format" extension to VSCode, then right click in the file and choose "Format document".
-Request for review
We may suggest some changes, improvements or alternatives.
diff --git a/docs/participate/quick_start.md b/docs/participate/quick_start.md
new file mode 100644
index 0000000000..23367f06f7
--- /dev/null
+++ b/docs/participate/quick_start.md
@@ -0,0 +1,840 @@
+---
+title: Quick Start to Develop OpenMQTTGateway
+permalink: /participate/quick_start.html
+sidebarDepth: 2
+lang: en-US
+---
+
+# Quick Start to Develop OpenMQTTGateway
+
+This document helps a new contributor. Maybe this is your first time with:
+
+- Git
+- PlatformIO
+- ESP32 or ESP8266
+
+It is normal to feel a bit lost at the beginning. This guide walks with you, step by step.
+
+::: tip Already experienced?
+If you only need the contribution rules and PR flow, jump to [Development contributions](./development.md). For community help or non-code support, see [Community participation](./community.md) and [Supporting the project](./support.md).
+:::
+
+
+
+In this document you will learn how to:
+
+- Prepare the development environment on Windows or Linux.
+- Build and flash the firmware (ESP32 / ESP8266 and other boards).
+- Build and preview the documentation website in the docs folder.
+
+At the end of each step you see a **Check**. Use it to confirm that the previous step is correct before you go to the next one. If a check fails, do not worry: read the step again, fix it, and try one more time.
+
+
+
+## 1. Understand this project
+
+OpenMQTTGateway is a firmware project. It runs on ESP32, ESP8266 and other boards. It connects many protocols (Bluetooth, RF, IR, LoRa, sensors) to MQTT.
+
+The repository also contains the documentation website. The docs use VuePress and live in the docs folder.
+
+Very simple view of the repository:
+
+- main: C++ source code for the firmware.
+- lib: reusable libraries.
+- scripts: helper scripts for build, test, CI.
+- docs: documentation website.
+
+You will mainly work on:
+
+- Firmware code: files under main and sometimes lib.
+- Docs site: files under docs and docs/.vuepress.
+
+**Check:** open the repository in a file explorer and confirm you see at least main, lib, scripts and docs folders. If not, read section 3 again.
+
+
+
+## 2. Prepare your computer
+
+You can use Windows or Linux. The steps are very similar. The examples use a terminal. On Windows you can use **Git Bash** or **WSL**; on Linux you can use your normal shell.
+
+Not everybody needs to install the same tools. It depends on what you want to do:
+
+- **Only firmware (with VS Code or terminal):** you mainly need Git, PlatformIO, VS Code (if you like GUI) and a bash shell.
+- **Only documentation website:** you mainly need Git, Node.js and npm.
+- **Both firmware and docs:** you need everything.
+
+The next subsections explain this.
+
+### 2.1 Common tools (for everyone)
+
+Install these tools first. They are useful for **all** types of work:
+
+- Git
+- Visual Studio Code (recommended, but you can also use another editor)
+- A bash shell
+ - On Windows: Git Bash or WSL (Ubuntu is a good choice).
+
+On Windows you can download:
+
+- Git from the official site:
+- Visual Studio Code from
+- Git Bash comes with "Git for Windows".
+
+On Linux you can install these with your package manager (for example apt on Ubuntu). For more help you can read the Git book: .
+
+**Check (common tools):** open a terminal (Git Bash, WSL, or Linux shell) and run:
+
+```bash
+git --version
+```
+
+If this command fails, install Git again and then close and reopen the terminal.
+
+### 2.2 Tools for firmware development
+
+For firmware builds you need **PlatformIO**. PlatformIO itself will install the right compiler and frameworks for your boards.
+
+You have two main options:
+
+1. Use **PlatformIO inside VS Code** (recommended for most users).
+2. Use **PlatformIO CLI in the terminal** (good for advanced or CI usage).
+
+#### 2.2.1 PlatformIO inside VS Code (recommended)
+
+If you only plan to build firmware from VS Code, you usually do **not** need to install Python or PlatformIO CLI manually. The PlatformIO extension will download what it needs.
+
+- Just install VS Code and the PlatformIO extension (see section 2.3).
+- When you first open the project, PlatformIO will set up its own tools.
+
+**Check:** after installing the extension and opening the project, the VS Code status bar shows something like "PlatformIO: Ready".
+
+#### 2.2.2 PlatformIO command line (CLI) with Python (for terminal builds)
+
+If you want to use the bash scripts (ci.sh, ci_build_firmware.sh, etc.) or build from a plain terminal, you need Python and PlatformIO CLI.
+
+Install these extra tools:
+
+- Python 3.10 or newer
+- PlatformIO CLI (pip package)
+
+PlatformIO is the main build system for this project. We will use it from VS Code and from the terminal. If you want to read more, the official docs are here: .
+
+On Windows you can download Python from:
+
+On Linux you can install Python with your package manager.
+
+Then install PlatformIO CLI globally with Python:
+
+```bash
+python3 -m pip install -U platformio
+```
+
+**Check (firmware tools):**
+
+```bash
+python3 --version
+platformio --version
+```
+
+If you see version numbers, the install is good. If the platformio command is not found, check that Python added the scripts folder (for example ~/.local/bin on Linux) to your PATH, then open a new terminal and try again.
+
+### 2.3 Tools for documentation website (Node.js and npm)
+::: warning Note
+This section is **only needed** if you want to **build or preview the site on your own computer**.
+:::
+
+If you want to build or edit the **documentation website**, you also need Node.js and npm. You do **not** need these tools just to build firmware.
+
+Install:
+
+- Node.js 18 or newer
+- npm (usually comes with Node.js)
+
+On Windows you can get Node.js from:
+
+On Linux you can install Node.js with your package manager or by following the docs: .
+
+**Check (docs tools):**
+
+```bash
+node --version
+npm --version
+```
+
+If one of these commands fails, reinstall Node.js, close the terminal, and try again.
+
+### 2.4 PlatformIO extension in Visual Studio Code
+Now add PlatformIO inside VS Code. You can also see pictures of these steps in many ESP32 + PlatformIO tutorials, for example on the PlatformIO site: .
+
+Steps (based on common PlatformIO + VS Code ESP32 guides, adapted for this project):
+
+1. Open Visual Studio Code.
+2. Click the Extensions icon on the left.
+3. In the search box, type "PlatformIO IDE".
+4. Click **Install** on the "PlatformIO IDE" extension.
+
+When the install finishes, a new icon appears on the left sidebar. It looks like an ant or an alien head. This opens the PlatformIO view.
+
+**Check:**
+
+- In VS Code, you see the PlatformIO icon on the left.
+- If you click it, PlatformIO opens without errors.
+
+If you do not see the icon, restart VS Code and wait a few seconds.
+
+**Friendly tip:** the first install can take several minutes because PlatformIO downloads tools for many boards. It happens only once. You can get a coffee while it works.
+
+
+
+## 3. Get the source code
+
+Now download this repository to your computer from GitHub.
+
+1. Open a terminal (Git Bash, WSL or Linux shell).
+2. Choose a parent folder where you want to keep your projects.
+3. Run:
+
+```bash
+git clone https://github.com/1technophile/OpenMQTTGateway.git
+cd OpenMQTTGateway
+```
+
+**Check:**
+
+- Run:
+
+ ```bash
+ git status
+ ```
+
+- The output should say "On branch" and "nothing to commit".
+- In your file explorer or with:
+
+ ```bash
+ ls
+ ```
+
+ you should see main, lib, scripts, docs and other files.
+
+If the clone fails, check your internet connection or a possible proxy. Then try again. If you are new to Git, the GitHub "Hello World" guide can also help: .
+
+
+
+## 4. Firmware development with Visual Studio Code and PlatformIO
+
+This section explains how to build and flash the firmware using Visual Studio Code with the PlatformIO extension.
+
+If you know the classic Arduino IDE, you can think of PlatformIO as a more powerful alternative. It manages many boards, libraries, and environments for you. The official introduction is here: .
+
+You do **not** create a new PlatformIO project. This repository is already a PlatformIO project. You just open it.
+
+### 4.1 Open the project in VS Code
+
+1. Start Visual Studio Code.
+2. Click **File → Open Folder…**.
+3. Select the OpenMQTTGateway folder you cloned in section 3.
+4. Click **Open**.
+
+VS Code will load the folder. PlatformIO will detect the platformio.ini file and start to prepare its toolchain (compiler, libraries, board support). You do not need to install these by hand.
+
+**Check:**
+
+- In the bottom status bar you see messages like "PlatformIO: Installing" and then "PlatformIO: Ready".
+- You can also open a terminal inside VS Code (View → Terminal) and run:
+
+ ```bash
+ pio --version
+ ```
+
+ You should see the PlatformIO version.
+
+If PlatformIO stays stuck on "Installing" for a long time, close VS Code, reopen it and wait again. Check that your internet connection is working.
+
+### 4.2 Look at the PlatformIO project structure
+
+PlatformIO projects usually have folders like (you will see similar names in many tutorials):
+
+- src: main source code.
+- lib: libraries.
+- include: headers.
+- platformio.ini: configuration for boards and environments.
+
+In OpenMQTTGateway the structure is a bit different, because it is a large project:
+
+- main: main C++ files for the firmware.
+- lib: libraries used by the firmware.
+- platformio.ini and environments.ini: list many PlatformIO environments.
+- test: tests for PlatformIO unit test framework.
+
+**Check:** open platformio.ini in VS Code and scroll. You should see several [env:...] sections. This means PlatformIO understands the project.
+
+If you want to know more about this file, see the PlatformIO docs about configuration: .
+
+### 4.3 Choose a PlatformIO environment
+
+An "environment" in PlatformIO is a build target. It defines the board, framework and options. You can think of it as a named profile for a specific device.
+
+To select the environment for your board:
+
+1. Press Ctrl+Shift+P (on macOS use Cmd+Shift+P).
+2. Type "PlatformIO: Switch Project Environment" and press Enter.
+3. A list of environments appears (for example esp32dev-all-test, theengs-bridge and many others).
+4. Choose an environment that matches your board. For a generic ESP32 DevKit you can start with **esp32dev-all-test**.
+
+**Check:**
+
+- Look at the bottom blue bar. You should see the selected environment name.
+
+If you chose the wrong environment, repeat the steps and pick another one.
+
+### 4.4 Build the firmware in VS Code
+
+Now compile the firmware.
+
+1. In VS Code, open the PlatformIO view (left sidebar icon).
+2. In the PlatformIO toolbar (bottom of the window), click the **check** (✓) icon. This runs the "Build" task.
+
+PlatformIO now compiles the code for the selected environment. This can take several minutes the first time.
+
+**Check:**
+
+- In the Terminal panel, the build ends with the word "SUCCESS".
+- On disk, a file like:
+
+ ```
+ .pio/build//firmware.bin
+ ```
+
+ exists.
+
+If the build fails, read the error at the end of the log. Take your time; errors are part of the normal developer life.
+
+Common problems:
+
+- Missing tools: check that platformio works from the terminal (section 2.2).
+- Wrong environment: try with esp32dev-all-test first.
+
+Fix the problem, then run the build again.
+
+### 4.5 Upload the firmware to the board
+
+After a successful build you can flash the firmware (upload the program to the board).
+
+1. Connect your ESP board to the computer with a good USB cable.
+2. In the PlatformIO toolbar click the **right arrow** (→) icon. This runs the "Upload" task.
+
+PlatformIO selects a serial port automatically in many cases.
+
+**Check:**
+
+- The upload log ends with success, and no "Failed to connect" error.
+- The board reboots after upload.
+
+If the upload fails:
+
+- Check the USB cable (some cables are power-only and do not carry data).
+- On some boards you must press and hold the BOOT button during upload.
+- Make sure no other program is using the same serial port (for example another serial monitor).
+- You can set the serial port manually in platformio.ini with the upload_port option.
+
+### 4.6 Open the Serial Monitor
+
+The Serial Monitor lets you see log messages from the firmware.
+
+1. In the PlatformIO toolbar click the **plug** icon. This opens the Serial Monitor.
+2. Set the baud rate to 115200 if it is not already set.
+
+**Check:**
+
+- After reset, you see text from the board, for example boot messages and MQTT logs.
+
+If the text is unreadable, check that the baud rate matches the value in platformio.ini (monitor_speed). In this project the default is usually 115200.
+
+If you want to learn more about Serial Monitor problems, the PlatformIO docs have a short page: .
+
+### 4.7 Run PlatformIO tests (optional)
+
+You can run unit tests for the project.
+
+1. Open a terminal inside VS Code (View → Terminal).
+2. In the project root, run:
+
+```bash
+pio test -e test
+```
+
+**Check:**
+
+- The output ends with "SUCCESS". If tests fail, read which test failed and open the file under test to understand why.
+
+
+## 5. Firmware development from the terminal with ci.sh
+
+You can also work only from the terminal. This is useful if you prefer command line, use remote development, or want to reproduce the same steps as the CI (Continuous Integration, the automatic build that runs on GitHub).
+
+All helper scripts live in the scripts folder. The main entry point is:
+
+- scripts/ci.sh
+
+This script calls other scripts:
+
+- scripts/ci_build.sh
+- scripts/ci_build_firmware.sh
+- scripts/ci_prepare_artifacts.sh
+- scripts/ci_site.sh
+- scripts/ci_qa.sh
+- scripts/ci_list-env.sh
+
+The scripts are written for bash. On Windows always use **Git Bash** or **WSL** for them, not plain PowerShell or cmd.
+
+If you are new to bash, a gentle introduction is here: .
+
+### 5.1 Check that you are in the right place
+
+1. Open a bash terminal.
+2. Go to your clone:
+
+```bash
+cd path/to/OpenMQTTGateway
+```
+
+**Check:** run:
+
+```bash
+ls scripts main docs
+```
+
+You should see these folders listed. If not, you are in the wrong directory.
+
+### 5.2 List available firmware environments
+
+You can ask the helper scripts which PlatformIO environments exist.
+
+```bash
+./scripts/ci.sh list-env
+```
+
+**Check:**
+
+- The command prints many names in columns (for example esp32dev-all-test, theengs-bridge, rfbridge-direct, and so on).
+
+If the command fails with "command not found" or similar, confirm that bash is used and that the file has execute permission (on Linux you may need chmod +x scripts/ci.sh).
+
+### 5.3 Quick build of one firmware (simple mode)
+
+Use ci.sh with the build command to build one firmware from the terminal.
+
+Example for a development build on esp32dev-all-test:
+
+```bash
+./scripts/ci.sh build esp32dev-all-test --mode dev --verbose
+```
+
+What this does:
+
+- Checks that Python, PlatformIO and git are installed.
+- Calls ci_build_firmware.sh to run platformio run -e esp32dev-all-test.
+- Optionally prepares artifacts if you add deployment options.
+
+Useful flags:
+
+- --mode dev or --mode prod: choose development or production mode. For local work, **dev** is usually enough.
+- --clean: remove old build files before building.
+- --verbose: show more logs from PlatformIO.
+
+**Check:**
+
+- The command ends with a "Build Summary" block and "Status: SUCCESS".
+- The folder .pio/build/esp32dev-all-test contains firmware.bin.
+
+If the build fails, read the error line near the bottom. Fix missing tools (see section 2) or wrong environment name, then run the command again.
+
+### 5.4 Use ci_build_firmware.sh directly (advanced control)
+
+Sometimes you want to work closer to PlatformIO.
+
+You can call scripts/ci_build.sh directly when you want more control or when you debug a CI issue:
+
+```bash
+./scripts/ci_build.sh esp32dev-all-test --dev-ota --clean --verbose
+```
+
+This script:
+
+- Validates the environment name.
+- Sets environment variables for the build (for example OMG_VERSION, OTA flags).
+- Runs platformio run for the chosen environment.
+- Verifies that firmware.bin and other files exist.
+
+**Check:**
+
+- At the end you see a "Build Summary" for that environment.
+- The directory .pio/build/esp32dev-all-test contains .bin and .elf files.
+
+If there are no artifacts, check that PlatformIO is installed and that the environment name matches one from ci_list-env.sh.
+
+### 5.5 Prepare artifacts for sharing or flashing tools
+
+After a successful build, you can create a clean set of files ready for release or for use with external flashing tools (for example esptool.py or web uploaders).
+
+Use scripts/ci_prepare_artifacts.sh through ci_build.sh, or call it directly.
+
+Example (after a build) with ci_build.sh wrapper:
+
+```bash
+./scripts/ci_build.sh esp32dev-all-test --mode prod --deploy-ready
+```
+
+Example direct call to ci_prepare_artifacts.sh:
+
+```bash
+./scripts/ci_prepare_artifacts.sh esp32dev-all-test --clean
+```
+
+This script:
+
+- Copies firmware.bin, partitions.bin, bootloader.bin and other files from .pio/build/ into the output folder.
+- Renames them with the environment name, for example esp32dev-all-test-firmware.bin.
+- Creates archives for the libraries used by that environment.
+
+**Check:**
+
+- The folder generated/toDeploy (or your custom output) exists.
+- It contains files like -firmware.bin and one or more *-libraries.tgz archives.
+
+If the script says the build directory is missing, run a firmware build first (section 5.3 or 5.4).
+
+### 5.6 Run QA checks from the terminal
+
+Before you send a pull request, it is good to check the code style.
+
+Run:
+
+```bash
+./scripts/ci.sh qa --check
+```
+
+This uses scripts/ci_qa.sh to run clang-format checks on files under main by default.
+
+**Check:**
+
+- The summary says "Status: SUCCESS".
+
+If there are formatting problems, you can auto-fix them:
+
+```bash
+./scripts/ci.sh qa --fix
+```
+
+After this, review the changes with git diff, then commit them.
+
+### 5.7 Run the full pipeline (QA + firmware build + docs)
+
+For a full local run, similar to CI, use:
+
+```bash
+./scripts/ci.sh all esp32dev-all-test --mode prod
+```
+
+This will:
+
+- Run QA checks.
+- Build the firmware.
+- Build the documentation site in production mode (unless you add --no-site).
+
+**Check:**
+
+- At the end you see a "Complete Pipeline Summary" with "Status: SUCCESS".
+
+If QA fails, fix style issues first. If the build fails, fix code or environment problems, then run again.
+
+::: tip Next Steps
+Once your code builds successfully, check the [Development contributions guide](./development.md) for:
+- Code naming rules (ZgatewayXXX, ZsensorYYY, etc.)
+- Code style and quality requirements
+- How to open a pull request
+- Contributing workflow
+:::
+
+
+
+## 6. Work on the documentation website (from the terminal)
+
+The documentation website uses VuePress and Node.js. The site source is in the docs folder.
+
+::: warning Note
+This section is **only needed** if you want to **build or preview the site on your own computer**.
+If you make a **very small change** in a markdown (.md) file (for example fix a typo or add one sentence), you can:
+
+- Edit the file in VS Code.
+- Push your change and open a pull request.
+
+In that case it is **not mandatory** to install Node.js, npm, or to run `./scripts/ci.sh site`. The CI on GitHub will build the site for you and show problems if there are any.
+
+If you want to see your doc changes locally before you push (recommended for bigger edits), then follow the steps below.
+:::
+
+### 6.1 Install Node dependencies
+
+From the project root:
+
+```bash
+cd OpenMQTTGateway # only if you are not already inside
+npm install
+```
+
+This command reads package.json and installs all Node modules needed for the docs.
+
+**Check:**
+
+- The command finishes without error.
+- A node_modules folder exists in the project root.
+
+If install is slow, your internet may be the reason. If it fails, try again later or clear the npm cache with:
+
+```bash
+npm cache clean --force
+```
+
+### 6.2 Build the docs site with ci.sh
+
+If you want to check that everything still builds well after bigger doc changes, you can build the site locally.
+
+The recommended way is:
+
+```bash
+./scripts/ci.sh site --mode prod --url-prefix / --version 1.8.0
+```
+
+Important options:
+
+- `--mode dev` or `--mode prod`: development or production build (default: dev).
+- `--url-prefix PATH`: base URL path for links, e.g. `/` for root or `/dev/` for dev (default: /dev/).
+- `--version TAG`: version string written into docs/.vuepress/meta.json (default: edge).
+- `--preview`: if added, starts a local HTTPS preview server after build.
+- `--clean`: remove generated/site folder before build.
+- `--insecure-curl`: allow curl to skip TLS verification if needed.
+
+The script (scripts/ci_site.sh) will:
+
+- Check that node, npm and openssl are available.
+- Download a shared configuration file for the site.
+- Create docs/.vuepress/meta.json with site info.
+- Run npm run docs:build to build the site.
+
+**Check:**
+
+- The summary at the end says "Site Build Summary" and "Status: SUCCESS".
+- The folder docs/.vuepress/dist exists and contains HTML files.
+
+If openssl or node is missing, go back to section 2 and install them.
+
+### 6.3 Preview the docs site locally
+
+To preview the site in your browser:
+
+```bash
+./scripts/ci.sh site --mode dev --url-prefix /dev/ --version edge --preview
+```
+
+The script will start a local HTTPS server.
+
+**Check:**
+
+- The log prints a line similar to: "Preview server running at https://localhost:8443/dev/".
+- Open that URL in your browser. You should see the OpenMQTTGateway documentation.
+
+To stop the preview, go back to the terminal and press Ctrl+C.
+
+### 6.4 Work on docs with plain npm commands
+
+If you prefer not to use the ci.sh wrapper, you can work directly with npm and VuePress.
+
+From the project root:
+
+```bash
+npm run docs:dev
+```
+
+This runs VuePress in development mode with hot reload. When you change a .md file under docs, the browser reloads.
+
+For a production build:
+
+```bash
+npm run docs:build
+```
+
+**Check:**
+
+- For docs:dev, the terminal prints a local URL like http://localhost:8080. Open it in the browser and see the docs.
+- For docs:build, the folder docs/.vuepress/dist is created.
+
+If docs:build fails with an OpenSSL error on new Node versions, set:
+
+```bash
+export NODE_OPTIONS="--openssl-legacy-provider"
+```
+
+then run the command again. The ci_site.sh script already does this for you.
+
+### 6.5 Where to edit docs
+
+- All documentation pages are markdown (.md) files under docs.
+- This file itself is in docs/participate/quick_start.md.
+
+To add or edit docs:
+
+1. Open the docs folder in VS Code.
+2. Change or create markdown files.
+3. Run npm run docs:dev to check how the page looks.
+
+**Check:** after a change and a page refresh, your new text appears on the site.
+
+
+
+## 7. Typical workflows for contributors
+
+This section gives some example "day to day" flows.
+
+### 7.1 Quick firmware change with VS Code
+
+1. Open the project folder in VS Code.
+2. Choose the right environment (section 4.3).
+3. Edit code in main or lib.
+4. Build (section 4.4).
+5. Upload (section 4.5).
+6. Watch logs in Serial Monitor (section 4.6).
+
+**Check:** your change has the expected effect on the real device.
+
+### 7.2 Firmware change using terminal only
+
+1. Open a bash terminal.
+2. Go to the project root.
+3. Build firmware with:
+
+ ```bash
+ ./scripts/ci.sh build --mode dev --verbose
+ ```
+
+4. Flash firmware using PlatformIO CLI or another flash tool with the generated firmware file.
+
+**Check:** the device boots with your new firmware and behaves as expected.
+
+### 7.3 Change documentation and preview
+
+1. Edit markdown files under docs.
+2. In a terminal, run npm run docs:dev or ./scripts/ci.sh site --mode dev --preview.
+3. Open the local URL in your browser.
+
+**Check:** your text appears on the page and looks correct.
+
+
+
+## 8. Troubleshooting
+
+This list gives quick help for common problems.
+
+- **Problem:** platformio command not found.
+ - **Fix:** install it with python3 -m pip install -U platformio and open a new terminal.
+
+- **Problem:** Build fails for all environments.
+ - **Fix:** run ./scripts/ci.sh list-env to confirm you use a valid env. Check that you did not change platformio.ini or environments.ini in a wrong way.
+
+- **Problem:** Build fails with missing libraries.
+ - **Fix:** run a clean build (add --clean). If you work only with VS Code, press the trash icon or use the clean target from PlatformIO.
+
+- **Problem:** Upload fails ("Failed to connect to ESP32").
+ - **Fix:** choose the right serial port, check the cable, try holding BOOT during upload.
+
+- **Problem:** Serial output is garbled.
+ - **Fix:** set Serial Monitor baud to 115200 and confirm monitor_speed in platformio.ini is the same.
+
+- **Problem:** npm install is very slow or fails.
+ - **Fix:** check your internet connection. If needed run npm cache clean --force and try again.
+
+- **Problem:** Site build fails with an OpenSSL error.
+ - **Fix:** export NODE_OPTIONS="--openssl-legacy-provider" before running npm run docs:build, or use ./scripts/ci.sh site which already sets this.
+
+If you still have problems after these steps, you can open an issue on the project GitHub page. Include:
+
+- Your operating system (Windows or Linux, version).
+- What you tried to do.
+- The exact command you ran.
+- The error message from the end of the log.
+
+This information helps maintainers reproduce and fix the problem.
+
+
+
+## 9. Glossary (simple words)
+
+This glossary explains some words used in this guide.
+
+- **Firmware**: the program that runs inside your ESP32 or ESP8266 board.
+- **Repository (repo)**: the project folder stored on GitHub and on your computer.
+- **Commit**: a saved set of changes in Git, with a message.
+- **Branch**: a line of development in Git, like a separate copy where you work.
+- **Pull Request (PR)**: a request to merge your branch into the main project on GitHub.
+- **Environment (env)**: a PlatformIO configuration for a specific board and options.
+- **CI (Continuous Integration)**: automatic scripts that build and test the project on every change.
+- **Serial Monitor**: a window that shows text messages sent by your board over USB.
+- **MQTT**: a lightweight network protocol used to send messages between devices.
+- **VuePress**: a static site generator used to build this documentation.
+
+If any word in this guide is not clear, you can search it on the web or ask in the project community. Many people had the same question before you.
+
+
+
+## 10. External links and further reading
+
+Here is a list of useful links related to tools used in this project:
+
+- **OpenMQTTGateway project**:
+- **PlatformIO main site**:
+- **PlatformIO installation for VS Code**:
+- **PlatformIO documentation**:
+- **Visual Studio Code documentation**:
+- **Git official site**:
+- **Pro Git book (free)**:
+- **GitHub getting started**:
+- **Node.js documentation**:
+- **npm documentation**:
+- **VuePress documentation** (v1, similar to what this project uses):
+- **MQTT introduction (HiveMQ)**:
+
+You do **not** need to read all of them now. Keep this list as a bookmark and come back when you are curious or stuck.
+
+
+## 11. Final words and friendly advice
+
+Contributing to an open source project is a journey. The first steps (install tools, learn Git, learn PlatformIO) can feel slow. This is normal.
+
+Some final tips:
+
+- Change one thing at a time and test often.
+- Keep your changes small; they are easier to review.
+- Write clear commit messages.
+- When something breaks, read the last 10–20 lines of the log first.
+- Do not be afraid to ask questions; everyone started as a beginner.
+
+You are now ready to work on both firmware and documentation for OpenMQTTGateway. Take your time, follow the checks after each step, and you will build confidence with the toolchain and the project. Step by step, you will become faster and more comfortable.
+
+
+If you are new and want to "play" a bit before you change real logic, here are some safe exercises:
+
+1. **Practice the build chain only.**
+ - Clone the repo, open it in VS Code, select `esp32dev-all-test`, build, and upload to your board.
+ - Check that you can see logs in the Serial Monitor.
+2. **Make a tiny log change.**
+ - Find a `LOG` or `Serial` message in a gateway or sensor file under `main`.
+ - Change the text slightly (for example add a word), rebuild, upload, and verify you see the new message.
+3. **Edit a small doc page.**
+ - Fix a typo or add one sentence of clarification in a markdown file under `docs`.
+ - Run `./scripts/ci.sh site --mode prod --preview` and confirm your change appears in the browser.
+4. **Run QA locally.**
+ - Run `./scripts/ci.sh qa --check`. If there are issues, run `./scripts/ci.sh qa --fix` and see how files are changed.
+5. **Open a small PR.**
+ - For example, only the doc change or a very small code improvement. This lets you learn the review process without much stress.
+
+These small steps build confidence. After that you can move to bigger things: adding new sensors, improving MQTT payloads, or extending the web documentation.
diff --git a/docs/participate/support.md b/docs/participate/support.md
index 16c718b8f9..0e808a4152 100644
--- a/docs/participate/support.md
+++ b/docs/participate/support.md
@@ -1,15 +1,22 @@
# Supporting the project
-If you like the project and/or used it please consider supporting it! It can be done in different ways:
-* Purchase the [Theengs mobile application](https://app.theengs.io)
-* Purchase the [Theengs plug](https://shop.theengs.io)
-* Helping other users in the [community](https://community.openmqttgateway.com)
-* [Contribute](development) to the [code](https://github.com/1technophile/OpenMQTTGateway) or the [documentation](https://docs.openmqttgateway.com)
-* Buy devices, boards or parts from the [compatible web site](https://compatible.openmqttgateway.com), the devices and parts linked use affiliated links.
-* Donate or sponsor the project [developers](https://github.com/1technophile/OpenMQTTGateway/graphs/contributors)
-* Make a video or a blog article about what you have done with [OpenMQTTGateway](https://docs.openmqttgateway.com) and share it.
+If you like the project, you can help in different ways. Choose what fits you best.
-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.
+## Give time and knowledge
+- Help other users in the [community](https://community.openmqttgateway.com).
+- Share logs, payload samples, or how-to posts that unblock others.
+
+## Contribute code or docs
+- Follow the [Development contributions guide](./development.md) to open a PR.
+- Improve docs or examples if you spot unclear steps.
+
+## Financial support
+- Purchase the [Theengs mobile application](https://app.theengs.io) or the [Theengs plug](https://shop.theengs.io).
+- Buy devices or parts via the [compatible web site](https://compatible.openmqttgateway.com) (affiliate links help the project).
+- Sponsor the project [developers](https://github.com/1technophile/OpenMQTTGateway/graphs/contributors).
+- Make a video or blog article about what you built with [OpenMQTTGateway](https://docs.openmqttgateway.com) and share it.
+
+Support open-source development through sponsorship and gain exclusive access to our private forum. Your questions, issues, and feature requests receive priority attention, plus you'll see the roadmap early.
diff --git a/docs/prerequisites/board.md b/docs/prerequisites/board.md
index 3ece66cbae..71cec487ab 100644
--- a/docs/prerequisites/board.md
+++ b/docs/prerequisites/board.md
@@ -1,3 +1,7 @@
+---
+pageClass: table-generated-page
+---
+
# Boards
OpenMQTTGateway is not closed to one board or type of board, by using the power of the Arduino framework and libraries that are cross compatibles it let you many choice of hardware, from an ESP8266 to an ESP32.
@@ -43,4 +47,10 @@ The plug is available in North America only, other regions are planned.
Choosing your board depends heavily on the technologies you want to use with it.
To have a good overview of the compatibilities per board you can refer to the compatible modules attributes of each [board](https://compatible.openmqttgateway.com/index.php/boards/).
-The choice between these boards will depend on your knowledge and your requirements in terms of reliability, situation, modules wanted and devices you already have. The table below present those (auto-generated)
+The choice between these boards will depend on your knowledge and your requirements in terms of reliability, situation, modules wanted and devices you already have. Use the table below to explore the latest environments.
+
+
+
diff --git a/docs/prerequisites/boards/.gitignore b/docs/prerequisites/boards/.gitignore
deleted file mode 100644
index 86d0cb2726..0000000000
--- a/docs/prerequisites/boards/.gitignore
+++ /dev/null
@@ -1,4 +0,0 @@
-# Ignore everything in this directory
-*
-# Except this file
-!.gitignore
\ No newline at end of file
diff --git a/docs/setitup/rf.md b/docs/setitup/rf.md
index e6f3c7bb53..0c44fdb594 100644
--- a/docs/setitup/rf.md
+++ b/docs/setitup/rf.md
@@ -51,8 +51,22 @@ With SRX882S receiver connect the CS pin to 3.3V
|ESP8266|D2/**D3**/D1/D8|**RX**/D2|D5|**3V3**|D7|D6|D8|GND
|ESP32|**D27**|D12|D18|**3V3**|D23|D19|D5|GND
-To use the CC1101 module, `ZradioCC1101` must be uncomment in the `User_config.h` or added to the `build_flags`.
-More information about the [CC1101 wiring](https://github.com/LSatan/SmartRC-CC1101-Driver-Lib#wiring). ( Please note that with OMG we are recommending CC1101 GDO2 to be connected to ESP32 D27 and GDO0 to be connected to D12, this is different than the LSatan diagram. This is due to the ESP32 using D2 as part of the boot process. )
+To use the CC1101 module, `ZradioCC1101` must be uncomment in the `User_config.h` or added to the `build_flags`.
+
+More information about the [CC1101 wiring](https://github.com/LSatan/SmartRC-CC1101-Driver-Lib#wiring).
+
+
+:::tip Please note that with OMG we are recommending CC1101 GDO2 to be connected to ESP32 D27 and GDO0 to be connected to D12, this is different than the LSatan diagram. This is due to the ESP32 using D2 as part of the boot process.
+
+If you want to use custom SPI pins for the CC1101 module, you can define the following variables in your `User_config.h` or as `build_flags` in `platformio.ini`:
+ - `RF_CC1101_SCK`: SPI clock pin (SCK)
+ - `RF_CC1101_SCK`: SPI clock pin (SCK)
+ - `RF_CC1101_MISO`: SPI MISO pin (Master In Slave Out)
+ - `RF_CC1101_MOSI`: SPI MOSI pin (Master Out Slave In)
+ - `RF_CC1101_CS`: SPI chip select pin (CSN)
+
+When **all** these variables are defined, OpenMQTTGateway will use your custom pinout for the CC1101 connection. This is useful if your board does not use the default pins or if you want to avoid conflicts with other devices.
+:::
## ESP32 Hardware setup
@@ -73,3 +87,5 @@ The RF processing can be achieved after the modification by either RF, RF2 or Pi
## WIFI RF GATEWAY Hardware setup
This board doesn't require any hardware modifications.
+
+
diff --git a/docs/up.html b/docs/up.html
new file mode 100644
index 0000000000..b88b0c73e6
--- /dev/null
+++ b/docs/up.html
@@ -0,0 +1,135 @@
+
+
+
+
+
+ Squeezelite-ESP32 installer
+
+
+
+
+
+
+
+
+
+
Squeezelite-ESP32 installer
+
This is a prototype and not up-to-date. For latest installations, see the Squeezelite Web Installer.
+
Select your product
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/upload/ReadMe.md b/docs/upload/ReadMe.md
new file mode 100644
index 0000000000..7ec95e217b
--- /dev/null
+++ b/docs/upload/ReadMe.md
@@ -0,0 +1,79 @@
+# 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.
+
+
+
+
+
+## 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.
diff --git a/docs/upload/board-selector.md b/docs/upload/board-selector.md
new file mode 100644
index 0000000000..3c498cbaa8
--- /dev/null
+++ b/docs/upload/board-selector.md
@@ -0,0 +1,10 @@
+---
+pageClass: table-generated-page
+---
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/upload/web-install.md b/docs/upload/web-install.md
index aeb494f6c4..3547da575e 100644
--- a/docs/upload/web-install.md
+++ b/docs/upload/web-install.md
@@ -2,7 +2,14 @@
pageClass: table-generated-page
---
-# (Option 1) Upload from the web
+## 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).
+
+
+
::: 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/).
@@ -15,16 +22,8 @@ The correct driver to then select in the popup of this web install is
`/dev/cu.wchusbserialXXXXXXXXXXX`
:::
-You can upload the firmware to your ESP device directly from here.
-1. Plug in your ESP to a USB port.
-2. Select the firmware in the box below.
-3. Click the install button and choose the port that the ESP is connected to.
-4. Wait until the process is complete.
-5. Once completed you can configure your [WiFi and MQTT credentials](portal.md)
-
-Upload powered by [ESP Web Tools](https://esphome.github.io/esp-web-tools/)
## 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.
@@ -33,5 +32,4 @@ Support open-source development through sponsorship and gain exclusive access to
-## Environments characteristics
-The auto-generated table below describes the libraries and the modules of each board configuration.
+
diff --git a/docsgen/boards-info.js b/docsgen/boards-info.js
new file mode 100644
index 0000000000..14343d970b
--- /dev/null
+++ b/docsgen/boards-info.js
@@ -0,0 +1,232 @@
+'use strict';
+/**
+ * Universal parser for PlatformIO dependencies.
+ * Formats URLs and registry strings into a consistent "Registry Style":
+ * Name @ Version (provider:user)
+ */
+function smartFormat(dep) {
+ if (!dep) return "";
+ if (typeof dep !== 'string') return dep;
+
+ const cleanDep = dep.trim();
+
+ // Configuration for Git providers with specific regex for archives, releases, and git repos
+ const providers = [
+ {
+ id: 'gh',
+ name: 'github',
+ // Captures: 1. Author, 2. Repo, 3. Version from path (releases), 4. Version from filename/branch
+ regex: /github\.com\/([^/]+)\/([^/.]+)(?:\/(?:archive|releases\/download\/([^/]+)|tree)\/)?([^/]+)?(?:\.zip|\.git)?$/i
+ },
+ {
+ id: 'gl',
+ name: 'gitlab',
+ // Captures: 1. Author, 2. Repo, 3. Version from path, 4. Version from filename
+ regex: /gitlab\.com\/([^/]+)\/([^/.]+)(?:\/(?:-\/)?(?:archive|releases)\/([^/]+))?\/([^/]+)?(?:\.zip|\.git)?$/i
+ },
+ {
+ id: 'bb',
+ name: 'bitbucket',
+ // Captures: 1. Author, 2. Repo, 3. Version from path, 4. Version from filename
+ regex: /bitbucket\.org\/([^/]+)\/([^/.]+)(?:\/(?:get|downloads)\/([^/]+))?\/([^/]+)?(?:\.zip|\.git)?$/i
+ }
+ ];
+
+ // 1. Try to match against Git providers (GitHub, GitLab, Bitbucket)
+ for (const p of providers) {
+ const match = cleanDep.match(p.regex);
+ if (match) {
+ let [_, author, repo, pathVer, fileVer] = match;
+
+ // Prioritize version from path (typical in releases) over filename
+ let version = pathVer || fileVer || "latest";
+
+ // Clean up version string: remove extensions and 'v' prefix
+ version = version
+ .replace(/\.(zip|git|tar\.gz)$/i, '')
+ .replace(/^v(\d)/i, '$1'); // Removes 'v' only if followed by a number
+
+ // Avoid redundancy if the version string is identical to the repo name
+ if (version.toLowerCase() === repo.toLowerCase()) {
+ version = "latest";
+ }
+
+ return `${repo} @ ${version} (${p.id}:${author})`;
+ }
+ }
+
+ // 2. Fallback for Standard PlatformIO Registry format (e.g., owner/lib @ ^1.0.0)
+ if (cleanDep.includes('/') || cleanDep.includes('@')) {
+ const parts = cleanDep.split('@');
+ const fullName = parts[0].trim(); // Includes owner/name
+
+ // Clean up version if present
+ let version = "latest";
+ if (parts[1]) {
+ version = parts[1].trim().replace(/^[\^~=]/, '');
+ }
+
+ // Separate owner and library name for consistent formatting
+ if (fullName.includes('/')) {
+ const [owner, libName] = fullName.split('/');
+ return `${libName.trim()} @ ${version} (pio:${owner.trim()})`;
+ }
+
+ return `${fullName} @ ${version}`;
+ }
+
+ // 3. Return original string if no patterns match
+ return cleanDep;
+}
+
+function rowConfigFromPlatformIO() {
+ const { execSync } = require('child_process');
+
+ try {
+ const jsonConfig = execSync('pio project config --json-output').toString();
+ const config = JSON.parse(jsonConfig);
+ return config;
+ } catch (error) {
+ console.error("Assicurati che PlatformIO Core sia installato e nel PATH");
+ throw error;
+ }
+}
+
+function cleanValue(v) {
+ if (typeof v !== 'string') return v;
+ return v
+ .replace(/{/g, '')
+ .replace(/}/g, '')
+ .replace(/\$/g, '')
+ .replace(/env:/g, '')
+ .replace(/'/g, '')
+ .replace(/-D/g, '');
+}
+
+function convertJsonToSections(jsonConfig) {
+ const sections = {};
+ jsonConfig.forEach(([sectionName, configArray]) => {
+ sections[sectionName] = {};
+ configArray.forEach(([key, value]) => {
+ sections[sectionName][key] = value;
+ });
+ });
+ return sections;
+}
+
+function cleanLibraries(raw) {
+ if (!raw) return [];
+ if (typeof raw === 'string') {
+ raw = raw.split(',')
+ }
+ return raw.map((dep) => smartFormat(dep));
+}
+
+function extractModulesFromFlags(flags) {
+ if (!flags) return [];
+ let flagArray = [];
+ if (Array.isArray(flags)) {
+ flagArray = flags;
+ } else if (typeof flags === 'string') {
+ flagArray = flags.split(',').map(s => s.trim()).filter(s => s.length > 0);
+ } else {
+ return [];
+ }
+ const modules = [];
+ flagArray.forEach((flag) => {
+ // Match -DZmoduleName, allowing surrounding quotes
+ const match = flag.match(/^['" ]*-DZ([^=]+)/);
+ if (match) {
+ const moduleName = match[1];
+ // Additional constraint: must contain 'gateway', 'sensor', or 'actuator'
+ if (moduleName.includes('gateway') || moduleName.includes('sensor') || moduleName.includes('actuator')) {
+ modules.push(moduleName);
+ }
+ }
+ //if MQTT_BROKER_MODE = true then modules.push("MQTT Broker Mode");
+ const brokerMatch = flag.match(/^['" ]*-DMQTT_BROKER_MODE(?:=([^'"\s]+))?/);
+ if (brokerMatch) {
+ const value = brokerMatch[1];
+ // Add only if not explicitly set to false (case insensitive)
+ if (!value || value.toLowerCase() !== 'false') {
+ modules.push("MQTT Broker Mode");
+ }
+ }
+
+ });
+ return modules;
+}
+
+function collectBoardsInformations(sections, { includeTests = false } = {}) {
+ const rows = [];
+
+ Object.entries(sections).forEach(([section, items]) => {
+ if (!section.includes('env:')) return;
+ if (!includeTests && section.includes('-test')) return;
+
+ const env = section.replace('env:', '');
+ let uc = '';
+ let hardware = '';
+ let description = '';
+ let modules = [];
+ let platform = '';
+ let partitions = '';
+ let libraries = [];
+ let options = [];
+ let customImg = '';
+
+ Object.entries(items).forEach(([k, raw]) => {
+ const v = cleanValue(raw);
+
+
+ if (k === 'board') uc = v;
+ if (k === 'platform') platform = smartFormat(v);
+ if (k === 'board_build.partitions') partitions = v;
+ if (k === 'custom_description') description = v;
+ if (k === 'custom_hardware') hardware = v;
+ if (k === 'custom_img') customImg = v;
+
+ if (k === 'lib_deps') {
+ libraries = cleanLibraries(raw);
+ }
+
+ if (k === 'build_flags') {
+ options = v;
+ modules = extractModulesFromFlags(v);
+ }
+ });
+
+ rows.push({
+ Environment: env,
+ uC: uc,
+ Hardware: hardware,
+ Description: description,
+ Modules: modules,
+ Platform: platform,
+ Partitions: partitions,
+ Libraries: libraries,
+ Options: options,
+ CustomImg: customImg
+ });
+ });
+
+ rows.sort((a, b) => a.Environment.localeCompare(b.Environment, 'en', { sensitivity: 'base' }));
+ return rows;
+}
+
+function loadBoardsInfo(options = {}) {
+ const { includeTests = false } = options;
+ const config = rowConfigFromPlatformIO();
+ const sections = convertJsonToSections(config);
+ return collectBoardsInformations(sections, { includeTests });
+}
+
+function ensureDir(dir) {
+ const fs = require('fs');
+ if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+module.exports = {
+ loadBoardsInfo,
+ ensureDir
+};
diff --git a/docsgen/common_wu.js b/docsgen/common_wu.js
new file mode 100644
index 0000000000..bccc3078d5
--- /dev/null
+++ b/docsgen/common_wu.js
@@ -0,0 +1,77 @@
+// Common templates and constants for web installer manifest generation
+// Used by: scripts/gen_wu.js
+
+const mf_temp32 = (vars) => `{
+ "name": "OpenMQTTGateway",
+ "new_install_prompt_erase": true,
+ "builds": [
+ {
+ "chipFamily": "ESP32",
+ "improv": false,
+ "parts": [
+ { "path": "${vars.cp}${vars.bl}", "offset": 4096 },
+ { "path": "${vars.cp}${vars.part}", "offset": 32768 },
+ { "path": "${vars.cp}${vars.boot}", "offset": 57344 },
+ { "path": "${vars.cp}${vars.bin}", "offset": 65536 }
+ ]
+ }
+ ]
+}`;
+
+const mf_temp32c3 = (vars) => `{
+ "name": "OpenMQTTGateway",
+ "new_install_prompt_erase": true,
+ "builds": [
+ {
+ "chipFamily": "ESP32-C3",
+ "improv": false,
+ "parts": [
+ { "path": "${vars.cp}${vars.bl}", "offset": 0 },
+ { "path": "${vars.cp}${vars.part}", "offset": 32768 },
+ { "path": "${vars.cp}${vars.boot}", "offset": 57344 },
+ { "path": "${vars.cp}${vars.bin}", "offset": 65536 }
+ ]
+ }
+ ]
+}`;
+
+const mf_temp32s3 = (vars) => `{
+ "name": "OpenMQTTGateway",
+ "new_install_prompt_erase": true,
+ "builds": [
+ {
+ "chipFamily": "ESP32-S3",
+ "improv": false,
+ "parts": [
+ { "path": "${vars.cp}${vars.bl}", "offset": 0 },
+ { "path": "${vars.cp}${vars.part}", "offset": 32768 },
+ { "path": "${vars.cp}${vars.boot}", "offset": 57344 },
+ { "path": "${vars.cp}${vars.bin}", "offset": 65536 }
+ ]
+ }
+ ]
+}`;
+
+const mf_temp8266 = (vars) => `{
+ "name": "OpenMQTTGateway",
+ "new_install_prompt_erase": true,
+ "builds": [
+ {
+ "chipFamily": "ESP8266",
+ "parts": [{ "path": "${vars.cp}${vars.bin}", "offset": 0 }]
+ }
+ ]
+}`;
+
+
+const cors_proxy = ''; // 'https://cors.bridged.cc/'
+const esp32_boot = 'https://github.com/espressif/arduino-esp32/raw/2.0.7/tools/partitions/boot_app0.bin';
+
+module.exports = {
+ mf_temp32,
+ mf_temp32c3,
+ mf_temp32s3,
+ mf_temp8266,
+ cors_proxy,
+ esp32_boot
+};
diff --git a/docsgen/gen_wu.js b/docsgen/gen_wu.js
new file mode 100644
index 0000000000..5c5ed63071
--- /dev/null
+++ b/docsgen/gen_wu.js
@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+
+// Creates web installer manifests for ESP Web Tools firmware installation
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const { loadBoardsInfo, ensureDir } = require('./boards-info');
+
+const {
+ mf_temp32,
+ mf_temp32c3,
+ mf_temp32s3,
+ mf_temp8266,
+ cors_proxy,
+ esp32_boot
+} = require('./common_wu.js');
+
+// ============================================================================
+// Directory Configuration
+// ============================================================================
+
+// Base directories
+const ROOT_DIR = path.join(__dirname, '..');
+const DOCS_DIR = path.join(ROOT_DIR, 'docs');
+const VUEPRESS_DIR = path.join(DOCS_DIR, '.vuepress');
+const PUBLIC_DIR = path.join(VUEPRESS_DIR, 'public');
+const COMPONENTS_DIR = path.join(VUEPRESS_DIR, 'components');
+const ARTIFACTS_DIR = path.join(ROOT_DIR, 'generated', 'artifacts');
+
+// Feature-specific directories
+const FIRMWARE_SRC_DIR = path.join(ARTIFACTS_DIR, 'firmware_build');
+const FIRMWARE_BUILD_DIR = path.join(PUBLIC_DIR, 'firmware_build');
+const BOARDS_INFO_FILE = path.join(PUBLIC_DIR, 'boards-info.json');
+
+// Configuration files
+const DEFAULTS_CONFIG_PATH = path.join(VUEPRESS_DIR, 'defaults.json');
+const META_CONFIG_PATH = path.join(VUEPRESS_DIR, 'meta.json');
+
+
+
+let meta = require(DEFAULTS_CONFIG_PATH);
+try {
+ const meta_overload = require(META_CONFIG_PATH);
+ meta = { ...meta, ...meta_overload };
+} catch (e) {
+ console.warn('meta.json not found or not valid. Using default configuration.');
+}
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const dev = args.includes('--dev') || meta.mode === 'dev';
+const repo = meta.repo || '1technophile/OpenMQTTGateway';
+const firmwareManifestFolder = dev ? `/dev/firmware_build/` : `/firmware_build/`;
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function ensureFirmwareArtifacts() {
+ if (!fs.existsSync(FIRMWARE_SRC_DIR)) {
+ throw new Error(`Missing firmware artifacts in ${FIRMWARE_SRC_DIR}. Run "ci.sh build ..." first to populate this folder.`);
+ }
+ console.log(`Found firmware artifacts in: ${FIRMWARE_SRC_DIR}`);
+}
+// Replace version_tag in template and write to destination
+function renderVersionTemplate(templatePath, outputPath, version) {
+ if (!fs.existsSync(templatePath)) {
+ throw new Error(`Template not found: ${templatePath}`);
+ }
+ const content = fs.readFileSync(templatePath, 'utf8').replace(/version_tag/g, version);
+ fs.writeFileSync(outputPath, content);
+ console.log(`Generated version file from template: ${outputPath}`);
+}
+
+/**
+ * Download file from URL
+ */
+function downloadFile(url) {
+ return new Promise((resolve, reject) => {
+ https.get(url, (response) => {
+ // Handle redirects
+ if (response.statusCode === 302 || response.statusCode === 301) {
+ return downloadFile(response.headers.location).then(resolve).catch(reject);
+ }
+ if (response.statusCode !== 200) {
+ return reject(new Error(`Failed to download: ${response.statusCode}`));
+ }
+ const chunks = [];
+ response.on('data', (chunk) => chunks.push(chunk));
+ response.on('end', () => resolve(Buffer.concat(chunks)));
+ response.on('error', reject);
+ }).on('error', reject);
+ });
+}
+
+/**
+ * Fetch JSON from URL
+ */
+function fetchJson(url) {
+ return new Promise((resolve, reject) => {
+ https.get(url, { headers: { 'User-Agent': 'OpenMQTTGateway-Script' } }, (response) => {
+ if (response.statusCode !== 200) {
+ return reject(new Error(`Failed to fetch: ${response.statusCode}`));
+ }
+ let data = '';
+ response.on('data', (chunk) => data += chunk);
+ response.on('end', () => {
+ try {
+ resolve(JSON.parse(data));
+ } catch (e) {
+ reject(e);
+ }
+ });
+ response.on('error', reject);
+ }).on('error', reject);
+ });
+}
+
+/**
+ * Download and save asset
+ */
+async function downloadAsset(asset, destPath) {
+ const buffer = await downloadFile(asset.browser_download_url);
+ const filename = asset.browser_download_url.split('/').pop();
+ fs.writeFileSync(path.join(destPath, filename), buffer);
+ console.log(`Downloaded asset: ${filename} to ${destPath}`);
+}
+
+/**
+ * Create manifest and Vue option for a firmware
+ * Partition path uses filename only (matches Python; split is redundant but harmless)
+ */
+function createManifest(name, templateFn) {
+ const fw = name.split('-firmware')[0];
+ const man_file = fw + '.manifest.json';
+ const fwp_name = fw + '-partitions.bin';
+ const fwb_name = fw + '-bootloader.bin';
+
+ // Use filename to mirror Python behavior (no directories present today)
+ const partPath = fwp_name.split('/').pop();
+
+ const mani_str = templateFn({
+ cp: cors_proxy,
+ part: firmwareManifestFolder + partPath,
+ bin: firmwareManifestFolder + name,
+ bl: firmwareManifestFolder + fwb_name,
+ boot: firmwareManifestFolder + esp32_boot.split('/').pop()
+ });
+
+ const outPath = path.join(FIRMWARE_BUILD_DIR, man_file);
+ fs.writeFileSync(outPath, mani_str);
+ console.log(`Created manifest for ${fw}: ${outPath}`);
+}
+
+/**
+ * Create manifest for ESP8266
+ * Python adds manif_folder when writing to file, not in return
+ */
+function createManifest8266(name) {
+ const fw = name.split('-firmware')[0];
+ const man_file = fw + '.manifest.json';
+
+ const mani_str = mf_temp8266({
+ cp: cors_proxy,
+ bin: firmwareManifestFolder + name
+ });
+
+ const outPath = path.join(FIRMWARE_BUILD_DIR, man_file);
+ fs.writeFileSync(outPath, mani_str);
+ console.log(`Created manifest for ${fw} (ESP8266): ${outPath}`);
+
+}
+
+/**
+ * Device type matchers
+ */
+const ESP32_NAMES = ['esp32', 'ttgo', 'heltec', 'thingpulse', 'theengs', 'lilygo', 'shelly', 'tinypico'];
+const ESP8266_NAMES = ['nodemcu', 'sonoff', 'rf-wifi-gateway', 'manual-wifi-test', 'rfbridge'];
+
+const deviceMatchers = {
+ esp32: (name) => name.includes('firmware.bin') &&
+ !name.includes('esp32c3') && !name.includes('esp32s3') &&
+ ESP32_NAMES.some(key => name.includes(key)),
+
+ esp32c3: (name) => name.includes('firmware.bin') && name.includes('esp32c3'),
+
+ esp32s3: (name) => name.includes('firmware.bin') && name.includes('esp32s3'),
+
+ esp8266: (name) => name.includes('firmware.bin') &&
+ ESP8266_NAMES.some(key => name.includes(key))
+};
+
+/**
+ * Setup dev environment
+ */
+async function setupDevEnvironment() {
+ console.log('DEV mode: preparing web upload files...');
+ ensureFirmwareArtifacts();
+ // Generate OTA latest version definition from template
+ const tpl = path.join(__dirname, 'latest_version_dev.json.tpl');
+ renderVersionTemplate(tpl, path.join(FIRMWARE_BUILD_DIR, 'latest_version_dev.json'), meta.version);
+
+ // Copy the binaries from FIRMWARE_SRC_DIR to FIRMWARE_BUILD_DIR
+ const files = fs.readdirSync(FIRMWARE_SRC_DIR);
+ let copied = 0;
+ for (const name of files) {
+ if (name.includes('.bin')) {
+ fs.copyFileSync(
+ path.join(FIRMWARE_SRC_DIR, name),
+ path.join(FIRMWARE_BUILD_DIR, name)
+ );
+ copied++;
+ console.log(`Copied binary: ${name}`);
+ }
+ }
+ console.log(`Copied ${copied} firmware binaries to ${FIRMWARE_BUILD_DIR}`);
+}
+
+/**
+ * Setup release environment
+ */
+async function setupReleaseEnvironment() {
+ console.log('RELEASE mode: downloading and preparing web upload files...');
+
+ // Generate OTA latest version definition from template
+ const tpl = path.join(__dirname, 'latest_version.json.tpl');
+ renderVersionTemplate(tpl, path.join(FIRMWARE_BUILD_DIR, 'latest_version.json'), meta.version);
+
+ const releaseUrl = `https://api.github.com/repos/${repo}/releases/latest`;
+ console.log(`Fetching latest release info from: ${releaseUrl}`);
+ const rel_data = await fetchJson(releaseUrl);
+
+ if (!rel_data.assets) {
+ console.error('No assets found in the latest release!');
+ process.exit(1);
+ }
+
+ // Download all assets
+ let downloaded = 0;
+ for (const asset of rel_data.assets) {
+ const name = asset.name;
+ if (name.includes('firmware.bin') ||
+ name.includes('partitions.bin') ||
+ name.includes('bootloader.bin')) {
+ await downloadAsset(asset, FIRMWARE_BUILD_DIR);
+ downloaded++;
+ }
+ }
+ console.log(`Downloaded ${downloaded} firmware assets to ${FIRMWARE_BUILD_DIR}`);
+}
+
+/**
+ * Process firmware files and generate manifests
+ */
+function processFirmwareFiles(files) {
+ let manifestCount = 0;
+ for (const name of files) {
+ if (deviceMatchers.esp32(name)) {
+ createManifest(name, mf_temp32);
+ manifestCount++;
+ }
+ if (deviceMatchers.esp32c3(name)) {
+ createManifest(name, mf_temp32c3);
+ manifestCount++;
+ }
+ if (deviceMatchers.esp32s3(name)) {
+ createManifest(name, mf_temp32s3);
+ manifestCount++;
+ }
+ if (deviceMatchers.esp8266(name)) {
+ createManifest8266(name);
+ manifestCount++;
+ }
+ }
+ console.log(`Generated ${manifestCount} manifest files in ${FIRMWARE_BUILD_DIR}`);
+
+}
+
+/**
+ * Main execution function
+ */
+// ===================== OpenMQTTGateway Web Uploader Manifest Generator =====================
+// ===================== MAIN SCRIPT STARTS HERE =====================
+async function main() {
+ console.log('================================================================================');
+ console.log(' OpenMQTTGateway Web Uploader Manifest Generator - START');
+ console.log('================================================================================');
+
+ // === [1] Load and generate boards info ===
+ console.log('\n[1/4] Generating boards-info.json ...');
+ const boardsInfo = loadBoardsInfo({ verbose: 0 });
+ const boardsJson = boardsInfo.map((row) => ({
+ environment: row.Environment,
+ hardware: row.Hardware,
+ description: row.Description,
+ microcontroller: row.uC,
+ modules: row.Modules.filter(Boolean),
+ platform: row.Platform,
+ partitions: row.Partitions,
+ libraries: row.Libraries.filter(Boolean),
+ options: row.Options,
+ customImg: row.CustomImg
+ }));
+ ensureDir(path.dirname(BOARDS_INFO_FILE));
+ fs.writeFileSync(BOARDS_INFO_FILE, JSON.stringify(boardsJson, null, 2), 'utf8');
+ console.log(`Generated boards-info.json with ${boardsJson.length} boards: ${BOARDS_INFO_FILE}`);
+
+ // === [2] Ensure output directory ===
+ console.log('\n[2/4] Ensuring output directory ...');
+ ensureDir(FIRMWARE_BUILD_DIR);
+ console.log(`Ensured output directory exists: ${FIRMWARE_BUILD_DIR}`);
+
+ // === [3] Setup environment (dev or release) ===
+ console.log('\n[3/4] Preparing firmware files ...');
+ try {
+ if (dev) {
+ await setupDevEnvironment();
+ } else {
+ await setupReleaseEnvironment();
+ }
+ } catch (error) {
+ console.error(`Error setting up environment: ${error.message}`);
+ process.exit(1);
+ }
+
+ // === [4] Download boot binary and generate manifests ===
+ console.log('\n[4/4] Downloading boot binary and generating manifests ...');
+ console.log(`Downloading boot binary: ${esp32_boot}`);
+ const boot_bin = await downloadFile(esp32_boot);
+ const boot_filename = esp32_boot.split('/').pop();
+ fs.writeFileSync(path.join(FIRMWARE_BUILD_DIR, boot_filename), boot_bin);
+ console.log(`Saved boot binary as: ${boot_filename}`);
+
+ const files = fs.readdirSync(FIRMWARE_BUILD_DIR).sort();
+ console.log(`Processing firmware files in ${FIRMWARE_BUILD_DIR}...`);
+ processFirmwareFiles(files);
+
+ console.log('\n================================================================================');
+ console.log(' OpenMQTTGateway Web Uploader Manifest Generator - END');
+ console.log('================================================================================');
+}
+// ===================== MAIN SCRIPT ENDS HERE =====================
+
+// Run main function
+main().catch(error => {
+ console.error('Fatal error:', error);
+ process.exit(1);
+});
diff --git a/scripts/latest_version.json b/docsgen/latest_version.json.tpl
similarity index 100%
rename from scripts/latest_version.json
rename to docsgen/latest_version.json.tpl
diff --git a/scripts/latest_version_dev.json b/docsgen/latest_version_dev.json.tpl
similarity index 100%
rename from scripts/latest_version_dev.json
rename to docsgen/latest_version_dev.json.tpl
diff --git a/docsgen/up.html b/docsgen/up.html
new file mode 100644
index 0000000000..b88b0c73e6
--- /dev/null
+++ b/docsgen/up.html
@@ -0,0 +1,135 @@
+
+
+
+
+
+ Squeezelite-ESP32 installer
+
+
+
+
+
+
+
+
+
+
Squeezelite-ESP32 installer
+
This is a prototype and not up-to-date. For latest installations, see the Squeezelite Web Installer.
+