Merge remote-tracking branch 'upstream/main'

Author: softhack007

.coderabbit.yaml

@@ -0,0 +1,31 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+
+language: en-US
+
+reviews:
+  # generic review setting, see https://docs.coderabbit.ai/reference/configuration#reference
+  # auto_apply_labels: true
+  # abort_on_close: false
+  high_level_summary: true
+  review_status: true
+  collapse_walkthrough: false
+  poem: true
+  sequence_diagrams: false
+  slop_detection:
+    label: needs_rework
+  auto_review:
+    enabled: true
+    ignore_title_keywords:
+      - WIP
+
+  finishing_touches:
+    # Docstrings | Options for generating Docstrings for your PRs/MRs.
+    docstrings:
+      # Docstrings | Allow CodeRabbit to generate docstrings for PRs/MRs.
+      # default: true - disabled in WLED: has caused confusion in the past
+      enabled: false
+    unit_tests:
+      # default: true - disabled in WLED: we don't have a unit test framework, this option just confuses contributors
+      enabled: false
+    simplify:
+      enabled: true

AGENTS.md

@@ -0,0 +1,168 @@
+# AGENTS.md
+
+## Repository Overview
+
+This is the official user documentation for [WLED](https://github.com/wled/WLED), published at [kno.wled.ge](https://kno.wled.ge) using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
+
+All documentation is written in **English**. Contributors improve docs by editing Markdown files and submitting pull requests.
+
+[WLED](https://github.com/wled/WLED) is an open source firmware - written mainly in C++ using platformIO and node.js tooling - for ESP32/ESP8266 microcontrollers controlling addressable LEDs, with a web UI and various networking APIs for custom integrations. WLED is licensed under EUPL-1.2.
+
+---
+
+## Repository Structure
+
+```
+WLED-Docs/
+├── docs/                   # All documentation source files
+│   ├── index.md            # Landing page
+│   ├── assets/             # Images, stylesheets, JS, MkDocs overrides
+│   │   └── images/content/ # Preferred location for inline images
+│   ├── basics/             # Getting started, installation, compatibility, FAQ
+│   ├── features/           # WLED feature pages (effects, segments, presets, etc.)
+│   ├── interfaces/         # API and protocol docs (JSON API, MQTT, E1.31, etc.)
+│   ├── advanced/           # Wiring, compilation, custom features, etc.
+│   └── about/              # Contributors, roadmap, privacy policy
+├── mkdocs.yml              # Site config, navigation, theme settings
+└── README.md               # Contributor guide
+```
+
+---
+
+## Page Conventions
+
+Every documentation page must begin with a YAML front matter block:
+
+```yaml
+---
+title: Page Title
+hide:
+  # - navigation
+  # - toc
+---
+```
+
+- `title` is required and must match the nav entry in `mkdocs.yml`.
+- `navigation` and `toc` are commented out by default (i.e., both are shown). Only hide them when there is a clear design reason (e.g., the landing page hides both).
+
+---
+
+## Navigation Registration
+
+Every new page **must** also be registered in the `nav:` section of `mkdocs.yml`. Pages not listed there will not appear in the site navigation.
+
+```yaml
+nav:
+  - Section Name:
+    - Page Title: section/filename.md
+```
+
+Indentation in `mkdocs.yml` is significant.
+
+---
+
+## Markdown Style
+
+- **Headings**: Use `##` for top-level sections within a page (`#` is optional, as it may conflict with the page title). Use `###` and `####` for sub-sections.
+- **Admonitions**: Use MkDocs Material admonitions (`!!! info`, `!!! tip`, `!!! warning`, `!!! danger`) for callouts. These are rendered as styled boxes on the site.
+- **Tables**: Use standard GFM pipe tables.
+- **Code blocks**: Use fenced code blocks with a language hint (e.g., ` ```yaml `).
+- **Bold/Italic**: Use `**bold**` for important terms. Use `_italic_` sparingly.
+- **Line breaks**: A trailing two-space line break (or `<br />`) is used to force a line break within a paragraph where needed.
+- **Internal links**: Use root-relative paths without the `.md` extension, e.g. `[Segments](/features/segments)`.
+- **External links**: Use standard Markdown link syntax. Prefer linking to stable, canonical URLs.
+
+---
+
+## Images
+
+- Store images in `docs/assets/images/content/` whenever possible. Avoid external image hosting — the external resource could disappear at any time.
+- Reference images using a path relative to the page or a root-relative path, e.g.:
+  ```markdown
+  ![Alt text](../assets/images/content/my-image.png)
+  ```
+- Animated GIFs hosted on `raw.githubusercontent.com/scottrbailey/WLED-Utils/` are used extensively in the Effects table and are acceptable for that page.
+
+---
+
+## PR Review Checklist
+
+When reviewing a pull request, verify the following:
+
+### Content
+
+- [ ] All text is in **English**.
+- [ ] Content is accurate and consistent with the current WLED feature set.
+- [ ] No duplicate content — check whether similar information already exists on another page and cross-link instead.
+- [ ] Links are valid — no broken internal or external links.
+- [ ] Images are stored in `docs/assets/images/content/` (not external hosting) unless they are GIF previews from the known WLED-Utils repository.
+
+### Formatting
+
+- [ ] Front matter block (`---`) is present and includes a `title` field.
+- [ ] Page title in front matter matches the entry in `mkdocs.yml`.
+- [ ] Heading hierarchy is correct (`#` (optional) → `##` → `###` → `####`, no skipping levels).
+- [ ] Admonitions use the correct type (`info`, `tip`, `warning`, `danger`) for the context.
+- [ ] Tables are properly formatted with pipe characters.
+- [ ] Code blocks use language identifiers.
+- [ ] No unintentional trailing whitespace (two trailing spaces are allowed for forced line breaks).
+
+### Writing Style & Readability
+
+- [ ] Tone is **informal, friendly, and inviting** — avoid overly formal or academic language.
+- [ ] Title case: Use title case for section and subsection headings; articles and short prepositions stay lowercase.
+- [ ] Language is **simple and clear** — short sentences, common words, no unexplained jargon — so non-native English speakers can easily follow.
+- [ ] Logic is easy to follow, examples are kept simple.
+- [ ] Claim calibration: Calibrate verbs to evidence; do not write "proves" when the evidence is "suggests".
+- [ ] No grammar or spelling mistakes.
+- [ ] Express coordinate ideas in the same grammatical form.
+- [ ] Wording is **concise** — remove filler phrases (e.g. "it is worth noting that", "basically", "simply") and redundant sentences.
+- [ ] Prefer "use" over "leverage", "method" over "methodology", "feature" over "functionality".
+- [ ] Contractions (e.g. "you'll", "don't", "it's") are welcome — they help keep the tone approachable.
+- [ ] Avoid idioms or culture-specific phrases (e.g. "beating around the bush", "get your ducks in a row") — they are hard to understand when translated literally into other languages.
+- [ ] Smileys 😊, concrete examples, and images/diagrams/illustrations are encouraged where they help readers grasp the main message.
+
+### Navigation
+
+- [ ] If a new page is added, it is registered in the `nav:` section of `mkdocs.yml` at the correct location and indentation level.
+- [ ] If a page is renamed or moved, the `nav:` entry and all internal links to it are updated.
+
+### Scope
+
+- [ ] Changes are limited to documentation. This repository does not contain WLED firmware code.
+- [ ] PR does not introduce changes to `mkdocs.yml` that alter unrelated pages or nav structure.
+
+---
+
+## Local Preview
+
+To preview the site locally before submitting:
+
+**Docker (recommended):**
+```bash
+docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
+```
+
+**Python/pip:**
+```bash
+pip install mkdocs-material
+mkdocs serve
+```
+
+Then visit <http://localhost:8000>.
+
+---
+
+## Automated Deployment
+
+Merges to `main` trigger the GitHub Actions workflow (`.github/workflows/main.yml`), which builds the MkDocs site and deploys it to GitHub Pages automatically. There is no manual deployment step required.
+
+
+## General Guidelines
+
+- **Provide references** when making analyses or recommendations. Base them on the correct branch or PR.
+- **When unsure, say so.** Gather more information rather than guessing.
+- Support factual claims with verifiable citations, references or concrete evidence; **never fabricate citations**.
+- **Acknowledge good patterns** when you see them. Positive feedback always helps.
+- When updating an existing PR, retain the original description. Only modify it to ensure technical accuracy. Add change logs after the existing description.
+- No force-push on open PRs

docs/about/contributors.md

@@ -49,8 +49,9 @@ Tonyno - tireless user support and documentation
 ### Used Libraries and Dependencies
 
 [ESP8266](https://github.com/esp8266/Arduino)/[ESP32](https://github.com/espressif/arduino-esp32) Arduino Core  
+[ESP32 Tasmota](https://github.com/tasmota/platform-espressif32)/[ESP32 pioarduino](https://github.com/pioarduino/platform-espressif32) Arduino Core and build tools (since 16.0.0)  
 [NeoPixelBus](https://github.com/Makuna/NeoPixelBus) by Makuna  
-[FastLED](https://github.com/FastLED/FastLED/) library  
+[FastLED](https://github.com/FastLED/FastLED/) library (up to 0.15.5)  
 [ESPAsyncTCP](https://github.com/me-no-dev/ESPAsyncTCP) by me-no-dev  
 [ESPAsyncUDP](https://github.com/me-no-dev/ESPAsyncUDP) by me-no-dev (as of 0.9.0)  
 [ESPAsyncWebServer](https://github.com/me-no-dev/ESPAsyncWebServer) by me-no-dev  
@@ -59,7 +60,7 @@ Tonyno - tireless user support and documentation
 [WS2812FX](https://github.com/kitesurfer1404/WS2812FX) by kitesurfer1404 (modified)  
 [IRremoteESP8266](https://github.com/markszabo/IRremoteESP8266) by markszabo (optional)  
 [Timezone](https://github.com/JChristensen/Timezone) by JChristensen  
-[Blynk](https://github.com/blynkkk/blynk-library) library (compacted)  
+[Blynk](https://github.com/blynkkk/blynk-library) library (compacted, up to 0.14.1)  
 [E1.31](https://github.com/forkineye/E131) library by forkineye (modified)  
 [Espalexa](https://github.com/Aircoookie/Espalexa) by Aircoookie (modified)  
 Many included FastLED effects are modified versions of [kriegsman](https://gist.github.com/kriegsman/)'s gists!  
@@ -71,6 +72,8 @@ WLED implements Art-Net™ Designed by and Copyright Artistic Licence Holdings L
 
 [![badge](https://img.shields.io/badge/badges-by%20shields.io-blue.svg?style=flat-square)](https://shields.io)  
 [iro.js](https://iro.js.org/) colorpicker by James Daniel!  
+[Corsfix](https://corsfix.com/)
+
 Classic UI icons by [Linearicons](https://linearicons.com) created by [Perxis](https://perxis.com)!  
 
 If you would like to appear in this list for a contribution you made or be removed from it, feel free to contact me!

docs/about/roadmap.md

@@ -5,9 +5,5 @@ hide:
   # - toc
 ---
 
-These are currently on my list of what COULD be implemented, there is no guarantee if and when they will be available!
-
-- Create named playlists of presets
-- Custom color palettes
-- Settings pages overhaul
-- Rework of WiFi connection logic (reconnect after WiFi or power outage)
+Please check our [WLED milestone planning](https://github.com/wled/WLED/milestones) for upcoming features and releases. 
+There is no guarantee if and when a new feature or bugfix will be available!

docs/advanced/access-over-internet.md

@@ -0,0 +1,76 @@
+---
+title: Accessing WLED over Internet
+hide:
+  # - navigation
+  # - toc
+---
+
+WLED exposed to Internet safely with the help of a reverse proxy setup.
+This document describes the steps needed.
+
+!!! warning "Port Forwarding"
+    Under no circumstances port forward WLED instance to the public internet.
+    WLED does not support HTTPS or authentication, leading to a fundamentally insecure setup.
+
+!!! tip "Consider VPN Tunneling"
+    If you only need access from a single device, such as your phone,
+    consider a point-to-point VPN tunnel instead. Configuring a tunnel
+    may require less configuration and maintenance than a HTTPS reverse proxy.
+
+# Reverse proxy requirements
+
+WLED does not implement access control, allowing anyone able to connect to it change configuration or even update firmware.
+For a safe access, **the reverse proxy MUST implement access control** to only allow trusted users to access WLED.
+
+Secure access control cannot be implemented over insecure connection. **The reverse proxy MUST implement TLS termination**, only allowing access over HTTPS.
+
+Reverse proxy cannot run on the WLED device.
+You need a server in your local network to perform the encryption and proxying.
+
+# Example
+
+Assuming the following network setup, using Caddy as a reverse proxy:
+
+```
+[Public Internet]
+   |
+[Router]
+   |
+[Reverse Proxy]
+   |
+[WLED]
+```
+
+First, register a domain name. In this example, we assume the name "mydomain.example".
+A domain name is commonly a requirement for a HTTP certificate.
+You can use a dynamic dns provider for a free domain.
+
+Next, generate a HTTPs certificate for your domain.
+For the free Let's Encrypt certificates, configure necessary the automation for refreshing the certificate automatically.
+In this example, we are using Caddy which handles this automatically.
+
+We then expose the HTTPS port of the reverse proxy to public internet.
+In your network router, port forward port TCP 443 into the Reverse Proxy.
+In this example, we are using Caddy which only requires port 443 to complete the Let's Encrypt challenge for automatic certificate issuing.
+With other software, you may need to also open insecure HTTP port 80.
+
+Finally, in Caddyfile, configure the reverse proxy and authentication
+Note that Caddy uses HTTPS by default.
+With other software, we may need to disable access over the unsafe HTTP.
+
+```
+mydomain.example {
+  handle /wled/* {
+    # Create username and password. Password can be with `caddy hash-password --plaintext mypass`
+    basicauth {
+        yourusername PASSWORDHASH
+    }
+    uri strip_prefix /wled
+    reverse_proxy wled-wled-a.lan # IP address or the network local name of the WLED device
+  }
+}
+```
+
+Now `https://mydomain.example/wled/` exposes WLED to the public internet using secure HTTPS and password authentication.
+
+For additional securty, consider enabling [OTA lock password](/advanced/ota-lock).

docs/advanced/community-usermods.md

@@ -0,0 +1,26 @@
+---
+title: Community Usermods
+---
+
+This page is an index of usermods written by the WLED community. Entries are maintained by their authors; the WLED project does not test or endorse them.
+
+To help people find your usermod even before it appears here, tag your GitHub repository with the [`wled-usermod`](https://github.com/topics/wled-usermod) topic.
+
+## Adding your usermod
+
+Open a pull request to [WLED-Docs](https://github.com/wled/WLED-Docs) adding a row to the table below. One row, one PR.
+
+Use this format:
+
+```markdown
+| [Name](https://github.com/you/your-usermod) | Short description | @yourname | esp32 |  |
+```
+
+Platforms: `esp32`, `esp8266`, or `both`.
+
+## Index
+
+| Name | Description | Author | Platforms | Notes |
+|---|---|---|---|---|
+| [wled-usermod-example](https://github.com/wled/wled-usermod-example) | Annotated template — fork this to start your own usermod | @wled | both | Official starting point |
+| [user_fx](https://github.com/wled/WLED/tree/main/usermods/user_fx) | Community effects usermod — add your own effects here or use as a template | @wled | both | Ships with WLED; enable with `custom_usermods = user_fx` |

docs/advanced/compiling-wled.md

@@ -75,6 +75,20 @@ Once you've confirmed VSCode with Platformio is set up correctly, you can add/de
  7. Put your `-D` overrides on this new line, giving each `-D` it's own new line.
  8. Compile your freshly customized WLED image!
 
+### Adding usermods
+
+To include one or more usermods in your build, add a `custom_usermods` line to your environment in `platformio_override.ini`:
+
+```ini
+[env:esp32dev_temperature]
+extends = env:esp32dev
+custom_usermods =
+  audioreactive
+  Temperature
+```
+
+Each name corresponds to a folder under `usermods/`. No other file editing is required — usermods self-register when compiled in. For full details, including how to add external usermods from a git repository and how to write your own, see [Custom Features](/advanced/custom-features).
+
 ### Flashing the compiled binary
 
 !!! tip