+ {{ board.environment }}
+
+
+ {{ board.microcontroller }}
+
+ +
+ + + +diff --git a/.gitea/workflows/build-release.yml b/.gitea/workflows/build-release.yml
index 477a43b..b357293 100644
--- a/.gitea/workflows/build-release.yml
+++ b/.gitea/workflows/build-release.yml
@@ -67,16 +67,13 @@ jobs:
echo "tag_name=${TAG_NAME}" >> "$GITHUB_OUTPUT"
echo "short_sha=${SHORT_SHA}" >> "$GITHUB_OUTPUT"
- - name: Set version tag in sources
- env:
- TAG_NAME: ${{ steps.prep.outputs.tag_name }}
- run: |
- sed -i "s/version_tag/${TAG_NAME}/g" main/User_config.h scripts/latest_version.json
-
- name: Build OpenMQTTGateway Firmware (${{ steps.prep.outputs.pio_env }})
env:
PIO_ENV: ${{ steps.prep.outputs.pio_env }}
+ TAG_NAME: ${{ steps.prep.outputs.tag_name }}
run: |
+ # Inject the firmware version (same mechanism as upstream scripts/ci_build_firmware.sh)
+ export PLATFORMIO_BUILD_FLAGS="-DOMG_VERSION=\\\"${TAG_NAME}\\\""
mkdir -p ".pio/build/${PIO_ENV}"
pio run -e "${PIO_ENV}"
diff --git a/.gitignore b/.gitignore
index 4887bbf..9185faa 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,13 +1,50 @@
.pio
.vscode
*_env.ini
+*.pem
**/.DS_Store
node_modules
*.ps1
main/certs/private*
lib/*
!lib/esp32-bt-lib
+!lib/TheengsUtils
+!lib/LEDManager
CMakeLists.txt
dependencies.lock
sdkconfig.*
!sdkconfig.defaults
+__pycache__
+*.pem
+managed_components
+
+
+.github/chatmodes
+.github/prompts
+.github/*instructions.md
+.github/workflows/_docs
+# CI/CD Generated outputs
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+docs/.vitepress/public/boards-info.json
+docs/.vitepress/public/commonConfig.js
+docs/.vitepress/public/firmware_build
+
+# Generated site/firmware/reports files
+generated/
+
+# Generated ssl for testing
+.ssl
+
+# Generated JSON files from templates
+scripts/latest_version.json
+scripts/latest_version_dev.json
+
+# Generated configuration files
+docs/.vitepress/meta.json
+
+# Generated full documentation pages
+docs/prerequisites/board-full.md
+docs/upload/web-install-full.md
+.superpowers/
+docs/superpowers/
diff --git a/.shellcheckrc b/.shellcheckrc
new file mode 100644
index 0000000..db9bb42
--- /dev/null
+++ b/.shellcheckrc
@@ -0,0 +1 @@
+disable=SC1091
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..56f138f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,319 @@
+# OpenMQTTGateway - Claude Code Context
+
+This document provides essential context about the OpenMQTTGateway project for AI assistants working on the codebase.
+
+## Project Overview
+
+OpenMQTTGateway is a unified firmware that bridges various wireless technologies (RF 433MHz, IR, BLE, LoRa, etc.) to MQTT protocol, enabling home automation integration with platforms like Home Assistant, OpenHAB, and Node-RED.
+
+**Key Features:**
+- Multi-protocol gateway (BLE, RF 433MHz, IR, LoRa, RTL_433, Pilight, etc.)
+- ESP8266/ESP32 and Arduino support
+- MQTT-based communication
+- Web UI for configuration
+- Home Assistant MQTT Discovery support
+- Over 100 supported BLE sensors via Theengs Decoder
+
+**Main Branch:** `development` (not master/main)
+
+## Architecture
+
+### Modular Design
+
+The firmware uses a modular architecture where each protocol/sensor/actuator is implemented as a separate "gateway" or "sensor" module:
+
+- **Gateways**: Receive and transmit signals (e.g., `gatewayBT.cpp`, `gatewayRF.cpp`, `gatewayIR.cpp`)
+- **Sensors**: Read physical sensor data (e.g., `sensorBME280.cpp`, `sensorDHT.cpp`)
+- **Actuators**: Control outputs (e.g., `actuatorONOFF.cpp`, `actuatorPWM.cpp`)
+
+Each module has:
+- A config file (e.g., `config_BT.h`, `config_RF.h`)
+- An implementation file (e.g., `gatewayBT.cpp`, `gatewayRF.cpp`)
+
+### Configuration System
+
+Configuration is managed through:
+1. **User_config.h** - Main configuration file with defaults
+2. **config_*.h** - Module-specific configurations
+3. **platformio.ini & environments.ini** - Build-time configurations
+4. **prod_env.ini** - User-specific environments (gitignored)
+
+Build flags in `environments.ini` can override User_config.h parameters.
+
+## Directory Structure
+
+```
+OpenMQTTGateway/
+├── main/ # Main source code (Arduino convention)
+│ ├── main.cpp # Main application entry point
+│ ├── User_config.h # Global configuration
+│ ├── config_*.h # Module configurations
+│ ├── gateway*.cpp # Gateway implementations
+│ ├── sensor*.cpp # Sensor implementations
+│ ├── actuator*.cpp # Actuator implementations
+│ ├── webUI.cpp # Web interface
+│ ├── mqttDiscovery.cpp # Home Assistant discovery
+│ └── rf/ # RF-specific modules
+├── lib/ # Custom libraries
+├── scripts/ # Build and automation scripts
+├── docs/ # VuePress documentation
+├── tests/ # Test configurations
+├── environments.ini # PlatformIO environment definitions
+├── platformio.ini # PlatformIO configuration
+└── prod_env.ini.example # Example production environment
+
+Note: src_dir is set to "main" in platformio.ini
+```
+
+## Key Concepts
+
+### Environment-Based Builds
+
+The project supports 80+ hardware configurations defined in `environments.ini`. Examples:
+- `esp32dev-ble` - ESP32 with BLE gateway
+- `esp32dev-pilight` - ESP32 with Pilight RF
+- `esp32dev-rtl_433` - ESP32 with RTL_433 decoder
+- `nodemcuv2-ir` - NodeMCU with IR
+- `rfbridge` - Sonoff RF Bridge
+
+### MQTT Topics
+
+Standard topic structure:
+- Base: `home/` (configurable via Base_Topic)
+- Gateway name: `OpenMQTTGateway` or `OMG` (configurable)
+- Example: `home/OpenMQTTGateway/BTtoMQTT`
+
+### Module Activation
+
+Modules are activated via build flags in environments.ini:
+```ini
+build_flags =
+ '-DZgatewayBT="BT"' # Enable BLE gateway
+ '-DZgatewayRF="RF"' # Enable RF gateway
+ '-DZsensorBME280="BME280"' # Enable BME280 sensor
+```
+
+### Web UI & WiFi Manager
+
+- ESP32/ESP8266 boards include a WiFiManager for initial setup
+- Access point: SSID = `WifiManager_ssid`, Password = `WifiManager_password`
+- Web UI provides runtime configuration and control
+- Can disable WiFiManager with `ESPWifiManualSetup` flag
+
+## Important Files
+
+### Core Files
+
+- **main/main.cpp** - Main application loop, MQTT handling, module coordination
+- **main/User_config.h** - Global configuration defaults
+- **main/webUI.cpp** - Web interface implementation
+- **main/mqttDiscovery.cpp** - Home Assistant MQTT discovery
+
+### Gateway Files
+
+- **main/gatewayBT.cpp** - BLE gateway (uses Theengs Decoder)
+- **main/gatewayRF.cpp** - RF 433MHz gateway (RCSwitch library)
+- **main/gatewayRF2.cpp** - Alternative RF implementation
+- **main/gatewayPilight.cpp** - Pilight protocol gateway
+- **main/gatewayRTL_433.cpp** - RTL_433 decoder integration
+- **main/gatewayIR.cpp** - Infrared gateway
+- **main/gatewayLORA.cpp** - LoRa gateway
+
+### Configuration Files
+
+All in `main/` directory:
+- **config_RF.h** - RF gateway configuration
+- **config_BT.h** - BLE gateway configuration
+- **config_IR.h** - IR gateway configuration
+- etc.
+
+### Build System
+
+- **platformio.ini** - Main PlatformIO config
+- **environments.ini** - All environment definitions (~3000+ lines)
+- **scripts/** - Python scripts for build automation
+
+## Common Patterns
+
+### Adding a New Gateway Module
+
+1. Create `gateway[NAME].cpp` in `main/`
+2. Create `config_[NAME].h` in `main/`
+3. Add build flag in `environments.ini`: `-DZgateway[NAME]="[NAME]"`
+4. Include conditional compilation: `#ifdef Zgateway[NAME]`
+5. Implement setup function: `setup[NAME]()`
+6. Implement loop function: `[NAME]toMQTT()`
+7. Optionally implement MQTT callback: `MQTTto[NAME]()`
+
+### Adding a New Sensor Module
+
+Similar to gateways, but prefix with `sensor` instead of `gateway` and `Z` becomes `Zsensor`.
+
+### Configuration Override Pattern
+
+```cpp
+#ifndef PARAM_NAME
+# define PARAM_NAME default_value
+#endif
+```
+
+This allows platformio.ini build flags to override defaults.
+
+### MQTT Publishing Pattern
+
+```cpp
+pub(subjectToMQTT, data); // Basic publish
+pub_custom_topic(topic, data, retain); // Custom topic with retain
+```
+
+## Development Workflow
+
+### Building
+
+```bash
+# List all environments
+pio run --list-targets
+
+# Build specific environment
+pio run -e esp32dev-ble
+
+# Upload to device
+pio run -e esp32dev-ble -t upload
+
+# Monitor serial
+pio device monitor
+```
+
+### Code Formatting
+
+- Uses clang-format with config in `.clang-format`
+- CI checks formatting automatically
+- Format before committing
+
+### Testing
+
+- Unit tests in `tests/` directory
+- CI runs builds for all environments
+- Nightly builds test comprehensive environment matrix
+
+### Documentation
+
+- Documentation uses VuePress, located in `docs/`
+- Hosted at https://docs.openmqttgateway.com
+
+## CI/CD
+
+### GitHub Actions Workflows
+
+Located in `.github/workflows/`:
+- **build.yml** - Build validation on PRs
+- **nightly.yml** - Nightly builds of all environments
+- **format-check.yml** - Code formatting validation
+
+### Build Matrix
+
+The nightly build tests configurations:
+- ESP32 variants (ESP32, ESP32-S3, ESP32-C3)
+- ESP8266 variants (NodeMCU, Sonoff)
+- Different gateway combinations
+- Board-specific builds (M5Stack, Heltec, TTGO, etc.)
+
+## Common Issues & Solutions
+
+### Memory Constraints
+
+- ESP8266 has limited RAM (~40KB free)
+- Use `PROGMEM` for constants
+- Minimize module combinations on ESP8266
+- ESP32 has more headroom (~200KB+ free)
+
+### RF Module Conflicts
+
+- Some RF implementations (RF, RF2, Pilight, RTL_433) may conflict
+- Use separate environments for different RF approaches
+- Check GPIO pin assignments in config files
+
+### BLE on ESP32
+
+- BLE stack uses significant RAM
+- Limit simultaneous BLE connections
+
+## Related Projects
+
+- **Theengs Decoder** - BLE device decoder library
+- **Theengs Gateway** - Python version for Raspberry Pi/PC
+- **RTL_433_ESP** - ESP32 port of RTL_433
+
+## Resources
+
+- **Documentation**: https://docs.openmqttgateway.com
+- **Community Forum**: https://community.openmqttgateway.com
+- **GitHub**: https://github.com/1technophile/OpenMQTTGateway
+- **Web Installer**: https://docs.openmqttgateway.com/upload/web-install.html
+
+## Products
+
+- **Theengs Bridge** - ESP32 BLE gateway with Ethernet
+- **Theengs Plug** - Smart plug with BLE gateway
+
+## Conventions
+
+### Naming
+
+- Gateways: `gateway[NAME].cpp` with `Zgateway[NAME]` flag
+- Sensors: `sensor[NAME].cpp` with `Zsensor[NAME]` flag
+- Actuators: `actuator[NAME].cpp` with `Zactuator[NAME]` flag
+- Config files: `config_[NAME].h`
+
+### Code Style
+
+- 2-space indentation
+- Follow existing patterns in similar modules
+- Use preprocessor directives for module isolation
+- Comment complex RF protocols or BLE parsing
+
+### Git Workflow
+
+- Main branch: `development`
+- Feature branches from `development`
+- PRs target `development`
+- Squash commits when appropriate
+- Descriptive commit messages
+
+## Quick Start for Contributors
+
+1. Fork the repository
+2. Create `prod_env.ini` for your local environments
+3. Choose an environment from `environments.ini`
+4. Build: `pio run -e [environment-name]`
+5. Make changes following existing patterns
+6. Test build with your environment
+7. Run format check
+8. Submit PR to `development` branch
+
+## Platform-Specific Notes
+
+### ESP32
+- Preferred platform for new development
+- More RAM and Flash
+- Supports BLE natively
+- Can use Ethernet via add-on boards
+
+### ESP8266
+- Legacy support
+- Memory constrained
+- No native BLE
+- Good for simple RF/IR gateways
+
+## Tips for AI Assistants
+
+1. **Check environments.ini** when modifying build configurations
+2. **Follow existing module patterns** when adding new features
+3. **Test on relevant environments** - changes may affect multiple boards
+4. **Memory is precious** especially on ESP8266
+5. **MQTT topic structure** is critical for Home Assistant integration
+6. **Config headers** allow user customization without code changes
+7. **Use conditional compilation** to keep builds modular
+8. **WebUI changes** need both backend (webUI.cpp) and frontend (config_WebUI.h)
+9. **RF protocols** often need precise timing - be careful with changes
+10. **The main branch is `development`** - always target PRs there
diff --git a/README.md b/README.md
index 8ef78d4..c0ac0e9 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,5 @@
[](https://community.openmqttgateway.com)
-
-
-
[](https://community.openmqttgateway.com)
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.
@@ -15,49 +12,39 @@ OpenMQTTGateway aims to unify various technologies and protocols into a single f
The documentation is [here](https://docs.openmqttgateway.com)
+New to OpenMQTTGateway? Follow the [Getting Started guide](https://docs.openmqttgateway.com/getting-started.html) to flash a board from your browser and see your first sensor data in about 15 minutes.
+
The reference sheet, with the list of all functions, pinouts is [here](https://docs.google.com/spreadsheets/d/1_5fQjAixzRtepkykmL-3uN3G5bLfQ0zMajM9OBZ1bx0/edit#gid=0)
## Upload
-Upload OpenMQTTGateway directly from the [upload page](https://docs.openmqttgateway.com/upload/web-install.html) (no additional software required) or [build your own configuration](https://docs.openmqttgateway.com/upload/builds.html) with [PlatformIO](https://platformio.org/) or [Arduino IDE](https://www.arduino.cc/en/software)
+Upload OpenMQTTGateway directly from the [upload page](https://docs.openmqttgateway.com/upload/web-install.html) (no additional software required) or [build your own configuration](https://docs.openmqttgateway.com/upload/builds.html) with [PlatformIO](https://platformio.org/).
## 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.
+Support open-source development through sponsorship, it helps keep the project healthy and evolving.
-[](https://github.com/sponsors/theengs)
+[](https://github.com/sponsors/1technophile)
## Products powered by OpenMQTTGateway
### Theengs Bridge, Bluetooth gateway (BLE) with external antenna
-[Theengs bridge](https://shop.theengs.io/products/theengs-bridge-esp32-ble-mqtt-gateway-with-ethernet-and-external-antenna) is a powerfull BLE to MQTT gateway for over [90 sensors](https://decoder.theengs.io/devices/devices.html). Equipped with an Ethernet port, and external antenna, ensuring an enhanced range for your BLE sensors. It supports also WiFi connectivity.
+[Theengs bridge](https://shop.theengs.io/products/theengs-bridge-esp32-ble-mqtt-gateway-with-ethernet-and-external-antenna) is a powerfull BLE to MQTT gateway for over [100 sensors](https://decoder.theengs.io/devices/devices.html). Equipped with an Ethernet port, and external antenna, ensuring an enhanced range for your BLE sensors. It supports also WiFi connectivity.
[](https://shop.theengs.io/products/theengs-bridge-esp32-ble-mqtt-gateway-with-ethernet-and-external-antenna)
-### Theengs Plug, Bluetooth gateway (BLE) gateway and Smart Plug
-
-[Theengs plug](https://shop.theengs.io/products/theengs-plug-smart-plug-ble-gateway-and-energy-consumption) brings the following features:
-* BLE to MQTT gateway, tens of [Bluetooth devices](https://compatible.openmqttgateway.com/index.php/devices/ble-devices/) supported thanks to Theengs Decoder library. The plug uses an ESP32 acting as a BLE to Wifi gateway to scan, decode and forward the data of the nearby sensors,
-* Smart plug that can be controlled remotely,
-* Energy consumption monitoring,
-* Device tracker,
-* Presence detection (beta),
-* Local connectivity first.
-
-[](https://shop.theengs.io/products/theengs-plug-smart-plug-ble-gateway-and-energy-consumption)
-
-Support the project by purchasing the [Theengs bridge](https://shop.theengs.io/products/theengs-bridge-esp32-ble-mqtt-gateway-with-ethernet-and-external-antenna) or the [Theengs plug](https://shop.theengs.io/products/theengs-plug-smart-plug-ble-gateway-and-energy-consumption)
+Support the project by purchasing the [Theengs bridge](https://shop.theengs.io/products/theengs-bridge-esp32-ble-mqtt-gateway-with-ethernet-and-external-antenna)
## Compatible items
-* [List of supported devices](https://compatible.openmqttgateway.com/index.php/devices/), door/window sensors, PIR sensors, smoke detectors, weather stations...
+* [List of supported BLE devices](https://decoder.theengs.io/devices/devices.html), thermometers, scales, plant sensors, beacons...
-* [List of compatible boards (Off the shelf or DIY) is available](https://compatible.openmqttgateway.com/index.php/boards/), RF Bridge, IR, BLE gateways...
+* [Boards guide](https://docs.openmqttgateway.com/prerequisites/board.html), RF Bridge, IR, BLE gateways...
*Running on a computer*
If you want to use the BLE decoding capabilities of OpenMQTTGateway with a Raspberry Pi, Windows or Unix PC you can now leverage [Theengs Gateway](https://theengs.github.io/gateway/).
-* [List of compatible components to build your gateway](https://compatible.openmqttgateway.com/index.php/parts/), DHT, RF, IR emitters and receivers...
+* [Parts to build your gateway](https://docs.openmqttgateway.com/prerequisites/parts.html), DHT, RF, IR emitters and receivers...
## Compatible controllers, saas or software
@@ -82,7 +69,6 @@ For Questions or Support please don't open an issue, first go to the [docs](http
If you like the project and/or used it please consider supporting it! It can be done in different ways:
* 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 to the [community](https://community.openmqttgateway.com)
diff --git a/docs/.vitepress/commonConfig.mts b/docs/.vitepress/commonConfig.mts
new file mode 100644
index 0000000..fc0bf1d
--- /dev/null
+++ b/docs/.vitepress/commonConfig.mts
@@ -0,0 +1,41 @@
+// docs/.vitepress/commonConfig.mts
+// Adapter that loads the shared Theengs commonConfig.js (CommonJS) downloaded
+// by CI from https://www.theengs.io/commonConfig.js, and re-exports the nav
+// and head arrays in a format VitePress can consume.
+//
+// This keeps theengs.io as the single source of truth for nav/head until all
+// Theengs docs sites are migrated to VitePress.
+
+import { createRequire } from 'module'
+import { existsSync } from 'fs'
+import { resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const require = createRequire(import.meta.url)
+
+const commonConfigPath = resolve(__dirname, 'public/commonConfig.js')
+
+let sharedConfig: any = null
+
+if (existsSync(commonConfigPath)) {
+ sharedConfig = require(commonConfigPath)
+} else {
+ console.warn(
+ 'commonConfig.js not found in .vitepress/public/. ' +
+ 'Using fallback nav/head. Run CI or download from https://www.theengs.io/commonConfig.js'
+ )
+}
+
+// Re-export nav from shared config, or use a minimal fallback
+export const commonNav = sharedConfig?.themeConfig?.nav ?? [
+ { text: 'Home', link: 'https://www.theengs.io' },
+ { text: 'Community', link: 'https://community.openmqttgateway.com' },
+ { text: 'Shop', link: 'https://shop.theengs.io/' }
+]
+
+// Re-export head from shared config, or use a minimal fallback
+export const commonHead = sharedConfig?.head ?? [
+ ['meta', { name: 'viewport', content: 'width=device-width, initial-scale=1' }],
+ ['meta', { name: 'theme-color', content: '#3eaf7c' }]
+]
diff --git a/docs/.vitepress/components/BoardEnvironmentTable.vue b/docs/.vitepress/components/BoardEnvironmentTable.vue
new file mode 100644
index 0000000..137d727
--- /dev/null
+++ b/docs/.vitepress/components/BoardEnvironmentTable.vue
@@ -0,0 +1,926 @@
+
+
+
+ Loading supported environments...
+ Error {{ error }} No boards match your filters.
+
+
+ Loading environments...
+ Error {{ error }}
+
+ Need to select one environment...{{ recommendedBoard.environment }}
+
+ 🛒 {{ shoppingHint }}
+
+
+
+
+ {{ board.microcontroller }}
+
+ {{ board.environment }}
+
+
+
+
+
+
+
+ 📋
+ Technical Information
+ ▼
+
+
+ Libraries
+ Gateway Modules
+ Hardware
+ Partitions
+ {{ currentEnvironment.partitions }}
+ Build Options
+ {{ formatOptions(currentEnvironment.options) }}
+
; the default
+ theme only makes code scroll inside its language-* wrapper, so long lines such
+ as the esptool.py commands pushed the whole page sideways on phones. */
+.vp-doc pre {
+ overflow-x: auto;
+}
+
+/* Embeds are written as raw HTML in markdown with fixed width/height attributes
+ (e.g.