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

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

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

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

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

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


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

Co-authored-by: Florian <1technophile@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

README.md

@@ -12,6 +12,8 @@ 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
@@ -19,9 +21,9 @@ The reference sheet, with the list of all functions, pinouts is [here](https://d
 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://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/theengs)
+[![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/1technophile)
 
 ## Products powered by OpenMQTTGateway
 
@@ -41,20 +43,20 @@ Support open-source development through sponsorship and gain exclusive access to
 * Presence detection (beta),
 * Local connectivity first.
 
-[![Theengs plug view](./docs/.vuepress/public/img/Theengs-Plug-OpenMQTTGateway.png)](https://shop.theengs.io/products/theengs-plug-smart-plug-ble-gateway-and-energy-consumption)
+[![Theengs plug view](./docs/img/Theengs-Plug-OpenMQTTGateway.png)](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)
 
 ## Compatible items
 
-* [List of supported devices](https://docs.openmqttgateway.com/prerequisites/devices.html), 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://docs.openmqttgateway.com/prerequisites/board.html), 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://docs.openmqttgateway.com/prerequisites/parts.html), 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
 
@@ -79,7 +81,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 a [Theengs plug](https://shop.theengs.io/products/theengs-plug-smart-plug-ble-gateway-and-energy-consumption) or a [Theengs bridge](https://shop.theengs.io/products/theengs-bridge-esp32-ble-mqtt-gateway-with-ethernet-and-external-antenna)
 * 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)
 

docs/.vitepress/components/BoardEnvironmentTable.vue

@@ -13,6 +13,46 @@
     </div>
 
     <div v-if="!loading && !error">
+      <!-- Guided picker -->
+      <div class="wizard">
+        <span class="wizard-title">Help me choose</span>
+        <div class="wizard-row">
+          <span class="filter-group__label">I want to bridge:</span>
+          <div class="filter-chips">
+            <button
+              v-for="b in bridgeOptions"
+              :key="b.key"
+              :class="['filter-chip', { 'filter-chip--active': wizardBridge === b.key }]"
+              @click="wizardBridge = wizardBridge === b.key ? null : b.key">
+              {{ b.label }}
+            </button>
+          </div>
+        </div>
+        <div class="wizard-row">
+          <span class="filter-group__label">My hardware:</span>
+          <div class="filter-chips">
+            <button
+              v-for="h in hardwareOptions"
+              :key="h.key"
+              :class="['filter-chip', { 'filter-chip--active': wizardHardware === h.key }]"
+              @click="wizardHardware = wizardHardware === h.key ? null : h.key">
+              {{ h.label }}
+            </button>
+          </div>
+        </div>
+        <div v-if="wizardBridge && recommendedBoard" class="wizard-result">
+          <div class="wizard-result__text">
+            <span>Recommended: <code>{{ recommendedBoard.environment }}</code></span>
+            <span v-if="recommendedBoard.description" class="wizard-result__desc" v-html="recommendedBoard.description"></span>
+            <span v-if="wizardHardware === 'none' && shoppingHint" class="wizard-result__desc">🛒 {{ shoppingHint }}</span>
+          </div>
+          <button class="wizard-result__cta" @click="openSelector(recommendedBoard.environment)">Flash it →</button>
+        </div>
+        <div v-else-if="wizardBridge && !recommendedBoard" class="wizard-result wizard-result--none">
+          No pre-built environment matches this combination<template v-if="wizardBridge === 'ble' && wizardHardware === 'esp8266'"> — Bluetooth needs an ESP32</template>. Try another hardware choice, or <a :href="buildsUrl">build from source</a>.
+        </div>
+      </div>
+
       <!-- Search and Filter Bar -->
       <div class="filter-bar">
         <div class="search-box">
@@ -32,33 +72,6 @@
           </button>
         </div>
 
-        <div class="filter-groups">
-          <div class="filter-group">
-            <span class="filter-group__label">MCU:</span>
-            <div class="filter-chips">
-              <button
-                v-for="mcu in mcuFilters"
-                :key="mcu"
-                :class="['filter-chip', { 'filter-chip--active': activeMcuFilter === mcu }]"
-                @click="toggleMcuFilter(mcu)">
-                {{ mcu }}
-              </button>
-            </div>
-          </div>
-          <div class="filter-group">
-            <span class="filter-group__label">Gateway:</span>
-            <div class="filter-chips">
-              <button
-                v-for="gw in gatewayFilters"
-                :key="gw.key"
-                :class="['filter-chip', { 'filter-chip--active': activeGatewayFilter === gw.key }]"
-                @click="toggleGatewayFilter(gw.key)">
-                {{ gw.label }}
-              </button>
-            </div>
-          </div>
-        </div>
-
         <div v-if="hasActiveFilters" class="filter-status">
           <span>Showing {{ filteredBoards.length }} of {{ boards.length }} boards</span>
           <button class="filter-clear" @click="clearFilters">Clear all filters</button>
@@ -164,7 +177,7 @@
 </template>
 
 <script setup lang="ts">
-import { ref, reactive, computed, onMounted } from 'vue'
+import { ref, reactive, computed, onMounted, watch } from 'vue'
 
 interface Board {
   environment: string
@@ -176,11 +189,6 @@ interface Board {
   CustomImg?: string
 }
 
-interface GatewayFilter {
-  key: string
-  label: string
-}
-
 const props = withDefaults(defineProps<{
   boardsUrl?: string
   selectorPath?: string
@@ -195,8 +203,25 @@ const error = ref<string | null>(null)
 const expandedModules = reactive<Record<string, boolean>>({})
 const expandedLibraries = reactive<Record<string, boolean>>({})
 const searchQuery = ref('')
-const activeMcuFilter = ref<string | null>(null)
+const wizardBridge = ref<string | null>(null)
-const activeGatewayFilter = ref<string | null>(null)
+const wizardHardware = ref<string | null>(null)
+
+const bridgeOptions = [
+  { key: 'ble', label: 'Bluetooth devices' },
+  { key: 'rf433', label: 'RF devices (433/868/915MHz)' },
+  { key: 'ir', label: 'Infrared' },
+  { key: 'lora', label: 'LoRa' }
+]
+
+const hardwareOptions = [
+  { key: 'esp32dev', label: 'Generic ESP32' },
+  { key: 'esp32c3', label: 'ESP32-C3' },
+  { key: 'esp32s3', label: 'ESP32-S3' },
+  { key: 'lilygo', label: 'LilyGo / Heltec / TTGO' },
+  { key: 'm5', label: 'M5Stack' },
+  { key: 'esp8266', label: 'ESP8266 / NodeMCU' },
+  { key: 'none', label: "I don't have hardware yet" }
+]
 
 const popularEnvironments = [
   'esp32dev-ble',
@@ -226,44 +251,105 @@ function getMcuFamily(mcu: string | undefined): string | null {
   return 'Other'
 }
 
-const mcuFilters = computed<string[]>(() => {
+function matchesBridge(board: Board, bridge: string): boolean {
-  const families: Record<string, boolean> = {}
+  const mods = (board.modules || []).map(m => m.toLowerCase())
-  boards.value.forEach(b => {
+  switch (bridge) {
-    const family = getMcuFamily(b.microcontroller)
+    case 'ble': return mods.some(m => m.includes('bt'))
-    if (family) families[family] = true
+    case 'rf433': return mods.some(m => m.includes('rf') || m.includes('rtl_433') || m.includes('pilight'))
+    case 'ir': return mods.some(m => m.includes('ir'))
+    case 'lora': return mods.some(m => m.includes('lora'))
+    default: return true
+  }
+}
+
+function matchesHardware(board: Board, hardware: string): boolean {
+  const haystack = `${board.environment} ${board.microcontroller || ''}`.toLowerCase()
+  switch (hardware) {
+    case 'esp32dev': return board.environment.toLowerCase().includes('esp32dev')
+    case 'esp32c3': return getMcuFamily(board.microcontroller) === 'ESP32-C3'
+    case 'esp32s3': return getMcuFamily(board.microcontroller) === 'ESP32-S3'
+    case 'lilygo': return /lilygo|heltec|ttgo/.test(haystack)
+    case 'm5': return haystack.includes('m5')
+    case 'esp8266': return getMcuFamily(board.microcontroller) === 'ESP8266'
+    default: return true // 'none': no hardware constraint
+  }
+}
+
+// Preferred defaults per bridge choice, consulted before the generic
+// popular-first order. All entries must be web-flashable environments.
+const preferredByBridge: Record<string, string[]> = {
+  ble: ['esp32dev-ble', 'esp32c3-dev-c2-ble', 'esp32s3-dev-c1-ble', 'esp32-m5atom-lite', 'heltec-ble', 'lilygo-ble'],
+  rf433: ['lilygo-rtl_433', 'esp32dev-rtl_433', 'heltec-rtl_433', 'nodemcuv2-rf'],
+  ir: ['esp32dev-ir', 'nodemcuv2-ir', 'esp32-m5atom-lite'],
+  lora: ['ttgo-lora32-v21', 'heltec-wifi-lora-32', 'ttgo-lora32-v1', 'ttgo-t-beam']
+}
+
+const recommendedBoard = ref<Board | null>(null)
+const manifestCache = new Map<string, boolean>()
+
+// Not every environment in boards-info.json has a pre-built firmware
+// manifest; only recommend ones that can actually be web-flashed.
+async function hasManifest(env: string): Promise<boolean> {
+  const cached = manifestCache.get(env)
+  if (cached !== undefined) return cached
+  let ok = false
+  try {
+    const response = await fetch(buildUrl(`/firmware_build/${env}.manifest.json`), { method: 'HEAD' })
+    ok = response.ok
+  } catch {
+    ok = false
+  }
+  manifestCache.set(env, ok)
+  return ok
+}
+
+let recommendationToken = 0
+watch([wizardBridge, wizardHardware, boards], async () => {
+  const token = ++recommendationToken
+  const bridge = wizardBridge.value
+  if (!bridge) {
+    recommendedBoard.value = null
+    return
+  }
+  const candidates = boards.value.filter(b =>
+    matchesBridge(b, bridge) &&
+    (!wizardHardware.value || matchesHardware(b, wizardHardware.value))
+  )
+  const preferred = preferredByBridge[bridge] || []
+  const ordered = [...candidates].sort((a, b) => {
+    const ai = preferred.indexOf(a.environment)
+    const bi = preferred.indexOf(b.environment)
+    return (ai === -1 ? preferred.length : ai) - (bi === -1 ? preferred.length : bi)
   })
-  return Object.keys(families).sort()
+  for (const candidate of ordered.slice(0, 8)) {
+    if (await hasManifest(candidate.environment)) {
+      if (token === recommendationToken) recommendedBoard.value = candidate
+      return
+    }
+  }
+  if (token === recommendationToken) recommendedBoard.value = null
 })
 
-const gatewayFilters = computed<GatewayFilter[]>(() => {
+const shoppingHint = computed<string>(() => {
-  const gateways: Record<string, string> = {
+  switch (wizardBridge.value) {
-    BT: 'BLE',
+    case 'ble':
-    RF: 'RF',
+    case 'ir': return 'Any ESP32 development board will do.'
-    IR: 'IR',
+    case 'rf433': return 'A LILYGO LoRa32 or Heltec LoRa V2 board matching your devices\' frequency (433/868/915MHz) needs no soldering.'
-    LORA: 'LoRa',
+    case 'lora': return 'Get a LILYGO LoRa32 or Heltec LoRa board matching the frequency used in your region.'
-    RTL_433: 'RTL_433',
+    default: return ''
-    Pilight: 'Pilight'
   }
-  const result: GatewayFilter[] = []
-  Object.keys(gateways).forEach(key => {
-    const hasBoards = boards.value.some(b =>
-      Array.isArray(b.modules) && b.modules.some(m =>
-        m.toLowerCase().includes(key.toLowerCase())
-      )
-    )
-    if (hasBoards) {
-      result.push({ key, label: gateways[key] })
-    }
-  })
-  return result
 })
 
+const buildsUrl = computed(() => buildUrl('/upload/builds.html'))
+
 const hasActiveFilters = computed(() =>
-  searchQuery.value || activeMcuFilter.value || activeGatewayFilter.value
+  searchQuery.value || wizardBridge.value || wizardHardware.value
 )
 
 const filteredBoards = computed<Board[]>(() =>
   boards.value.filter(board => {
+    if (wizardBridge.value && !matchesBridge(board, wizardBridge.value)) return false
+    if (wizardHardware.value && wizardHardware.value !== 'none' && !matchesHardware(board, wizardHardware.value)) return false
     if (searchQuery.value) {
       const q = searchQuery.value.toLowerCase()
       const haystack = [
@@ -274,32 +360,14 @@ const filteredBoards = computed<Board[]>(() =>
       ].join(' ').toLowerCase()
       if (!haystack.includes(q)) return false
     }
-    if (activeMcuFilter.value) {
-      const family = getMcuFamily(board.microcontroller)
-      if (family !== activeMcuFilter.value) return false
-    }
-    if (activeGatewayFilter.value) {
-      const key = activeGatewayFilter.value.toLowerCase()
-      if (!Array.isArray(board.modules) || !board.modules.some(m =>
-        m.toLowerCase().includes(key)
-      )) return false
-    }
     return true
   })
 )
 
-function toggleMcuFilter(mcu: string) {
-  activeMcuFilter.value = activeMcuFilter.value === mcu ? null : mcu
-}
-
-function toggleGatewayFilter(gw: string) {
-  activeGatewayFilter.value = activeGatewayFilter.value === gw ? null : gw
-}
-
 function clearFilters() {
   searchQuery.value = ''
-  activeMcuFilter.value = null
+  wizardBridge.value = null
-  activeGatewayFilter.value = null
+  wizardHardware.value = null
 }
 
 async function loadBoards() {
@@ -357,6 +425,16 @@ function getBoardImageUrl(board: Board): string {
 }
 
 onMounted(() => {
+  // Preset the guided picker from query parameters, e.g. ?bridge=ble&hardware=esp32dev
+  const params = new URLSearchParams(window.location.search)
+  const bridgeParam = params.get('bridge')
+  if (bridgeParam && bridgeOptions.some(b => b.key === bridgeParam)) {
+    wizardBridge.value = bridgeParam
+  }
+  const hardwareParam = params.get('hardware')
+  if (hardwareParam && hardwareOptions.some(h => h.key === hardwareParam)) {
+    wizardHardware.value = hardwareParam
+  }
   loadBoards()
 })
 </script>
@@ -366,6 +444,77 @@ onMounted(() => {
   margin: 2rem 0;
 }
 
+/* Guided picker */
+.wizard {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 12px;
+  padding: 16px;
+  margin-bottom: 1.25rem;
+}
+
+.wizard-title {
+  font-weight: 600;
+  font-size: 0.95rem;
+}
+
+.wizard-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.wizard-result {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  flex-wrap: wrap;
+  border-top: 1px dashed var(--vp-c-divider);
+  padding-top: 12px;
+  font-size: 0.9rem;
+}
+
+.wizard-result__text {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.wizard-result__desc {
+  color: var(--vp-c-text-2);
+  font-size: 0.85rem;
+}
+
+.wizard-result__cta {
+  background: var(--vp-c-brand-1);
+  color: var(--vp-c-white, #fff);
+  border: none;
+  border-radius: 20px;
+  padding: 8px 18px;
+  font-weight: 600;
+  font-size: 0.9rem;
+  cursor: pointer;
+  transition: background 0.2s ease;
+}
+
+.wizard-result__cta:hover {
+  background: var(--vp-c-brand-2);
+}
+
+.wizard-result--none {
+  display: block;
+  color: var(--vp-c-text-2);
+}
+
+.wizard-result--none a {
+  color: var(--vp-c-brand-1);
+}
+
 /* Search and Filter Bar */
 .filter-bar {
   margin-bottom: 1.5rem;

docs/.vitepress/components/FlashEnvironmentSelector.vue

@@ -135,6 +135,16 @@
             </div>
           </div>
         </details>
+
+        <!-- Post-flash next steps -->
+        <div class="next-steps">
+          <h3 class="next-steps__title">✅ After flashing</h3>
+          <ol class="next-steps__list">
+            <li>Keep the board powered — it starts a WiFi access point named <code>OpenMQTTGateway</code> or starting with <code>OMG_</code>.</li>
+            <li>From your phone or computer, connect to that WiFi network and follow the <a :href="portalUrl">configuration portal guide</a> to enter your WiFi and MQTT broker credentials.</li>
+            <li>The gateway restarts, joins your network and connects to your broker — <a :href="verifyUrl">check that it works</a>.</li>
+          </ol>
+        </div>
       </div>
 
     </Transition>
@@ -190,6 +200,9 @@ const manifestUrl = computed<string | null>(() => {
   return `${resolvedFirmwareBaseUrl.value}${selectedEnvironment.value}.manifest.json`
 })
 
+const portalUrl = computed<string>(() => buildUrl('/upload/portal.html'))
+const verifyUrl = computed<string>(() => buildUrl('/getting-started.html#step-4-check-that-it-works'))
+
 const boardImageUrl = computed<string | null>(() => {
   if (!currentEnvironment.value) return null
   const customImg = currentEnvironment.value.customImg || currentEnvironment.value.CustomImg
@@ -294,6 +307,36 @@ function handleImageError(): void {
 </script>
 
 <style scoped>
+/* Post-flash next steps */
+.next-steps {
+  margin-top: 16px;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 12px;
+  padding: 20px 24px;
+}
+
+.next-steps__title {
+  margin: 0 0 8px;
+  font-size: 16px;
+  font-weight: 600;
+}
+
+.next-steps__list {
+  margin: 0;
+  padding-left: 20px;
+}
+
+.next-steps__list li {
+  margin: 6px 0;
+  line-height: 1.6;
+}
+
+.next-steps__list a {
+  color: var(--vp-c-brand-1);
+  font-weight: 500;
+}
+
 /* Main Container */
 .flash-selector {
   max-width: 1200px;
@@ -323,6 +366,7 @@ function handleImageError(): void {
   display: flex;
   flex-direction: column;
   gap: 16px;
+  min-width: 0;
 }
 
 .board-hero__title {
@@ -341,6 +385,7 @@ function handleImageError(): void {
   align-items: center;
   gap: 8px;
   margin: 0;
+  min-width: 0;
 }
 
 .switcher-label {
@@ -355,10 +400,14 @@ function handleImageError(): void {
   position: relative;
   display: inline-flex;
   align-items: center;
+  min-width: 0;
+  max-width: 100%;
 }
 
 .switcher-select {
   appearance: none;
+  max-width: 100%;
+  text-overflow: ellipsis;
   background: var(--vp-c-bg-soft);
   color: var(--vp-c-text-1);
   border: none;
@@ -425,7 +474,7 @@ function handleImageError(): void {
   display: flex;
   align-items: flex-start;
   justify-content: center;
-  min-width: 180px;
+  min-width: 0;
   max-width: 200px;
 }
 

docs/.vitepress/components/OmgPipeline.vue

@@ -0,0 +1,122 @@
+<template>
+  <div class="omg-pipeline-wrap">
+    <div class="omg-pipeline">
+      <div class="omg-node">
+        <span class="omg-node-icon">🌡️</span>
+        <strong>Your devices</strong>
+        <span class="omg-node-sub">BLE · RF · IR · LoRa</span>
+      </div>
+      <span class="omg-arrow">⇄</span>
+      <div class="omg-node omg-node-brand">
+        <span class="omg-node-icon">📟</span>
+        <strong>OpenMQTTGateway</strong>
+        <span class="omg-node-sub">ESP32 / ESP8266</span>
+      </div>
+      <span class="omg-arrow">⇄</span>
+      <div class="omg-node">
+        <span class="omg-node-icon">🔀</span>
+        <strong>MQTT broker</strong>
+        <span class="omg-node-sub">Mosquitto...</span>
+      </div>
+      <span class="omg-arrow">⇄</span>
+      <div class="omg-node">
+        <span class="omg-node-icon">🏠</span>
+        <strong>Your controller</strong>
+        <span class="omg-node-sub">Home Assistant, OpenHAB...</span>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.omg-pipeline-wrap {
+  container-type: inline-size;
+  margin: 24px 0;
+}
+
+.omg-pipeline {
+  display: flex;
+  align-items: stretch;
+  gap: 8px;
+}
+
+.omg-node {
+  flex: 1 1 0;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  gap: 4px;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 12px;
+  padding: 20px 10px;
+}
+
+.omg-node-brand {
+  border-color: var(--vp-c-brand-1);
+  box-shadow: 0 0 0 1px var(--vp-c-brand-1);
+}
+
+.omg-node-icon {
+  font-size: 28px;
+}
+
+.omg-node strong {
+  font-size: 15px;
+  line-height: 1.3;
+}
+
+.omg-node-sub {
+  color: var(--vp-c-text-2);
+  font-size: 13px;
+}
+
+.omg-arrow {
+  align-self: center;
+  flex-shrink: 0;
+  color: var(--vp-c-brand-1);
+  font-size: 20px;
+  font-weight: 700;
+}
+
+/* Narrow containers (doc column, tablets): tighten the nodes, keep one row */
+@container (max-width: 760px) {
+  .omg-pipeline {
+    gap: 6px;
+  }
+  .omg-node {
+    padding: 12px 6px;
+  }
+  .omg-node strong {
+    font-size: 13px;
+  }
+  .omg-node-sub {
+    font-size: 11px;
+  }
+  .omg-node-icon {
+    font-size: 22px;
+  }
+  .omg-arrow {
+    font-size: 16px;
+  }
+}
+
+/* Very narrow (phones): stack vertically */
+@container (max-width: 480px) {
+  .omg-pipeline {
+    flex-direction: column;
+  }
+  .omg-arrow {
+    transform: rotate(90deg);
+  }
+  .omg-node strong {
+    font-size: 15px;
+  }
+  .omg-node-sub {
+    font-size: 13px;
+  }
+}
+</style>

docs/.vitepress/config.mts

@@ -18,9 +18,11 @@ try {
 
 export default defineConfig({
   title: `${meta.title} - ${meta.version}`,
-  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.',
+  description: 'One gateway, many technologies: MQTT gateway for ESP8266 or ESP32 with bidirectional 433mhz/315mhz/868mhz/915mhz RF, Infrared communications, BLE, LoRa, beacons detection, mi flora / mi jia / LYWSD02/ Mi Scale compatibility, SMS & LORA.',
   base: meta.url_prefix as '/' | `/${string}/`,
   outDir: resolve(__dirname, '../../', meta.dest),
+  // Internal working documents, not part of the published site
+  srcExclude: ['superpowers/**'],
   head: commonHead,
   ignoreDeadLinks: [
     /localhost/,
@@ -46,7 +48,8 @@ export default defineConfig({
       pattern: `https://github.com/${meta.theme_config_repo}/edit/development/docs/:path`
     },
     sidebar: [
-      { text: '0 - What is it for', link: '/' },
+      { text: 'What is it for', link: '/' },
+      { text: 'Getting Started', link: '/getting-started' },
       {
         text: '1 - Prerequisites',
         collapsed: true,
@@ -59,7 +62,21 @@ export default defineConfig({
         ]
       },
       {
-        text: '2 - Set it up',
+        text: '2 - Upload',
+        collapsed: true,
+        link: '/upload/',
+        items: [
+          { text: '1. Web installer (easiest)', link: '/upload/web-install' },
+          { text: '2. Ready-to-go binaries', link: '/upload/binaries' },
+          { text: '3. Build from source', link: '/upload/builds' },
+          { text: 'Configuration portal', link: '/upload/portal' },
+          { text: 'Portal HTTP API', link: '/upload/portal-api' },
+          { text: 'Advanced Configuration', link: '/upload/advanced-configuration' },
+          { text: 'Troubleshoot', link: '/upload/troubleshoot' }
+        ]
+      },
+      {
+        text: '3 - Hardware setup',
         collapsed: true,
         items: [
           { text: 'RF', link: '/setitup/rf' },
@@ -72,21 +89,6 @@ export default defineConfig({
           { text: 'Actuators', link: '/setitup/actuators' }
         ]
       },
-      {
-        text: '3 - Upload',
-        collapsed: true,
-        link: '/upload/',
-        items: [
-          { text: '(Option 1) Upload from the web', link: '/upload/web-install' },
-          { text: 'Binaries', link: '/upload/binaries' },
-          { text: 'Builds', link: '/upload/builds' },
-          { text: 'Gitpod', link: '/upload/gitpod' },
-          { text: 'Portal', link: '/upload/portal' },
-          { text: 'Portal HTTP API', link: '/upload/portal-api' },
-          { text: 'Advanced Configuration', link: '/upload/advanced-configuration' },
-          { text: 'Troubleshoot', link: '/upload/troubleshoot' }
-        ]
-      },
       {
         text: '4 - Use',
         collapsed: true,
@@ -123,7 +125,7 @@ export default defineConfig({
         collapsed: true,
         link: '/participate/',
         items: [
-          { text: 'Quick Start', link: '/participate/quick_start' },
+          { text: 'Contributor Quick Start', link: '/participate/quick_start' },
           { text: 'Support', link: '/participate/support' },
           { text: 'Development', link: '/participate/development' },
           { text: 'Adding Protocols', link: '/participate/adding-protocols' },

docs/.vitepress/theme/custom.css

@@ -17,6 +17,32 @@
   max-width: 100% !important;
 }
 
+/* Enlarge the home hero image beyond the theme's ~320px default cap */
+.VPHome .VPHero .image-container {
+  transform: none;
+  width: 100%;
+  height: auto;
+  margin: 0 auto;
+}
+
+.VPHome .VPHero .image-bg {
+  display: none;
+}
+
+.VPHome .VPHero .image-src {
+  position: static;
+  transform: none;
+  width: 100%;
+  max-width: 420px;
+  max-height: none;
+}
+
+@media (min-width: 960px) {
+  .VPHome .VPHero .image-src {
+    max-width: 520px;
+  }
+}
+
 /* Gray backdrop when ESP Web Tools install dialog is open */
 ewt-install-dialog {
   position: fixed;

docs/.vitepress/theme/index.ts

@@ -6,12 +6,14 @@ import { useRoute } from 'vitepress'
 import './custom.css'
 import BoardEnvironmentTable from '../components/BoardEnvironmentTable.vue'
 import FlashEnvironmentSelector from '../components/FlashEnvironmentSelector.vue'
+import OmgPipeline from '../components/OmgPipeline.vue'
 
 export default {
   extends: DefaultTheme,
   enhanceApp({ app }) {
     app.component('BoardEnvironmentTable', BoardEnvironmentTable)
     app.component('FlashEnvironmentSelector', FlashEnvironmentSelector)
+    app.component('OmgPipeline', OmgPipeline)
   },
   setup() {
     const route = useRoute()

docs/getting-started.md

@@ -0,0 +1,73 @@
+# Getting Started
+
+This guide walks you through the two most popular setups from start to finish, flashed **from your browser** and integrated with **Home Assistant**. No soldering, no development environment, about 15 minutes:
+
+* **Bluetooth sensors** — any ESP32 board reading thermometers, plant sensors, scales...
+* **RF devices (433/315/868/915MHz)** — a LILYGO LoRa32 board receiving weather stations, door sensors, PIR sensors...
+
+Using another controller (OpenHAB, Node-RED...) or another technology (IR, LoRa)? Follow the same steps and take the detours linked along the way.
+
+## How the pieces fit together
+
+OpenMQTTGateway (OMG) is a firmware for your board that translates signals from your devices (Bluetooth sensors, RF remotes, weather stations...) into MQTT messages, and the other way around:
+
+<OmgPipeline />
+
+The **broker** is the message hub; the **controller** is the home automation software where you see and use the data.
+
+## What you need
+
+* **A board** — for **Bluetooth**, any ESP32 development board. For **RF**, a LILYGO® LoRa32 V2.1 or a Heltec LoRa V2 matching your devices' frequency — 433MHz for most European devices, 915MHz in North America (no soldering needed). See the [board guide](prerequisites/board.md) for other cases, or get a pre-flashed [Theengs Bridge](https://shop.theengs.io/) and skip the flashing step.
+* **A data USB cable** — some cables are charge-only and won't work.
+* **An MQTT broker** — see Step 1.
+* **A device to observe** — e.g. a [compatible Bluetooth sensor](https://decoder.theengs.io/devices/devices.html) such as a Mi Flora, LYWSD03MMC, Govee or Inkbird thermometer, or any RF sensor around you (weather station, door or PIR sensor...).
+
+## Step 1 — Set up the MQTT broker
+
+If you use **Home Assistant**, the simplest option is the Mosquitto add-on:
+
+1. In Home Assistant go to **Settings → Add-ons → Add-on store**, install **Mosquitto broker** and start it.
+2. Install the **MQTT integration** (**Settings → Devices & services → Add integration → MQTT**) if it isn't set up already.
+3. Create a dedicated user for the gateway in **Settings → People → Users** (e.g. `omg` — it doesn't need to be an administrator). The gateway will log in with it.
+
+No Home Assistant? Install [Mosquitto](https://mosquitto.org/) on any always-on machine, or see the [broker page](prerequisites/broker.md) for alternatives.
+
+## Step 2 — Flash the firmware from your browser
+
+1. Open the [web installer](upload/web-install.md) in **Chrome, Edge or Opera** (Firefox and Safari don't support web flashing).
+2. Connect the board to your computer with the USB cable.
+3. Pick the firmware matching your board and use case — the two most flashed:
+   * **Bluetooth** on a generic ESP32: <a href="./upload/board-selector.html?env=esp32dev-ble"><strong>esp32dev-ble</strong></a>
+   * **RF** on a LILYGO LoRa32: <a href="./upload/board-selector.html?env=lilygo-rtl_433"><strong>lilygo-rtl_433</strong></a> (the radio frequency is configurable afterwards)
+4. Click **Connect**, select the board's USB port, and let the installer finish.
+
+Prefer a desktop tool, or need a custom configuration? See the other [upload options](upload/index.md).
+
+## Step 3 — Connect the gateway to your WiFi and broker
+
+After flashing, the gateway starts its own WiFi access point:
+
+1. From your phone or computer, connect to the WiFi network named **OpenMQTTGateway** or starting with **OMG_** (no password, except for Theengs devices — see the [portal page](upload/portal.md)).
+2. A configuration page opens (on Android, accept "stay connected without internet"). Click **Configure WiFi**.
+3. Select your WiFi network and enter its password.
+4. Enter your broker's address as MQTT server (for the Home Assistant add-on, `homeassistant.local` or the server IP), keep port `1883`, and fill in the MQTT username and password from Step 1.
+5. Click **Save**. The gateway restarts and joins your network.
+
+The full list of portal fields is described on the [configuration portal page](upload/portal.md).
+
+## Step 4 — Check that it works
+
+* In Home Assistant, go to **Settings → Devices & services → MQTT**: after a minute you should see a device named **OpenMQTTGateway**, created automatically through MQTT discovery.
+* **Bluetooth**: bring a compatible sensor nearby — it appears as its own device with its measurements as entities. Some devices only advertise on an event: press a button or trigger a reading if nothing shows up.
+* **RF**: supported devices appear automatically as soon as they transmit — weather stations send every minute or two, door and PIR sensors on an event, so trigger one to see it arrive.
+* You can also watch the raw messages with [MQTT Explorer](https://mqtt-explorer.com/): connect to your broker and look for `home/OpenMQTTGateway/LWT` = `online` and messages under `home/OpenMQTTGateway/`.
+
+Something not right? Head to the [troubleshooting page](upload/troubleshoot.md) or ask on the [community forum](https://community.openmqttgateway.com).
+
+## Where to go next
+
+* **More RF options** — other <a href="./upload/web-install.html?bridge=rf433">compatible boards and firmwares</a>, transmitting, frequency tuning, and protocol details in [RF hardware setup](setitup/rf.md) and [RF usage](use/rf.md).
+* **Infrared** — wire an IR emitter/receiver following the [IR hardware setup](setitup/ir.md).
+* **Tune the gateway** — the [WebUI](use/webui.md) and [gateway commands](use/gateway.md) let you configure it at runtime over MQTT.
+* **Other controllers** — [OpenHAB](integrate/openhab3.md), [Node-RED](integrate/node_red.md), [Jeedom](integrate/jeedom.md), [AWS IoT](integrate/aws_iot.md).
+* **Full Home Assistant details** — [Home Assistant integration](integrate/home_assistant.md).

docs/index.md

@@ -1,3 +1,45 @@
+---
+layout: home
+
+hero:
+  name: OpenMQTTGateway
+  text: One gateway, many technologies
+  tagline: Bridge RF, Infrared, Bluetooth LE, LoRa and more to MQTT, and to your home automation platform.
+  image:
+    src: /img/OpenMQTTGateway.png
+    alt: Overview of the protocols and compatible controllers
+  actions:
+    - theme: brand
+      text: Get started
+      link: /getting-started
+    - theme: alt
+      text: Flash from your browser
+      link: /upload/web-install
+    - theme: alt
+      text: Supported BLE devices
+      link: https://decoder.theengs.io/devices/devices.html
+
+features:
+  - icon: 📶
+    title: Bluetooth Low Energy
+    details: Decodes more than 100 BLE sensors out of the box thanks to Theengs Decoder — Mi Flora, Xiaomi, Govee, Inkbird, SwitchBot and more.
+  - icon: 📡
+    title: RF 433/315/868/915MHz
+    details: Receive and transmit RF signals with RTL_433, RCSwitch, KaKu or Pilight — weather stations, door sensors, remotes, PIR sensors.
+  - icon: 🔴
+    title: Infrared & LoRa
+    details: Make your old TV or AC smart through IR, or reach far-away sensors with LoRa.
+  - icon: 🏠
+    title: Home automation ready
+    details: Home Assistant MQTT auto-discovery enabled by default. Works with OpenHAB, Domoticz, Jeedom, Node-RED, FHEM and any MQTT-capable software.
+  - icon: ⚡
+    title: Easy to install
+    details: Flash an ESP32 or ESP8266 directly from your browser, then configure WiFi and MQTT through a web portal. No development tools required.
+  - icon: 🔧
+    title: Extensible
+    details: Add sensors (BME280, DHT, INA226...) and actuators (relays, PWM, LED), secure connections with TLS, and update over the air.
+---
+
 <script setup>
 import { useData } from 'vitepress'
 import { computed } from 'vue'
@@ -9,133 +51,241 @@ const commitUrl = computed(() =>
     ? `https://github.com/${theme.value.repo}/commit/${version}`
     : null
 )
+
+const useCases = [
+  { icon: '🌱', text: 'Water the garden when a Mi Flora sensor says the soil is dry' },
+  { icon: '🚪', text: 'Detect opened doors and windows through 433MHz or BLE' },
+  { icon: '🧊', text: 'Get alerted when the fridge or freezer gets too warm' },
+  { icon: '📺', text: 'Make your old TV or AC smart through infrared control' },
+  { icon: '⌚', text: 'Run a welcome scenario when your smartwatch comes home' },
+  { icon: '🥩', text: 'Follow your meat temperature while cooking with an Inkbird IBBQ' },
+  { icon: '💧', text: 'Detect water leakage or smoke remotely' },
+  { icon: '📬', text: 'Know when a distant mailbox is opened, over LoRa' },
+  { icon: '🌡️', text: 'Trigger a fan from a Mi Jia temperature and humidity sensor' },
+  { icon: '🚨', text: 'Sound a siren if something is going wrong' },
+  { icon: '⚖️', text: 'Log your weight automatically from a BLE scale' },
+  { icon: '🛞', text: 'Monitor your vehicle tire pressure' }
+]
+
+const functions = [
+  'Home Assistant auto-discovery', 'Message deduplication', 'Simple MQTT API',
+  'Signal forward & repeat', 'WiFi onboarding portal', 'Web UI configuration',
+  'Whitelist & blacklist', 'TLS secure connections', 'Over-the-air updates',
+  'Local first, cloud optional'
+]
+
+const videos = [
+  { id: '_gdXR1uklaY', title: '433MHz and BLE gateway', author: 'Andreas Spiess' },
+  { id: 'noUROhtf0E0', title: 'BLE gateway', author: 'Andreas Spiess' },
+  { id: 'H-JXWbWjJYE', title: 'RTL_433 on ESP32', author: 'Tech Mind' },
+  { id: '6DftaHxDawM', title: 'LoRa gateway', author: 'PricelessToolkit' }
+]
+
+const press = [
+  { name: 'ESPHome vs OMG', url: 'https://medium.com/@zediot/esphome-vs-openmqttgateway-choosing-the-right-esp32-bridge-model-7126379e36be' },
+  { name: 'ZedIoT', url: 'https://zediot.com/blog/what-is-openmqttgateway/' },
+  { name: 'HomeTechHacker', url: 'https://hometechhacker.com/theengs-bridge-ble-mqtt-gateway-review/' },
+  { name: 'Squix', url: 'https://blog.squix.org/2023/04/esp32-cheap-sensor-network-with-openmqttgateway.html' },
+  { name: 'Hackaday', url: 'https://hackaday.com/2023/01/13/arduino-library-brings-rtl_433-to-the-esp32' },
+  { name: 'CNX Software', url: 'https://www.cnx-software.com/2023/01/14/esp32-board-with-lora-433-mhz-sensors/' },
+  { name: 'RTL-SDR', url: 'https://www.rtl-sdr.com/rtl_433-ported-to-esp32-microcontrollers-with-cc1101-or-sx127x-transceiver-chips/' },
+  { name: 'LWN.net', url: 'https://lwn.net/Articles/921497/' }
+]
 </script>
 
-<div v-if="isDev" class="warning custom-block">
+<div v-if="isDev" class="warning custom-block omg-section">
 <p class="custom-block-title">Development Version</p>
 <p>This is the edge version of the documentation, built from commit <a v-if="commitUrl" :href="commitUrl"><code>{{ version }}</code></a><code v-else>{{ version }}</code>. It is under active development and may contain bugs, incomplete features, or breaking changes. Use it at your own risk.</p>
 </div>
 
-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.
+<div class="omg-section">
-
+  <h2>How it works</h2>
-<div style="text-align: center;">
+  <p class="omg-lead">OpenMQTTGateway is a firmware for ESP32 and ESP8266 boards that translates your devices' signals into <a href="http://mqtt.org/">MQTT</a> messages — and back. One board replaces a drawer full of proprietary bridges.</p>
-<img src="./img/OpenMQTTGateway.png" alt="Overview of the protocols and compatible controllers" style="max-width: 100%; height: auto;">
+  <OmgPipeline />
+  <p class="omg-caption">Decodes <a href="https://decoder.theengs.io/devices/devices.html">more than 100 BLE devices</a> and many RF protocols (433/315/868/915MHz) through <a href="./use/rf.html#supported-decoders">RTL_433 decoders</a> — and the BLE decoding also runs on Raspberry Pi, Windows or Linux with <a href="https://theengs.github.io/gateway/">Theengs Gateway</a>.</p>
 </div>
 
-# What is an MQTT gateway or bridge ?
+<div class="omg-section">
-
+  <h2>What will you automate?</h2>
-MQTT, short for Message Queuing Telemetry Transport, is a lightweight messaging protocol ideal for IoT devices.
+  <div class="omg-grid">
-
+    <div v-for="uc in useCases" :key="uc.text" class="omg-card">
-An MQTT gateway or bridge plays a pivotal role in the MQTT ecosystem:
+      <span class="omg-card-icon">{{ uc.icon }}</span>
-* Protocol Translation: It converts non-MQTT protocols (like LoRa or Bluetooth) into MQTT, enabling broader network communication.
+      <span>{{ uc.text }}</span>
-* Data Aggregation: Combines data from multiple devices into single messages, optimizing network use.
+    </div>
-* Security: Incorporates features like SSL/TLS encryption to safeguard data during transmission.
+  </div>
-* Device Management: Handles tasks like firmware updates and remote configuration changes.
+  <p class="omg-caption">The limit is your imagination 😀</p>
-
-In essence, an MQTT gateway ensures smooth communication between devices and MQTT brokers, enhancing the efficiency and security of IoT systems.
-
-# What OpenMQTTGateway can do ?
-
-OpenMQTTGateway integrates with established technologies, such as 433mhz/315mhz protocols and infrared (IR), allowing you to upgrade and repurpose older devices. Additionally, OMG is compatible with modern technologies like Bluetooth Low Energy (BLE) and LoRa.
-
-To have an overview of the supported PIR, door, water, temperature, smoke sensors, sirens, rings, beacons, switches & weather stations you can take a look to the 
-[compatible devices list](prerequisites/devices.md)
-
-You can run OpenMQTTGateway on a wide variety of [boards](prerequisites/board.md), ESP32, ESP8266, ESP32S3, ESP32C3.
-BLE to MQTT gateway can also run on Raspberry Pi, Windows or Unix computers thanks to [Theengs Gateway](https://theengs.github.io/gateway/).
-
-Using MQTT, you can seamlessly integrate with home automation platforms such as OpenHAB, Home Assistant, and others, or with IoT software like Node-Red.
-
-# Use cases
-Leveraging OpenMQTTGateway with a controller allows you to:
-* Monitor a garden with a Mi Flora BLE sensor and control an irrigation valve depending on the soil moisture,
-* Trigger a fan depending on the temperature and humidity thanks to a Mi Jia/LYWSD03MMC BLE sensor,
-* Follow your meat temperature when cooking with an Inkbird IBBQ
-* Alert yourself by a controller notification if the temperature of a fridge or freezer is too high,
-* Detect a beacon/smartwatch so as to trigger a special scenario when you come home,
-* [Lose weight with the help of a complete log system](https://www.youtube.com/watch?v=noUROhtf0E0&t=18s), video from [@Andreas Spiess](https://www.youtube.com/channel/UCu7_D0o48KbfhpEohoP7YSQ)
-* Detect opened door or windows through 433mhz or BLE and alert yourself when leaving
-* Detect water leakage or smoke remotely
-* Actionate a siren if something is going wrong
-* Detect if your far mailbox has been opened by the postman with LoRa
-* Make smart your old TV or AC system through infrared control
-* Monitor vehicle tire pressure
-
-The limit is your imagination 😀
-
-# Functions
-Under the hood, OpenMQTTGateway offers features such as:
-* Deduplication
-* Simple and lite API
-* Strong integrations with libraries used
-* Signal forward/repeat
-* Wifi web portal onboarding
-* Web portal configuration
-* Whitelist & Blacklist management
-* Secure connections
-* Over the air updates
-* Local or cloud, your choice
-
-## Using OpenMQTTGateway ?
-Support open-source development through sponsorship and gain exclusive access to our private forum. Your questions, issues, and feature requests will receive priority attention, plus you'll gain insider access to our roadmap.
-
-<div style="text-align: center;">
-    <iframe src="https://github.com/sponsors/theengs/button" title="Sponsor Theengs" height="32" width="228" style="border: 0; border-radius: 6px;"></iframe>
 </div>
 
-## Products powered by OpenMQTTGateway
+<div class="omg-section">
+  <h2>See it in action</h2>
+  <div class="omg-videos">
+    <a v-for="v in videos" :key="v.id" class="omg-video" :href="`https://www.youtube.com/watch?v=${v.id}`" target="_blank" rel="noopener noreferrer">
+      <img class="no-zoom" :src="`https://img.youtube.com/vi/${v.id}/mqdefault.jpg`" :alt="`${v.title} video by ${v.author}`" loading="lazy" />
+      <span class="omg-video-title">{{ v.title }}</span>
+      <span class="omg-video-author">by {{ v.author }}</span>
+    </a>
+  </div>
+  <p class="omg-caption">In the press:
+    <template v-for="(p, i) in press" :key="p.url"><a :href="p.url" target="_blank" rel="noopener noreferrer">{{ p.name }}</a><span v-if="i < press.length - 1"> · </span></template>
+  </p>
+</div>
 
-### Theengs Bridge, BLE gateway with external antenna
+<div class="omg-section">
+  <h2>Under the hood</h2>
+  <div class="omg-pills">
+    <span v-for="f in functions" :key="f" class="omg-pill">{{ f }}</span>
+  </div>
+</div>
 
-[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.
+<div class="omg-section">
-
+  <h2>Support the project</h2>
-<div style="text-align: center;">
+  <div class="omg-product">
     <a href="https://shop.theengs.io/products/theengs-bridge-esp32-ble-mqtt-gateway-with-ethernet-and-external-antenna" target="_blank" rel="noopener noreferrer">
-    <img src="./img/Theengs-Bridge-ble-gateway.png" alt="Theengs bridge view" style="max-width: 100%; height: auto;">
+      <img src="./img/Theengs-Bridge-ble-gateway.png" alt="Theengs Bridge, BLE to MQTT gateway with Ethernet and external antenna" />
     </a>
+    <div>
+      <h3>Theengs Bridge — ready-to-use BLE gateway</h3>
+      <p>Pre-flashed with OpenMQTTGateway, with an Ethernet port and an external antenna for enhanced BLE range. Every purchase directly funds the project.</p>
+      <a class="omg-cta" href="https://shop.theengs.io/products/theengs-bridge-esp32-ble-mqtt-gateway-with-ethernet-and-external-antenna" target="_blank" rel="noopener noreferrer">Get the Theengs Bridge</a>
+    </div>
+  </div>
+  <p style="margin-top: 24px;">You can also sponsor the development to help keep the project healthy and evolving.</p>
+  <div style="text-align: center;">
+    <iframe src="https://github.com/sponsors/1technophile/button" title="Sponsor 1technophile" height="32" width="228" style="border: 0; border-radius: 6px;"></iframe>
+  </div>
 </div>
 
-### Theengs Plug, BLE gateway and Smart Plug
+<div class="omg-section">
-
+  <p class="omg-disclaimer">The material and information contained in this documentation is for general information purposes only. You should not rely upon it as a basis for making any business, legal or any other decisions. There is no warranty given on this documentation content; if you decide to follow the information and materials given it is at your own risk.</p>
-[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://decoder.theengs.io/devices/devices.html) 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.
-
-<div style="text-align: center;">
-    <a href="https://shop.theengs.io/products/theengs-plug-smart-plug-ble-gateway-and-energy-consumption" target="_blank" rel="noopener noreferrer">
-    <img src="./img/Theengs-Plug-OpenMQTTGateway.png" alt="Theengs plug view" style="max-width: 100%; height: auto;">
-    </a>
 </div>
 
-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)
+<style scoped>
+.omg-section {
+  max-width: 1152px;
+  margin: 0 auto;
+  padding: 24px 24px 0;
+}
+.omg-section h2 {
+  border-top: 1px solid var(--vp-c-divider);
+  padding-top: 24px;
+  margin-bottom: 16px;
+  font-size: 24px;
+  font-weight: 600;
+  letter-spacing: -0.02em;
+}
+.omg-lead {
+  color: var(--vp-c-text-1);
+  max-width: 720px;
+  margin: 0 0 8px;
+}
+.omg-caption {
+  color: var(--vp-c-text-2);
+  font-size: 14px;
+  margin-top: 16px;
+}
+.omg-caption a { color: var(--vp-c-brand-1); }
+.omg-lead a { color: var(--vp-c-brand-1); }
 
-## Media
+/* Use cases grid */
+.omg-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
+  gap: 12px;
+}
+.omg-card {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  background: var(--vp-c-bg-soft);
+  border-radius: 12px;
+  padding: 14px 16px;
+  font-size: 14px;
+  line-height: 1.5;
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+.omg-card:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 6px 16px rgba(0, 0, 0, 0.12);
+}
+.omg-card-icon { font-size: 24px; flex-shrink: 0; }
 
-* [Hackaday - ARDUINO LIBRARY BRINGS RTL_433 TO THE ESP32](https://hackaday.com/2023/01/13/arduino-library-brings-rtl_433-to-the-esp32)
+/* Videos */
-* [CNX Software - 433 MHz is not dead! Using an ESP32 board with LoRa module to talk to 433 MHz sensors](https://www.cnx-software.com/2023/01/14/esp32-board-with-lora-433-mhz-sensors/)
+.omg-videos {
-* [RTL_433 PORTED TO ESP32 MICROCONTROLLERS WITH CC1101 OR SX127X TRANSCEIVER CHIPS](https://www.rtl-sdr.com/rtl_433-ported-to-esp32-microcontrollers-with-cc1101-or-sx127x-transceiver-chips/)
+  display: grid;
-* [Using low-cost wireless sensors in the unlicensed bands](https://lwn.net/Articles/921497/)
+  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
-* [SMART PLUG ESP32 OPENMQTTGATEWAY SERVING AS AN BLE MQTT GATEWAY AND A POWER METER](https://www.electronics-lab.com/smart-plug-esp32-openmqttgateway-serving-as-an-ble-mqtt-gateway-and-a-power-meter/)
+  gap: 20px;
+}
+.omg-video {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  text-decoration: none;
+  color: var(--vp-c-text-1);
+}
+.omg-video img {
+  width: 100%;
+  border-radius: 12px;
+  aspect-ratio: 16 / 9;
+  object-fit: cover;
+  transition: transform 0.2s ease;
+}
+.omg-video:hover img { transform: scale(1.03); }
+.omg-video-title { font-size: 14px; font-weight: 600; margin-top: 8px; }
+.omg-video-author { font-size: 13px; color: var(--vp-c-text-2); }
 
-### Theengs Plug
+/* Function pills */
-[![Theengs Plug video ElektroMaker](https://img.youtube.com/vi/nUwMt9p2U7o/0.jpg)](https://www.youtube.com/watch?v=nUwMt9p2U7o&t=427s)
+.omg-pills {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+.omg-pill {
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 999px;
+  padding: 6px 14px;
+  font-size: 13px;
+  color: var(--vp-c-text-1);
+}
 
-### 433Mhz and BLE
+/* Product card */
-[![433Mhz and BLE gateway video by Andreas Spiess](https://img.youtube.com/vi/_gdXR1uklaY/0.jpg)](https://www.youtube.com/watch?v=_gdXR1uklaY)
+.omg-product {
+  display: flex;
+  align-items: center;
+  gap: 32px;
+  background: var(--vp-c-bg-soft);
+  border-radius: 12px;
+  padding: 24px;
+  flex-wrap: wrap;
+}
+.omg-product > a { flex: 0 1 280px; min-width: 200px; }
+.omg-product img { width: 100%; border-radius: 8px; }
+.omg-product > div { flex: 1 1 300px; }
+.omg-product h3 { margin: 0 0 8px; font-size: 18px; font-weight: 600; }
+.omg-product p { color: var(--vp-c-text-2); margin: 0 0 16px; }
+.omg-cta {
+  display: inline-block;
+  background: var(--vp-c-brand-1);
+  color: var(--vp-c-white, #fff);
+  border-radius: 20px;
+  padding: 8px 20px;
+  font-size: 14px;
+  font-weight: 600;
+  text-decoration: none;
+  transition: background 0.2s ease;
+}
+.omg-cta:hover { background: var(--vp-c-brand-2); }
 
-### BLE
+.omg-disclaimer {
-[![BLE gateway video by Andreas Spiess](https://img.youtube.com/vi/noUROhtf0E0/0.jpg)](https://www.youtube.com/watch?v=noUROhtf0E0)
+  border-top: 1px solid var(--vp-c-divider);
+  padding: 24px 0 32px;
+  color: var(--vp-c-text-3);
+  font-size: 12px;
+  line-height: 1.6;
+}
 
-### 433Mhz
+@media (max-width: 640px) {
-[![RTL_433 video by TECH MIND](https://img.youtube.com/vi/H-JXWbWjJYE/0.jpg)](https://www.youtube.com/watch?v=H-JXWbWjJYE)
+  .omg-pipeline { flex-direction: column; }
-
+  .omg-arrow { transform: rotate(90deg); }
-### LORA
+}
-[![LORA video by Priceless Toolkit](https://img.youtube.com/vi/6DftaHxDawM/0.jpg)](https://www.youtube.com/watch?v=6DftaHxDawM)
+</style>
-
-::: warning Note
-The material and information contained in this documentation is for general information purposes only. You should not rely upon the material or information on this documentation as a basis for making any business, legal or any other decisions. There is no warranty given on this documentation content. If you decide to follow the information and materials given it is at your own risk. I will not be liable for any false, inaccurate, inappropriate or incomplete information presented on this website.
-:::

docs/participate/quick_start.md

@@ -1,11 +1,13 @@
 ---
-title: Quick Start to Develop OpenMQTTGateway
+title: Contributor Quick Start
 permalink: /participate/quick_start.html
 sidebarDepth: 2
 lang: en-US
 ---
 
-# Quick Start to Develop OpenMQTTGateway
+# Contributor Quick Start
+
+Looking to **use** OpenMQTTGateway rather than develop it? Head to the [Getting Started guide](../getting-started.md) instead.
 
 This document helps a new contributor. Maybe this is your first time with:
 

docs/participate/support.md

@@ -11,12 +11,12 @@ If you like the project, you can help in different ways. Choose what fits you be
 - 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).
+- Purchase the [Theengs mobile application](https://app.theengs.io) or the [Theengs Bridge](https://shop.theengs.io).
 - 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.
+Support open-source development through sponsorship, it helps keep the project healthy and evolving.
 
 <div style="text-align: center;">
-    <iframe src="https://github.com/sponsors/theengs/button" title="Sponsor Theengs" height="32" width="228" style="border: 0; border-radius: 6px;"></iframe>
+    <iframe src="https://github.com/sponsors/1technophile/button" title="Sponsor 1technophile" height="32" width="228" style="border: 0; border-radius: 6px;"></iframe>
 </div>

docs/prerequisites/board.md

@@ -6,48 +6,32 @@ aside: false
 
 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.
 
+## Which board do I need?
+
+For the most common use cases, the choice is simple:
+
+|I want to...|Recommended board|Extra hardware|
+|-|-|:-:|
+|Bring Bluetooth sensors into my home automation|Any ESP32 development board|None|
+|Receive RF devices — 433/315/868/915MHz (weather stations, door/PIR sensors...)|LILYGO® LoRa32 V2.1 or Heltec LoRa V2, matching your devices' frequency|None|
+|Send and receive RF remotes and switches (433/315MHz)|ESP32 + SRX882/STX882 or CC1101 modules|[Wiring](../setitup/rf.md)|
+|Control my TV or AC through infrared|ESP32 + IR emitter/receiver|[Wiring](../setitup/ir.md)|
+|Reach far-away sensors with LoRa|LILYGO® LoRa32 or Heltec LoRa board|None|
+|Skip flashing and wiring entirely|[Theengs Bridge](https://shop.theengs.io/), a pre-flashed BLE gateway|None|
+
+::: tip 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 use [Theengs Gateway](https://gateway.theengs.io/), and on a tablet or smartphone the [Theengs App](https://app.theengs.io/).
+:::
+
+## Exploring further
+
 Moreover the gateways capacities can be extended with sensors; DHT, HC SR501, ADC, I2C bus, INA226, MQ2, TEMT6000, TSL2561, BME280/BMP280, HTU21D, AHTx0, DS1820
 or actuators; LED, relays, PWM.
 
-::: tip 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 use [Theengs Gateway](https://gateway.theengs.io/).
-:::
-
-::: 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/).
-:::
-
-[Theengs bridge](https://shop.theengs.io/products/theengs-bridge-esp32-ble-mqtt-gateway-with-ethernet-and-external-antenna) is a powerful 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.
-
-<div style="text-align: center;">
-    <a href="https://shop.theengs.io/products/theengs-bridge-esp32-ble-mqtt-gateway-with-ethernet-and-external-antenna" target="_blank" rel="noopener noreferrer">
-    <img src="/img/Theengs-Bridge-ble-gateway.png" alt="Theengs bridge view" style="max-width: 100%; height: auto;">
-    </a>
-</div>
-
-[Theengs plug](https://shop.theengs.io/products/theengs-plug-smart-plug-ble-gateway-and-energy-consumption) is available flashed with OpenMQTTGateway, and brings the functions below:
-* BLE to MQTT gateway, tens of Bluetooth 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.
-
-<div style="text-align: center;">
-    <a href="https://shop.theengs.io/products/theengs-plug-smart-plug-ble-gateway-and-energy-consumption" target="_blank" rel="noopener noreferrer">
-    <img src="/img/Theengs-Plug-OpenMQTTGateway.png" alt="Theengs plug view" style="max-width: 100%; height: auto;">
-    </a>
-</div>
-
-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)
-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.
-
 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.
 
 <BoardEnvironmentTable 
       boardsUrl="/boards-info.json"
       selectorPath="/upload/board-selector.html"
 />
-

docs/prerequisites/broker.md

@@ -3,6 +3,11 @@ The broker will act as an intermediary between OpenMQTTGateway and your [control
 
 All the events or commands could pass by the broker.
 
+::: tip Recommended setup
+* **You use Home Assistant**: install the **Mosquitto broker add-on** (Settings → Add-ons → Add-on store), enable the MQTT integration, and create a dedicated user for the gateway. This is the path followed by the [Getting Started guide](../getting-started.md).
+* **You don't**: install [Mosquitto](https://mosquitto.org/) on any always-on machine (Raspberry Pi, NAS, server), it is lightweight, open source and well documented.
+:::
+
 There are many choices of brokers, here are some of the most popular:
 * [Mosquitto](https://mosquitto.org/) (Open source)
 * [Moquette](https://moquette-io.github.io/moquette/) (Open source)

docs/prerequisites/devices.md

@@ -1,6 +1,6 @@
 # Devices
 
-Here is an overview of devices supported by OpenMQTTGateway:
+For Bluetooth, the maintained list of supported devices is the [Theengs Decoder compatible devices list](https://decoder.theengs.io/devices/devices.html). For the other technologies, the sections below give an overview of what is supported:
 
 ## For radio frequency devices 
 OpenMQTTGateway can support a wide range of 433mhz/315mhz devices, all the ones with SC5262 / SC5272, HX2262 / HX2272, PT2262 / PT2272, EV1527, RT1527, FP1527, HS1527 chipsets are supported by the RF gateway. Added to that RF2 support Kaku and Pilight an [huge list](https://wiki.pilight.org/devices). 

docs/setitup/actuators.md

@@ -1,11 +1,11 @@
 # Actuators
 ## Compatible parts 
-|Module|Purpose|Where to Buy|
+|Module|Purpose|
-|-|-|-|
+|-|-|
-|LED|Basic led|-|
+|LED|Basic led|
-|FASTLED|RGB Leds management|-|
+|FASTLED|RGB Leds management|
-|BUZZER|-|-|
+|BUZZER|-|
-|RELAY|Switch power circuit|-|
+|RELAY|Switch power circuit|
 
 ## Pinout
 |Module| Boards|

docs/setitup/gsm.md

@@ -1,10 +1,10 @@
 # GSM 2G gateway
 ## Compatible parts
 
-|Module|Purpose|Where to Buy|
+|Module|Purpose|
-|-|-|-|
+|-|-|
-|A6|GSM GPRS module|-|
+|A6|GSM GPRS module|
-|A7|GSM GPRS module with GPS|-|
+|A7|GSM GPRS module with GPS|
 
 ## Hardware setup
 

docs/setitup/ir.md

@@ -1,12 +1,12 @@
 # IR gateway
 ## Compatible parts
-|Module|Purpose|Where to Buy|
+|Module|Purpose|
-|-|-|-|
+|-|-|
-|IR diode|Emitting|-|
+|IR diode|Emitting|
-|IR receiver|Receiving|-|
+|IR receiver|Receiving|
-|transistor 2N2222|Amplify uC signal for the IR diode|-|
+|transistor 2N2222|Amplify uC signal for the IR diode|
-|330 ohms resistor|-|-|
+|330 ohms resistor|-|
-|220 ohms resistor|limit current to LED|-|
+|220 ohms resistor|limit current to LED|
 
 The IR setup can work with bc547 and a 4x3 LED-Matrix.
 

docs/setitup/rf.md

@@ -1,4 +1,4 @@
-# RF gateway (433mhz/315mhz)
+# RF gateway (433/315/868/915MHz)
 
 ## Protocols, modules and library
 
@@ -21,13 +21,13 @@ If you want to try the RTL_433 module with a combination or a board outside of t
 Heltec LORA V3 is not compatible with RTL_433 library as it is based on an SX1262 module.
 
 ## Assembly/soldering required parts
-|Module|Purpose|Compatible modules|Receiver Switching|Where to Buy|
+|Module|Purpose|Compatible modules|Receiver Switching|
-|-|-|-|-|-|
+|-|-|-|-|
-|SRX882 or SRX882S (recommended)|433Mhz Receiver|RF(RCSwitch), RF2(KaKu), Pilight|Supported|-|
+|SRX882 or SRX882S (recommended)|433Mhz Receiver|RF(RCSwitch), RF2(KaKu), Pilight|Supported|
-|STX882 (recommended)|433Mhz Transmitter|RF(RCSwitch), RF2(KaKu), Pilight|Supported|-|
+|STX882 (recommended)|433Mhz Transmitter|RF(RCSwitch), RF2(KaKu), Pilight|Supported|
-|CC1101|433Mhz Transceiver|[RTL_433](../use/rf#supported-decoders), RF(RCSwitch), RF2(KaKu), Pilight|Supported|-|
+|CC1101|433Mhz Transceiver|[RTL_433](../use/rf#supported-decoders), RF(RCSwitch), RF2(KaKu), Pilight|Supported|
-|SX1276/SX1278|433Mhz Transceiver|[RTL_433](../use/rf#supported-decoders)|Not Supported|-|
+|SX1276/SX1278|433Mhz Transceiver|[RTL_433](../use/rf#supported-decoders)|Not Supported|
-|LilyGo/Heltec|433Mhz Transceiver|[RTL_433](../use/rf#supported-decoders)|Not Supported|-|
+|LilyGo/Heltec|433Mhz Transceiver|[RTL_433](../use/rf#supported-decoders)|Not Supported|
 
 ### SRX STX Pinout
 |Board| Receiver Pin| Emitter Pin|
@@ -72,9 +72,9 @@ When **all** these variables are defined, OpenMQTTGateway will use your custom p
 ![Addon_RF](../img/OpenMQTTgateway_ESP32_Addon_RF.png)
 
 ## ESP8266 Hardware setup
-The default receiver pin is D2 (gpio 4). Avoid D3 (gpio 0): it is a boot strapping pin, a receiver holding it low at reset forces the ESP8266 into flash mode and the board never starts.
+If the gateway works only when serial monitor is connected don't use D3 use D2 instead (gpio 4) and modify config_RF.h accordingly.
 
-With SRX882 some users reported issues on D2, use D1 instead in this case and modify config_RF.h accordingly.
+With SRX882 some users reported that D3 is not working use D1 instead in this case and modify config_RF.h accordingly.
 
 ![Addon_RF](../img/OpenMQTTgateway_ESP8266_Addon_RF.png)
 

docs/setitup/sensors.md

@@ -1,21 +1,21 @@
 # Sensors
 ## Compatible sensors
-|Module|Purpose|Where to Buy|
+|Module|Purpose|
-|-|-|-|
+|-|-|
-|DHT11|Temperature, Humidity|-|
+|DHT11|Temperature, Humidity|
-|DHT22|Temperature, Humidity|-|
+|DHT22|Temperature, Humidity|
-|HCSR501|PIR|-|
+|HCSR501|PIR|
-|BH1750|Digital light|-|
+|BH1750|Digital light|
-|BME280|Temperature, Humidity, Pressure|-|
+|BME280|Temperature, Humidity, Pressure|
-|BMP280|Temperature, Pressure|-|
+|BMP280|Temperature, Pressure|
-|C-37, YL-83, HM-RD|Leak, Water|-|
+|C-37, YL-83, HM-RD|Leak, Water|
-|HTU21|Temperature, Humidity|-|
+|HTU21|Temperature, Humidity|
-|GPIO Input|Inputs|-|
+|GPIO Input|Inputs|
-|GPIO KeyCode|Keycode|-|
+|GPIO KeyCode|Keycode|
-|INA226|Current, Voltage|-|
+|INA226|Current, Voltage|
-|MQ2|Gas (flammable)|-|
+|MQ2|Gas (flammable)|
-|TEMT6000|Luminosity|-|
+|TEMT6000|Luminosity|
-|TSL2561|Luminosity|-|
+|TSL2561|Luminosity|
 
 ## Pinout
 |Module|Arduino Pin| ESP8266 Pin|ESP32 Pin|

docs/upload/board-selector.md

@@ -1,3 +1,5 @@
 <FlashEnvironmentSelector
   boardsUrl="/boards-info.json"
   firmwareBaseUrl="firmware_build/" />
+
+<small style="color: var(--vp-c-text-3);">Board photos courtesy of their manufacturers. ESP32 Feather photo © <a href="https://www.adafruit.com/product/3405">Adafruit Industries</a>, <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA</a>.</small>

docs/upload/gitpod.md

@@ -1,18 +0,0 @@
-# (Option 4) Build from the web
-
-To build OpenMQTTGateway from the web and download the binary, follow these steps:
-
-1. Use Gitpod by clicking on the link below:
-[https://gitpod.io#https://github.com/1technophile/OpenMQTTGateway/tree/development](https://gitpod.io#https://github.com/1technophile/OpenMQTTGateway/tree/development)
-
-2. This will generate a development environment in your browser and install [platformio](https://platformio.org/) as a build environment.
-
-3. A first build for `esp32dev-ble` will be launched automatically. To modify the environment configuration, go to the environments.ini file in the root folder and launch the command like the one shown at the bottom of the image below:
-`platformio run -e <environment name>`
-
-![Gitpod build success](../img/OpenMQTTGateway-Build-gitpod-env.png)
-
-4. Wait for the server to build the binary. Once you see [SUCCESS], you can go to `.pio/build/<environment name>` and download `firmware.bin` and `partitions.bin` by right-clicking on each and selecting "Download."
-![Gitpod build download](../img/OpenMQTTGateway-Build-gitpod.png)
-
-5. Finally, follow [Option 2](binaries.md) to upload the binary.

docs/upload/index.md

@@ -1,79 +1,159 @@
-# Upload
+# 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.
+Getting OpenMQTTGateway onto your board takes three steps, whichever method you pick:
-
+
-<p align="center">
+<div class="omg-journey">
-  <img src="../img/upload.png" alt="Firmware upload process">
+  <div class="omg-step">
-</p>
+    <span class="omg-step-num">1</span>
-
+    <strong>Flash the firmware</strong>
-## Choosing Your Upload Method
+    <span class="omg-step-sub">pick a method below</span>
-
+  </div>
-### Web-Based Installation
+  <span class="omg-step-arrow">→</span>
-
+  <div class="omg-step">
-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.
+    <span class="omg-step-num">2</span>
-
+    <strong>Configure WiFi &amp; MQTT</strong>
-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.
+    <span class="omg-step-sub">through the <a href="./portal.html">portal</a></span>
-
+  </div>
-### Ready-to-Go Binary Installation
+  <span class="omg-step-arrow">→</span>
-
+  <div class="omg-step">
-[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).
+    <span class="omg-step-num">3</span>
-
+    <strong>Verify</strong>
-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.
+    <span class="omg-step-sub">gateway appears on your <a href="../getting-started.html#step-4-check-that-it-works">broker &amp; controller</a></span>
-
+  </div>
-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.
+</div>
-
+
-### Custom Build and Upload
+## Choose your installation method
-
+
-[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.
+<div class="omg-methods">
-
+  <a class="omg-method" href="./web-install.html">
-[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.
+    <span class="omg-method-badge">Easiest</span>
-
+    <h3>1. Web installer</h3>
-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.
+    <p><strong>Choose this if</strong> you want the fastest path: flash directly from your browser, nothing to install.</p>
-
+    <p class="omg-method-req">Needs Chrome, Edge or Opera and a data USB cable. Standard configurations only.</p>
-### Browser-Based Building with Gitpod
+  </a>
-
+  <a class="omg-method" href="./binaries.html">
-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.
+    <h3>2. Ready-to-go binaries</h3>
-
+    <p><strong>Choose this if</strong> you prefer a desktop flashing tool (esptool.py, Espressif Flash Download Tool), or web flashing doesn't work for you.</p>
-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.
+    <p class="omg-method-req">Same pre-built firmware as the web installer, flashed from your computer.</p>
-
+  </a>
-## Configuring Network and MQTT Settings
+  <a class="omg-method" href="./builds.html">
-
+    <h3>3. Build from source</h3>
-After flashing firmware, configure network connectivity and MQTT broker settings using either runtime or build-time approaches.
+    <p><strong>Choose this if</strong> you need custom pin assignments, module combinations, or credentials embedded at build time.</p>
-
+    <p class="omg-method-req">Needs <a href="https://platformio.org/">PlatformIO</a>. Full control over the configuration.</p>
-### Runtime Configuration Portal
+  </a>
-
+</div>
-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).
+
-
+|                          | Web installer | Binaries | From source |
-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.
+|--------------------------|:---:|:---:|:---:|
-
+| No software to install   | ✅ | ❌ | ❌ |
-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.
+| Custom configuration     | ❌ | ❌ | ✅ |
-
+| Difficulty               | Easiest | Easy | Advanced |
-### Build-Time Configuration
+
-
+## After flashing: configure your gateway
-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.
+
-
+However you flashed, a freshly installed gateway starts its own WiFi access point (named `OpenMQTTGateway` or starting with `OMG_`). Connect to it and the [configuration portal](portal.md) lets you set your WiFi network, MQTT broker, and optional security settings — no rebuild needed.
-## Advanced Configuration Options
+
-
+If you build from source you can alternatively [embed the network and MQTT settings at build time](builds.md), so the gateway connects automatically on first boot.
-Beyond basic connectivity, OpenMQTTGateway supports several [advanced features](advanced-configuration.md) that enhance security and integration capabilities.
+
-
+## Going further
-### Secure MQTT Connections
+
-
+* [Advanced configuration](advanced-configuration.md) — TLS-secured MQTT connections, certificates, OTA updates.
-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.
+* [Home Assistant integration](../integrate/home_assistant.md) — auto-discovery is enabled by default; your gateway and sensors appear automatically.
-
+* [Gateway configuration](../use/gateway.md) — MQTT topic structure and runtime commands per module.
-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.
+
-
+Stuck? Check the [troubleshooting page](troubleshoot.md), or ask on the [community forum](https://community.openmqttgateway.com).
-### Home Assistant Auto-Discovery
+
-
+<style scoped>
-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.
+.omg-journey {
-
+  display: flex;
-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.
+  align-items: stretch;
-
+  gap: 8px;
-### Topic Customization
+  margin: 24px 0;
-
+  flex-wrap: wrap;
-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.
+}
-
+.omg-step {
-## Next Steps
+  flex: 1 1 150px;
-
+  display: flex;
-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.
+  flex-direction: column;
-
+  align-items: center;
-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.
+  text-align: center;
+  gap: 4px;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 12px;
+  padding: 16px 12px;
+}
+.omg-step-num {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border-radius: 50%;
+  background: var(--vp-c-brand-1);
+  color: var(--vp-c-white, #fff);
+  font-weight: 700;
+  font-size: 14px;
+}
+.omg-step-sub {
+  color: var(--vp-c-text-2);
+  font-size: 13px;
+}
+.omg-step-arrow {
+  align-self: center;
+  color: var(--vp-c-brand-1);
+  font-size: 20px;
+  font-weight: 700;
+}
+.omg-methods {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+  gap: 16px;
+  margin: 16px 0 24px;
+}
+.omg-method {
+  position: relative;
+  display: block;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 12px;
+  padding: 20px;
+  text-decoration: none !important;
+  color: var(--vp-c-text-1);
+  transition: border-color 0.2s ease, transform 0.2s ease;
+}
+.omg-method:hover {
+  border-color: var(--vp-c-brand-1);
+  transform: translateY(-2px);
+}
+.omg-method h3 {
+  margin: 0 0 8px;
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--vp-c-brand-1);
+}
+.omg-method p {
+  margin: 0 0 8px;
+  font-size: 14px;
+  line-height: 1.5;
+}
+.omg-method-req {
+  color: var(--vp-c-text-2);
+  font-size: 13px !important;
+}
+.omg-method-badge {
+  position: absolute;
+  top: -10px;
+  right: 12px;
+  background: var(--vp-c-brand-1);
+  color: var(--vp-c-white, #fff);
+  border-radius: 10px;
+  padding: 2px 10px;
+  font-size: 12px;
+  font-weight: 600;
+}
+@media (max-width: 640px) {
+  .omg-journey { flex-direction: column; }
+  .omg-step-arrow { transform: rotate(90deg); }
+}
+</style>

docs/upload/troubleshoot.md

@@ -1,7 +1,7 @@
 # Troubleshooting
 
 ## Compilation/build error
-This badge [![Build Status](https://github.com/1technophile/OpenMQTTGateway/workflows/Build/badge.svg?branch=master)](https://github.com/1technophile/OpenMQTTGateway/actions?query=branch%3Amaster+workflow%3ABuild) show you the state of the compilation of the master and this one [![Build Status](https://github.com/1technophile/OpenMQTTGateway/workflows/Build/badge.svg?branch=development)](https://github.com/1technophile/OpenMQTTGateway/actions?query=branch%3Adevelopment+workflow%3ABuild) for the development branch.
+This badge [![Build Status](https://github.com/1technophile/OpenMQTTGateway/workflows/Build/badge.svg?branch=development)](https://github.com/1technophile/OpenMQTTGateway/actions?query=branch%3Adevelopment+workflow%3ABuild) show you the state of the compilation of the development branch, from which the releases are made.
 If you see a green badge this means that the code compilation is OK with the configuration given in the `docs/platformio.ini`.
 Check your environment, boards , libraries before submitting an issue or a question.
 

docs/upload/web-install.md

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

docsgen/boards-info.js

@@ -214,11 +214,27 @@ function collectBoardsInformations(sections, { includeTests = false } = {}) {
     return rows;
 }
 
+// pio project config resolves extra_configs, which pulls in user-specific
+// files like prod_env.ini; only environments declared in environments.ini
+// belong in the published boards list.
+function publicEnvironmentNames() {
+    const fs = require('fs');
+    const path = require('path');
+    const ini = fs.readFileSync(path.resolve(__dirname, '..', 'environments.ini'), 'utf8');
+    const names = new Set();
+    for (const match of ini.matchAll(/^\[env:([^\]]+)\]/gm)) {
+        names.add(match[1].trim());
+    }
+    return names;
+}
+
 function loadBoardsInfo(options = {}) {
     const { includeTests = false } = options;
     const config = rowConfigFromPlatformIO();
     const sections = convertJsonToSections(config);
-    return collectBoardsInformations(sections, { includeTests });
+    const rows = collectBoardsInformations(sections, { includeTests });
+    const publicEnvs = publicEnvironmentNames();
+    return rows.filter(row => publicEnvs.has(row.Environment));
 }
 
 function ensureDir(dir) {

environments.ini

@@ -24,6 +24,7 @@ board_build.ldscript = eagle.flash.1m64.ld ;this frees more space for firmware u
 ;extra_scripts = scripts/compressFirmware.py ;uncomment this to compress the firmware. This helps updating e.g. Sonoff RF Bridge via OTA flash by saving space for the uploaded firmware.
 custom_description = RF gateway for the Sonoff RF Bridge relying on the internal decoder
 custom_hardware = RFBridge v1
+custom_img = img/boards/sonoff-rf-bridge.jpg
 
 [env:rfbridge-direct]
 platform = ${com.esp8266_platform}
@@ -48,6 +49,7 @@ board_build.ldscript = eagle.flash.1m64.ld ;this frees more space for firmware u
 ;extra_scripts = scripts/compressFirmware.py ;uncomment this to compress the firmware. This helps updating e.g. Sonoff RF Bridge via OTA flash by saving space for the uploaded firmware.
 custom_description = 'RF gateway for the Sonoff RF Bridge requiring direct hack, relying on ESPilight library, <a href="https://1technophile.blogspot.com/2019/04/sonoff-rf-bridge-pilight-or-how-to.html" target="_blank">tutorial</a>.'
 custom_hardware = RFBridge v1
+custom_img = img/boards/sonoff-rf-bridge.jpg
 
 [env:theengs-bridge]
 platform = ${com.esp32_platform}
@@ -88,6 +90,7 @@ build_flags =
   '-mfix-esp32-psram-cache-strategy=memw'
 custom_description = 'BLE gateway with external antenna and Ethernet/WiFi connectivity, <a href="https://tbridge01.theengs.io/" target="_blank">user guide</a>'
 custom_hardware = Theengs Bridge gateway ethernet
+custom_img = img/Theengs-Bridge-ble-gateway.png
 
 [env:theengs-bridge-v11]
 platform = ${com.esp32_platform}
@@ -289,6 +292,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP32_RF"'
   '-DvalueAsATopic=true'
 custom_description = RF gateway using RCSwitch library
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32dev-pilight]
 platform = ${com.esp32_platform}
@@ -306,6 +310,7 @@ build_flags =
   '-DZgatewayPilight="Pilight"'
   '-DGateway_Name="OMG_ESP32_Pilight"'
 custom_description = RF gateway using ESPilight library
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32dev-pilight-cc1101]
 platform = ${com.esp32_platform}
@@ -325,6 +330,7 @@ build_flags =
   '-DZradioCC1101="CC1101"'
   '-DGateway_Name="OMG_ESP32_Pilight-CC1101"'
 custom_description = Gateway using ESPilight library only, need CC1101
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32dev-somfy-cc1101]
 platform = ${com.esp32_platform}
@@ -341,6 +347,7 @@ build_flags =
   '-DZradioCC1101="CC1101"'
   '-DGateway_Name="OMG_ESP32_Somfy-CC1101"'
 custom_description = Gateway using Somfy Remote library, need CC1101
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32dev-pilight-somfy-cc1101]
 platform = ${com.esp32_platform}
@@ -362,6 +369,7 @@ build_flags =
   '-DZradioCC1101="CC1101"'
   '-DGateway_Name="OMG_ESP32_Pilight-Somfy-CC1101"'
 custom_description = Gateway using Somfy Remote and ESPilight library, need CC1101
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32dev-weatherstation]
 platform = ${com.esp32_platform}
@@ -376,6 +384,7 @@ build_flags =
   '-DZgatewayWeatherStation="WeatherStation"'
   '-DGateway_Name="OMG_ESP32_WeatherStation"'
 custom_description = Gateway to retrieve weather station data Ventus W174/W132 (tested), Auriol H13726, Hama EWS 1500, Meteoscan W155/W160 using WeatherStationDataRx
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32dev-gf-sun-inverter]
 platform = ${com.esp32_platform}
@@ -391,6 +400,7 @@ build_flags =
   '-DZgatewayGFSunInverter="GFSunInverter"'
   '-DGateway_Name="OMG_ESP32_GFSunInverter"'
 custom_description = RS232 reading of GridFree Sun Inverter
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32dev-ir]
 platform = ${com.esp32_platform}
@@ -405,6 +415,7 @@ build_flags =
   '-DZgatewayIR="IR"'
   '-DGateway_Name="OMG_ESP32_IR"'
 custom_description = Infrared (Emitting and receiving) using IRremoteESP8266
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32dev-ble]
 platform = ${com.esp32_platform}
@@ -422,6 +433,7 @@ build_flags =
   '-DLED_PIN_ON=0'
   '-DGateway_Name="OMG_ESP32_BLE"'
 custom_description = Regular BLE gateway with adaptive scanning activated, automatically adapts the scan parameters depending on your devices
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32dev-ble-broker]
 platform = ${com.esp32_platform}
@@ -440,6 +452,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP32_BLE"'
   '-DMQTT_BROKER_MODE=true'
 custom_description = MQTT Broker with BLE gateway with adaptive scanning activated, automatically adapts the scan parameters depending on your devices
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32dev-ble-mqtt-undecoded]
 platform = ${com.esp32_platform}
@@ -458,6 +471,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP32_BLE"'
   '-DMQTTDecodeTopic="undecoded"'
 custom_description = BLE gateway with the decoding offloaded to Theengs Gateway
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32dev-ble-aws]
 platform = ${com.esp32_platform}
@@ -484,6 +498,7 @@ build_flags =
   '-DMQTT_PASS=""'
   '-DAWS_IOT=true'
 custom_description = BLE gateway with AWS integration capability
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32feather-ble]
 platform = ${com.esp32_platform}
@@ -502,6 +517,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP32_FTH_BLE"'
 custom_description =  BLE Gateway
 custom_hardware = ESP32 Feather Adafruit
+custom_img = img/boards/esp32-feather.jpg
 
 [env:esp32-lolin32lite-ble]
 platform = ${com.esp32_platform}
@@ -532,6 +548,7 @@ build_flags =
 ;  '-Dwifi_password="WIFI_PASSWORD"'
 custom_description = 'Suitable for low power with BLE gateway, <a href="https://1technophile.blogspot.com/2021/04/low-power-esp32-ble-gateway.html" target="_blank">tutorial</a>'
 custom_hardware = LOLIN 32 Lite
+custom_img = img/boards/lolin32-lite.jpg
 
 [env:esp32-olimex-gtw-ble-eth]
 platform = ${com.esp32_platform}
@@ -552,6 +569,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP32_OLM_GTWE"'
 custom_description = BLE gateway using ethernet or wifi
 custom_hardware = OLIMEX ESP32 Gateway
+custom_img = img/boards/olimex-esp32-gateway.jpg
 
 [env:esp32-olimex-gtw-ble-poe]
 platform = ${com.esp32_platform}
@@ -569,6 +587,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP32_OLM_POE"'
 custom_description = BLE gateway using ethernet, need to be configured through PIO
 custom_hardware = OLIMEX ESP32 Gateway with POE
+custom_img = img/boards/olimex-esp32-poe.jpg
 
 [env:esp32-olimex-gtw-ble-poe-iso]
 platform = ${com.esp32_platform}
@@ -586,6 +605,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP32_OLM_POE"'
 custom_description = BLE gateway using ethernet, need to be configured through PIO
 custom_hardware = OLIMEX ESP32 Gateway with POE and ISO
+custom_img = img/boards/olimex-esp32-poe-iso.jpg
 
 [env:esp32-wt32-eth01-ble-eth]
 platform = ${com.esp32_platform}
@@ -606,6 +626,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP32_WT32-ETH01"'
 custom_description = BLE gateway using ethernet, need to be configured through PIO
 custom_hardware = WT32
+custom_img = img/boards/wt32-eth01.jpg
 
 [env:esp32-olimex-gtw-ble-wifi]
 platform = ${com.esp32_platform}
@@ -625,6 +646,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP32_OLM_GTWW"'
 custom_description = BLE gateway using wifi
 custom_hardware = OLIMEX ESP32 Gateway
+custom_img = img/boards/olimex-esp32-gateway.jpg
 
 [env:esp32-m5stick-ble]
 platform = espressif32@6.1.0
@@ -648,6 +670,7 @@ build_flags =
 board_upload.speed = 921600
 custom_description = Expandable module with BLE gateway, display, and little IR emitter
 custom_hardware = M5Stick Grey
+custom_img = img/boards/m5stick.webp
 
 [env:esp32-m5stack-ble]
 platform = espressif32@6.1.0
@@ -672,6 +695,7 @@ build_flags =
 board_upload.speed = 921600
 custom_description = Expandable module with BLE gateway and display
 custom_hardware = M5Stack Core
+custom_img = img/boards/m5stack-core.webp
 
 [env:esp32-m5tough-ble]
 platform = espressif32@6.1.0
@@ -690,6 +714,7 @@ build_flags =
 board_upload.speed = 921600
 custom_description = Expandable module with BLE gateway and display, suitable for outdoor
 custom_hardware = M5Tough rugged
+custom_img = img/boards/m5tough.webp
 
 [env:esp32-m5stick-c-ble]
 platform = espressif32@6.1.0
@@ -720,6 +745,7 @@ build_flags =
 board_upload.speed = 1500000
 custom_description = Expandable module with BLE gateway, display, and little IR emitter
 custom_hardware = M5Stick C
+custom_img = img/boards/m5stick-c.webp
 
 [env:esp32-m5stick-cp-ble]
 platform = espressif32@6.1.0
@@ -750,6 +776,7 @@ build_flags =
 board_upload.speed = 1500000
 custom_description = Expandable module with BLE gateway, display, and little IR emitter
 custom_hardware = M5Stick CP
+custom_img = img/boards/m5stick-c-plus.webp
 
 [env:esp32-m5atom-matrix]
 platform = ${com.esp32_platform}
@@ -781,6 +808,7 @@ build_flags =
 board_upload.speed = 1500000
 custom_description = Compact enclosure ESP32 with BLE gateway
 custom_hardware = M5 ATOM Matrix
+custom_img = img/boards/m5atom-matrix.webp
 
 [env:esp32-m5atom-lite]
 platform = ${com.esp32_platform}
@@ -807,6 +835,7 @@ build_flags =
 board_upload.speed = 1500000
 custom_description = Compact enclosure ESP32 with BLE gateway
 custom_hardware = M5 ATOM Lite
+custom_img = img/boards/m5atom-lite.webp
 
 [env:esp32doitv1-aithinker-r01-sx1278]
 platform = espressif32@6.1.0
@@ -858,6 +887,7 @@ board_upload.speed = 921600
 board_upload.port = /dev/cu.usbserial-0001
 board_monitor.speed = 921600
 board_monitor.port = /dev/cu.usbserial-0001
+custom_img = img/boards/esp32doitv1.jpg
 
 [env:esp32doitv1-aithinker-r01-sx1278-hcsr501-test]
 extends = env:esp32doitv1-aithinker-r01-sx1278
@@ -926,6 +956,7 @@ build_flags =
 ;  '-DRADIOLIB_DEBUG=true'
 ;  '-DRADIOLIB_VERBOSE=true'
 custom_description = Gateway using RTL_433_ESP library, need CC1101
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32dev-rtl_433-fsk]
 platform = espressif32@6.1.0
@@ -970,6 +1001,7 @@ build_flags =
 ;  '-DRADIOLIB_DEBUG=true'
 ;  '-DRADIOLIB_VERBOSE=true'
 custom_description = Gateway using RTL_433_ESP library and RadioLib with FSK modulation (beta), need CC1101
+custom_img = img/boards/esp32dev.jpg
 
 [env:heltec-rtl_433]
 platform = espressif32@6.1.0
@@ -999,6 +1031,7 @@ build_flags =
 ;  '-DDISPLAY_METRIC=false'
 custom_description = Gateway using RTL_433_ESP and RadioLib
 custom_hardware = ESP32 HELTEC LORA32 V2
+custom_img = img/boards/heltec-wifi-lora-32.png
 
 [env:heltec-rtl_433-fsk]
 platform = espressif32@6.1.0
@@ -1032,6 +1065,7 @@ build_flags =
 ;  '-DDISPLAY_METRIC=false'
 custom_description = Gateway using RTL_433_ESP and RadioLib with FSK modulation (beta)
 custom_hardware = ESP32 HELTEC LORA32 V2
+custom_img = img/boards/heltec-wifi-lora-32.png
 
 [env:heltec-ble]
 platform = ${com.esp32_platform}
@@ -1057,6 +1091,7 @@ build_flags =
 ;  '-DDISPLAY_METRIC=false'
 custom_description = Heltec BLE gateway with adaptive scanning activated, automatically adapts the scan parameters depending on your devices
 custom_hardware = ESP32 HELTEC LORA32 V2
+custom_img = img/boards/heltec-wifi-lora-32.png
 
 [env:lilygo-rtl_433]
 platform = espressif32@6.1.0
@@ -1086,6 +1121,7 @@ build_flags =
 ;  '-DDISPLAY_METRIC=false'
 custom_description = For ESP32, Gateway using RTL_433_ESP and RadioLib
 custom_hardware = ESP32 LILYGO LoRa32 V2.1
+custom_img = img/boards/lilygo-lora32-v21.jpg
 
 [env:lilygo-rtl_433-fsk]
 platform = espressif32@6.1.0
@@ -1119,6 +1155,7 @@ build_flags =
 ;  '-DDISPLAY_METRIC=false'
 custom_description = For ESP32, Gateway using RTL_433_ESP and RadioLib with FSK modulation (beta)
 custom_hardware = ESP32 LILYGO LoRa32 V2.1
+custom_img = img/boards/lilygo-lora32-v21.jpg
 
 [env:lilygo-t3-s3-rtl_433]
 platform = espressif32@6.10.0
@@ -1165,6 +1202,7 @@ build_flags =
   '-DRF_MODULE_DIO5=36'
 custom_description = For ESP32, Gateway using RTL_433_ESP and RadioLib with FSK modulation (beta)
 custom_hardware = ESP32 LILYGO T3-S3 SX1276 v1.0
+custom_img = img/boards/lilygo-t3-s3.jpg
 
 [env:lilygo-t3-s3-rtl_433-fsk]
 platform = espressif32@6.10.0
@@ -1215,6 +1253,7 @@ build_flags =
   '-DRF_MODULE_DIO5=36'
 custom_description = For ESP32, Gateway using RTL_433_ESP and RadioLib with FSK modulation (beta)
 custom_hardware = ESP32 LILYGO T3-S3 SX1276 v1.0
+custom_img = img/boards/lilygo-t3-s3.jpg
 
 [env:lilygo-ble]
 platform = ${com.esp32_platform}
@@ -1240,6 +1279,7 @@ build_flags =
 ;  '-DDISPLAY_METRIC=false'
 custom_description = LilyGo BLE gateway with adaptive scanning activated, automatically adapts the scan parameters depending on your devices
 custom_hardware = ESP32 LILYGO LoRa32 V2.1
+custom_img = img/boards/lilygo-lora32-v21.jpg
 
 [env:esp32dev-multi_receiver]
 platform = espressif32@6.1.0
@@ -1266,6 +1306,7 @@ build_flags =
   '-DRF_MODULE_GDO2=27'   ; CC1101 pin GDO2
 ;  '-DRF_MODULE_INIT_STATUS=true'    ; Display transceiver config during startup
 custom_description = Multi RF library with the possibility to switch between RTL_433_ESP, NewRemoteSwitch and RCSwitch, need CC1101
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32dev-multi_receiver-pilight]
 platform = ${com.esp32_platform}
@@ -1296,6 +1337,7 @@ build_flags =
   '-DRF_MODULE_GDO2=27'   ; CC1101 pin GDO2
 ;  '-DRF_MODULE_INIT_STATUS=true'    ; Display transceiver config during startup
 custom_description = Multi RF library with the possibility to switch between ESPilight, NewRemoteSwitch and RCSwitch, need CC1101
+custom_img = img/boards/esp32dev.jpg
 
 [env:tinypico-ble]
 platform = ${com.esp32_platform}
@@ -1313,6 +1355,7 @@ build_flags =
 board_build.flash_mode = dio
 custom_description = BLE gateway
 custom_hardware = ESP32 TinyPICO
+custom_img = img/boards/tinypico.jpg
 
 [env:ttgo-lora32-v1]
 platform = ${com.esp32_platform}
@@ -1335,6 +1378,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP32_LORA"'
 custom_description = LORA communication using arduino-LoRA configurable frequency
 custom_hardware= ESP32 TTGO LORA V1
+custom_img = img/boards/ttgo-lora32-v1.jpg
 
 [env:ttgo-lora32-v21]
 platform = ${com.esp32_platform}
@@ -1362,6 +1406,7 @@ build_flags =
 ;  '-DDISPLAY_METRIC=false'
 custom_description = For ESP32, Gateway using LORA
 custom_hardware = ESP32 LILYGO LoRa32 V2.1
+custom_img = img/boards/lilygo-lora32-v21.jpg
 
 [env:ttgo-t-beam]
 # See version pinout differences here
@@ -1394,6 +1439,7 @@ build_flags =
   '-DTimeBetweenReadingADC=60000'
 custom_description = BLE gateway with battery holder
 custom_hardware = TTGO T BEAM
+custom_img = img/boards/ttgo-t-beam.jpg
 
 [env:heltec-wifi-lora-32]  ; Heltec ESP32 Board with SSD1306 display
 platform = ${com.esp32_platform}
@@ -1425,6 +1471,7 @@ custom_description = LORA communication using arduino-LoRA
 custom_hardware = ESP32 HELTEC LORA32
 
 ; For testing only, not for production use
+custom_img = img/boards/heltec-wifi-lora-32.png
 [env:shelly-plus1]
 platform = ${com.esp32_solo_platform}
 board = esp32-solo1
@@ -1457,6 +1504,7 @@ build_flags =
   '-DGATEWAY_MODEL="SPLUS1"'
 custom_description = BLE, Relay control, Switch
 custom_hardware = Shelly Plus 1
+custom_img = img/boards/shelly-plus1.jpg
 
 [env:nodemcuv2-all-test]
 platform = ${com.esp8266_platform}
@@ -1545,6 +1593,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP8266_2G"'
 board_build.flash_mode = dout
 custom_description = SMS gateway, need A6/A7 GSM module
+custom_img = img/boards/nodemcuv2.jpg
 
 [env:nodemcuv2-ir]
 platform = ${com.esp8266_platform}
@@ -1560,6 +1609,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP8266_IR"'
 board_build.flash_mode = dout
 custom_description = Infrared gateway using IRremoteESP8266
+custom_img = img/boards/nodemcuv2.jpg
 
 [env:nodemcuv2-serial]
 platform = ${com.esp8266_platform}
@@ -1574,6 +1624,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP8266_SERIAL"'
 board_build.flash_mode = dout
 custom_description = SERIAL gateway
+custom_img = img/boards/nodemcuv2.jpg
 
 [env:avatto-bakeey-ir]
 platform = ${com.esp8266_platform}
@@ -1614,6 +1665,7 @@ build_flags =
   '-DvalueAsATopic=true'
 board_build.flash_mode = dout
 custom_description = The historic RF gateway using RCSwitch library
+custom_img = img/boards/nodemcuv2.jpg
 
 [env:nodemcuv2-rf-cc1101]
 platform = ${com.esp8266_platform}
@@ -1632,6 +1684,7 @@ build_flags =
   '-DvalueAsATopic=true'
 board_build.flash_mode = dout
 custom_description = RF gateway using RCSwitch library with CC1101
+custom_img = img/boards/nodemcuv2.jpg
 
 [env:nodemcuv2-somfy-cc1101]
 platform = ${com.esp8266_platform}
@@ -1649,6 +1702,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP8266_Somfy-CC1101"'
 board_build.flash_mode = dout
 custom_description = Somfy RF gateway using Somfy Remote library, need CC1101
+custom_img = img/boards/nodemcuv2.jpg
 
 [env:manual-wifi-test]
 platform = ${com.esp8266_platform}
@@ -1696,6 +1750,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP8266_RF2"'
 board_build.flash_mode = dout
 custom_description = KAKU RF gateway using NewRemoteSwitch library
+custom_img = img/boards/nodemcuv2.jpg
 
 [env:nodemcuv2-rf2-cc1101]
 platform = ${com.esp8266_platform}
@@ -1713,6 +1768,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP8266_RF2-CC1101"'
 board_build.flash_mode = dout
 custom_description = KAKU RF gateway using NewRemoteSwitch library, need CC1101
+custom_img = img/boards/nodemcuv2.jpg
 
 [env:nodemcuv2-pilight]
 platform = ${com.esp8266_platform}
@@ -1729,6 +1785,7 @@ build_flags =
   '-fcommon'
 board_build.flash_mode = dout
 custom_description = Gateway using ESPilight without the need of CC1101
+custom_img = img/boards/nodemcuv2.jpg
 
 [env:nodemcuv2-weatherstation]
 platform = ${com.esp8266_platform}
@@ -1744,6 +1801,7 @@ build_flags =
   '-DGateway_Name="OMG_ESP8266_RF3"'
 board_build.flash_mode = dout
 custom_description = RF gateway using WeatherStationDataRx library
+custom_img = img/boards/nodemcuv2.jpg
 
 [env:sonoff-basic]
 platform = ${com.esp8266_platform}
@@ -1766,6 +1824,7 @@ build_flags =
 board_build.flash_mode = dout
 custom_description = Basic Sonoff wifi relay
 custom_hardware = Sonoff Basic R1, R2
+custom_img = img/boards/sonoff-basic.jpg
 
 [env:sonoff-basic-rfr3]
 platform = ${com.esp8266_platform}
@@ -1791,6 +1850,7 @@ build_flags =
 board_build.flash_mode = dout
 custom_description = 'Wifi relay and RF receiver using RCSwitch library, <a href="https://1technophile.blogspot.com/2019/08/new-sonoff-rfr3-as-433tomqtt-gateway.html" target="_blank">tutorial</a>'
 custom_hardware = 'Sonoff Basic RFR3, <a href="https://1technophile.blogspot.com/2019/08/new-sonoff-rfr3-as-433tomqtt-gateway.html" target="_blank">tutorial</a>'
+custom_img = img/boards/sonoff-rfr3.jpg
 
 [env:esp32dev-ble-datatest]
 platform = ${com.esp32_platform}
@@ -1812,6 +1872,7 @@ build_flags =
   '-DpubBLEAdvData=true'
   '-DGateway_Name="OMG_ESP32_BLE"'
 custom_description = Default BLE gateway with additional servicedata, manufacturerdata and service uuid for analysing decoding issues
+custom_img = img/boards/esp32dev.jpg
 
 [env:esp32s3-dev-c1-ble]
 platform = ${com.esp32_platform}
@@ -1831,6 +1892,7 @@ build_flags =
   '-DNO_INT_TEMP_READING=true' ; Internal temperature reading not building on ESP32 C3 or S3
   '-DGateway_Name="OMG_ESP32_BLE"'
 custom_description = BLE gateway on the S3
+custom_img = img/boards/esp32s3-devkit-c1.png
 
 [env:esp32s3-m5stack-stamps3]
 platform = ${com.esp32_platform}
@@ -1850,6 +1912,7 @@ build_flags =
   '-DNO_INT_TEMP_READING=true' ; Internal temperature reading not building on ESP32 C3 or S3
   '-DGateway_Name="OMG_ESP32_BLE"'
 custom_description = BLE gateway on the M5Stack StampS3
+custom_img = img/boards/m5stamp-s3.webp
 
 [env:esp32s3-atomS3U]
 platform = ${com.esp32_platform}
@@ -1875,6 +1938,7 @@ build_flags =
 board_upload.speed = 921600
 custom_description = USB module with BLE gateway, and IR emitter
 custom_hardware = AtomS3U ESP32S3
+custom_img = img/boards/m5atoms3u.webp
 
 [env:esp32c3-dev-m1-ble]
 platform = ${com.esp32_platform}
@@ -1895,6 +1959,7 @@ build_flags =
   '-DNO_INT_TEMP_READING=true' ; Internal temperature reading not building on ESP32 C3 or S3
   '-DGateway_Name="OMG_ESP32_BLE"'
 custom_description = BLE gateway on the C3
+custom_img = img/boards/esp32c3-devkit-m1.png
 
 [env:airm2m_core_esp32c3]
 platform = ${com.esp32_platform}
@@ -1916,6 +1981,7 @@ custom_description = BLE gateway on the C3
 custom_hardware = AirM2M ESP32C3-CORE
 
 ; Espressiv ESP32-C3-DevKitC-02
+custom_img = img/boards/airm2m.png
 [env:esp32c3-dev-c2-ble]
 platform = ${com.esp32_platform}
 platform_packages = ${com.esp32_platform_packages}
@@ -1938,6 +2004,7 @@ build_flags =
   '-DTRIGGER_GPIO=7'
   '-DGateway_Name="OpenMQTTGateway_ESP32C3_DKC02"'
 custom_description = BLE gateway on Espressiv ESP32-C3-DevKitC-02
+custom_img = img/boards/esp32c3-devkit-c02.png
 
 [env:esp32c3-dev-c2-ble-no-serial]
 extends = env:esp32c3-dev-c2-ble
@@ -1948,6 +2015,7 @@ build_flags =
 custom_description = BLE gateway on Espressiv ESP32-C3-DevKitC-02 without logging
 
 ; Wemos Lolin C3 mini v2.1.0
+custom_img = img/boards/esp32c3-devkit-c02.png
 [env:esp32c3_lolin_mini]
 platform = ${com.esp32_platform}
 platform_packages = ${com.esp32_platform_packages}
@@ -1978,6 +2046,7 @@ build_flags =
   '-DWM_DEBUG=0'  ; disable serial logging.
 custom_description = BLE gateway on ESP32C3
 custom_hardware = Wemos Lolin C3 mini v2.1.0
+custom_img = img/boards/lolin-c3-mini.jpg
 
 [env:esp32c3_lolin_mini_with_serial]
 extends = env:esp32c3_lolin_mini
@@ -1987,6 +2056,7 @@ build_flags =
 ; Serial output via USB
   '-DCONFIG_ESP_CONSOLE_USB_SERIAL_JTAG=true'
   '-DCONFIG_ESP_CONSOLE_UART=ESP_CONSOLE_USB_SERIAL_JTAG'
+custom_img = img/boards/lolin-c3-mini.jpg
 
 [env:esp32c3-m5stamp]
 ; https://docs.m5stack.com/en/core/stamp_c3
@@ -2011,6 +2081,7 @@ build_flags =
   '-DUSE_MAC_AS_GATEWAY_NAME'
 custom_description = BLE gateway on ESP32C3
 custom_hardware = M5Stamp C3
+custom_img = img/boards/m5stamp-c3.webp
 
 [env:esp32c3u-m5stamp]
 ; https://docs.m5stack.com/en/core/stamp_c3u
@@ -2035,6 +2106,7 @@ build_flags =
   '-DUSE_MAC_AS_GATEWAY_NAME'
 custom_description = BLE gateway on ESP32C3
 custom_hardware = M5Stamp C3U
+custom_img = img/boards/m5stamp-c3u.webp
 
 [env:thingpulse-espgateway]
 platform = ${com.esp32_platform}
@@ -2069,6 +2141,7 @@ build_flags =
 ;  '-DsimplePublishing=true'
 custom_description = BLE Gateway using ethernet or wifi with external antenna
 custom_hardware = ThingPulse gateway single ESP32
+custom_img = img/boards/thingpulse-espgateway.jpg
 
 [env:esp32dev-ble-idf]
 platform = ${com.esp32_platform}
@@ -2095,3 +2168,4 @@ build_flags =
   '-DUSE_BLUFI=1'
   '-DenableMultiGTWSync=false'
 custom_description = Regular BLE gateway based on esp-idf with adaptive scanning activated, automatically adapts the scan parameters depending on your devices
+custom_img = img/boards/esp32dev.jpg