diff --git a/README.md b/README.md
index 64afc4b..900b7c9 100644
--- a/README.md
+++ b/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)
 
diff --git a/docs/.vitepress/components/BoardEnvironmentTable.vue b/docs/.vitepress/components/BoardEnvironmentTable.vue
index 822060e..137d727 100644
--- a/docs/.vitepress/components/BoardEnvironmentTable.vue
+++ b/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 activeGatewayFilter = ref<string | null>(null)
+const wizardBridge = 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[]>(() => {
-  const families: Record<string, boolean> = {}
-  boards.value.forEach(b => {
-    const family = getMcuFamily(b.microcontroller)
-    if (family) families[family] = true
+function matchesBridge(board: Board, bridge: string): boolean {
+  const mods = (board.modules || []).map(m => m.toLowerCase())
+  switch (bridge) {
+    case 'ble': return mods.some(m => m.includes('bt'))
+    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 gateways: Record<string, string> = {
-    BT: 'BLE',
-    RF: 'RF',
-    IR: 'IR',
-    LORA: 'LoRa',
-    RTL_433: 'RTL_433',
-    Pilight: 'Pilight'
+const shoppingHint = computed<string>(() => {
+  switch (wizardBridge.value) {
+    case 'ble':
+    case 'ir': return 'Any ESP32 development board will do.'
+    case 'rf433': return 'A LILYGO LoRa32 or Heltec LoRa V2 board matching your devices\' frequency (433/868/915MHz) needs no soldering.'
+    case 'lora': return 'Get a LILYGO LoRa32 or Heltec LoRa board matching the frequency used in your region.'
+    default: return ''
   }
-  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
-  activeGatewayFilter.value = null
+  wizardBridge.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;
diff --git a/docs/.vitepress/components/FlashEnvironmentSelector.vue b/docs/.vitepress/components/FlashEnvironmentSelector.vue
index 7dc170a..f8b78a0 100644
--- a/docs/.vitepress/components/FlashEnvironmentSelector.vue
+++ b/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;
 }
 
diff --git a/docs/.vitepress/components/OmgPipeline.vue b/docs/.vitepress/components/OmgPipeline.vue
new file mode 100644
index 0000000..0bc59ea
--- /dev/null
+++ b/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>
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index a4b2212..5191bba 100644
--- a/docs/.vitepress/config.mts
+++ b/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' },
diff --git a/docs/.vitepress/public/img/OpenMQTTGateway.png b/docs/.vitepress/public/img/OpenMQTTGateway.png
new file mode 100644
index 0000000..e8ce218
Binary files /dev/null and b/docs/.vitepress/public/img/OpenMQTTGateway.png differ
diff --git a/docs/.vitepress/public/img/boards/airm2m.png b/docs/.vitepress/public/img/boards/airm2m.png
new file mode 100644
index 0000000..493118c
Binary files /dev/null and b/docs/.vitepress/public/img/boards/airm2m.png differ
diff --git a/docs/.vitepress/public/img/boards/az-delivery.jpg b/docs/.vitepress/public/img/boards/az-delivery.jpg
new file mode 100644
index 0000000..a781f9a
Binary files /dev/null and b/docs/.vitepress/public/img/boards/az-delivery.jpg differ
diff --git a/docs/.vitepress/public/img/boards/esp32-feather.jpg b/docs/.vitepress/public/img/boards/esp32-feather.jpg
new file mode 100644
index 0000000..9a9ea9b
Binary files /dev/null and b/docs/.vitepress/public/img/boards/esp32-feather.jpg differ
diff --git a/docs/.vitepress/public/img/boards/esp32c3-devkit-c02.png b/docs/.vitepress/public/img/boards/esp32c3-devkit-c02.png
new file mode 100644
index 0000000..f6fc7f4
Binary files /dev/null and b/docs/.vitepress/public/img/boards/esp32c3-devkit-c02.png differ
diff --git a/docs/.vitepress/public/img/boards/esp32c3-devkit-m1.png b/docs/.vitepress/public/img/boards/esp32c3-devkit-m1.png
new file mode 100644
index 0000000..e367e8b
Binary files /dev/null and b/docs/.vitepress/public/img/boards/esp32c3-devkit-m1.png differ
diff --git a/docs/.vitepress/public/img/boards/esp32dev.jpg b/docs/.vitepress/public/img/boards/esp32dev.jpg
new file mode 100644
index 0000000..785e977
Binary files /dev/null and b/docs/.vitepress/public/img/boards/esp32dev.jpg differ
diff --git a/docs/.vitepress/public/img/boards/esp32doitv1.jpg b/docs/.vitepress/public/img/boards/esp32doitv1.jpg
new file mode 100644
index 0000000..9a256ff
Binary files /dev/null and b/docs/.vitepress/public/img/boards/esp32doitv1.jpg differ
diff --git a/docs/.vitepress/public/img/boards/esp32s3-devkit-c1.png b/docs/.vitepress/public/img/boards/esp32s3-devkit-c1.png
new file mode 100644
index 0000000..2a97806
Binary files /dev/null and b/docs/.vitepress/public/img/boards/esp32s3-devkit-c1.png differ
diff --git a/docs/.vitepress/public/img/boards/heltec-wifi-kit-32.png b/docs/.vitepress/public/img/boards/heltec-wifi-kit-32.png
new file mode 100644
index 0000000..3cc771f
Binary files /dev/null and b/docs/.vitepress/public/img/boards/heltec-wifi-kit-32.png differ
diff --git a/docs/.vitepress/public/img/boards/heltec-wifi-lora-32.png b/docs/.vitepress/public/img/boards/heltec-wifi-lora-32.png
new file mode 100644
index 0000000..2444d62
Binary files /dev/null and b/docs/.vitepress/public/img/boards/heltec-wifi-lora-32.png differ
diff --git a/docs/.vitepress/public/img/boards/lilygo-lora32-v21.jpg b/docs/.vitepress/public/img/boards/lilygo-lora32-v21.jpg
new file mode 100644
index 0000000..3cb5928
Binary files /dev/null and b/docs/.vitepress/public/img/boards/lilygo-lora32-v21.jpg differ
diff --git a/docs/.vitepress/public/img/boards/lilygo-t3-s3.jpg b/docs/.vitepress/public/img/boards/lilygo-t3-s3.jpg
new file mode 100644
index 0000000..7e4429b
Binary files /dev/null and b/docs/.vitepress/public/img/boards/lilygo-t3-s3.jpg differ
diff --git a/docs/.vitepress/public/img/boards/lolin-c3-mini.jpg b/docs/.vitepress/public/img/boards/lolin-c3-mini.jpg
new file mode 100644
index 0000000..6c076de
Binary files /dev/null and b/docs/.vitepress/public/img/boards/lolin-c3-mini.jpg differ
diff --git a/docs/.vitepress/public/img/boards/lolin32-lite.jpg b/docs/.vitepress/public/img/boards/lolin32-lite.jpg
new file mode 100644
index 0000000..dff1e4b
Binary files /dev/null and b/docs/.vitepress/public/img/boards/lolin32-lite.jpg differ
diff --git a/docs/.vitepress/public/img/boards/m5atom-lite.webp b/docs/.vitepress/public/img/boards/m5atom-lite.webp
new file mode 100644
index 0000000..330d4ce
Binary files /dev/null and b/docs/.vitepress/public/img/boards/m5atom-lite.webp differ
diff --git a/docs/.vitepress/public/img/boards/m5atom-matrix.webp b/docs/.vitepress/public/img/boards/m5atom-matrix.webp
new file mode 100644
index 0000000..e1ac7ab
Binary files /dev/null and b/docs/.vitepress/public/img/boards/m5atom-matrix.webp differ
diff --git a/docs/.vitepress/public/img/boards/m5atoms3u.webp b/docs/.vitepress/public/img/boards/m5atoms3u.webp
new file mode 100644
index 0000000..25d21c5
Binary files /dev/null and b/docs/.vitepress/public/img/boards/m5atoms3u.webp differ
diff --git a/docs/.vitepress/public/img/boards/m5stack-core.webp b/docs/.vitepress/public/img/boards/m5stack-core.webp
new file mode 100644
index 0000000..8903c7e
Binary files /dev/null and b/docs/.vitepress/public/img/boards/m5stack-core.webp differ
diff --git a/docs/.vitepress/public/img/boards/m5stamp-c3.webp b/docs/.vitepress/public/img/boards/m5stamp-c3.webp
new file mode 100644
index 0000000..73c34ff
Binary files /dev/null and b/docs/.vitepress/public/img/boards/m5stamp-c3.webp differ
diff --git a/docs/.vitepress/public/img/boards/m5stamp-c3u.webp b/docs/.vitepress/public/img/boards/m5stamp-c3u.webp
new file mode 100644
index 0000000..84978d8
Binary files /dev/null and b/docs/.vitepress/public/img/boards/m5stamp-c3u.webp differ
diff --git a/docs/.vitepress/public/img/boards/m5stamp-s3.webp b/docs/.vitepress/public/img/boards/m5stamp-s3.webp
new file mode 100644
index 0000000..9896fb6
Binary files /dev/null and b/docs/.vitepress/public/img/boards/m5stamp-s3.webp differ
diff --git a/docs/.vitepress/public/img/boards/m5stick-c-plus.webp b/docs/.vitepress/public/img/boards/m5stick-c-plus.webp
new file mode 100644
index 0000000..1ee901b
Binary files /dev/null and b/docs/.vitepress/public/img/boards/m5stick-c-plus.webp differ
diff --git a/docs/.vitepress/public/img/boards/m5stick-c.webp b/docs/.vitepress/public/img/boards/m5stick-c.webp
new file mode 100644
index 0000000..70c56d9
Binary files /dev/null and b/docs/.vitepress/public/img/boards/m5stick-c.webp differ
diff --git a/docs/.vitepress/public/img/boards/m5stick.webp b/docs/.vitepress/public/img/boards/m5stick.webp
new file mode 100644
index 0000000..d463bdf
Binary files /dev/null and b/docs/.vitepress/public/img/boards/m5stick.webp differ
diff --git a/docs/.vitepress/public/img/boards/m5tough.webp b/docs/.vitepress/public/img/boards/m5tough.webp
new file mode 100644
index 0000000..0dc2d8f
Binary files /dev/null and b/docs/.vitepress/public/img/boards/m5tough.webp differ
diff --git a/docs/.vitepress/public/img/boards/nodemcuv2.jpg b/docs/.vitepress/public/img/boards/nodemcuv2.jpg
new file mode 100644
index 0000000..edd8a25
Binary files /dev/null and b/docs/.vitepress/public/img/boards/nodemcuv2.jpg differ
diff --git a/docs/.vitepress/public/img/boards/olimex-esp32-gateway.jpg b/docs/.vitepress/public/img/boards/olimex-esp32-gateway.jpg
new file mode 100644
index 0000000..39cd3ac
Binary files /dev/null and b/docs/.vitepress/public/img/boards/olimex-esp32-gateway.jpg differ
diff --git a/docs/.vitepress/public/img/boards/olimex-esp32-poe-iso.jpg b/docs/.vitepress/public/img/boards/olimex-esp32-poe-iso.jpg
new file mode 100644
index 0000000..d345775
Binary files /dev/null and b/docs/.vitepress/public/img/boards/olimex-esp32-poe-iso.jpg differ
diff --git a/docs/.vitepress/public/img/boards/olimex-esp32-poe.jpg b/docs/.vitepress/public/img/boards/olimex-esp32-poe.jpg
new file mode 100644
index 0000000..a0e4199
Binary files /dev/null and b/docs/.vitepress/public/img/boards/olimex-esp32-poe.jpg differ
diff --git a/docs/.vitepress/public/img/boards/shelly-plus1.jpg b/docs/.vitepress/public/img/boards/shelly-plus1.jpg
new file mode 100644
index 0000000..4236593
Binary files /dev/null and b/docs/.vitepress/public/img/boards/shelly-plus1.jpg differ
diff --git a/docs/.vitepress/public/img/boards/sonoff-basic.jpg b/docs/.vitepress/public/img/boards/sonoff-basic.jpg
new file mode 100644
index 0000000..855c64d
Binary files /dev/null and b/docs/.vitepress/public/img/boards/sonoff-basic.jpg differ
diff --git a/docs/.vitepress/public/img/boards/sonoff-rf-bridge.jpg b/docs/.vitepress/public/img/boards/sonoff-rf-bridge.jpg
new file mode 100644
index 0000000..6bd6de3
Binary files /dev/null and b/docs/.vitepress/public/img/boards/sonoff-rf-bridge.jpg differ
diff --git a/docs/.vitepress/public/img/boards/sonoff-rfr3.jpg b/docs/.vitepress/public/img/boards/sonoff-rfr3.jpg
new file mode 100644
index 0000000..8bfda39
Binary files /dev/null and b/docs/.vitepress/public/img/boards/sonoff-rfr3.jpg differ
diff --git a/docs/.vitepress/public/img/boards/thingpulse-espgateway.jpg b/docs/.vitepress/public/img/boards/thingpulse-espgateway.jpg
new file mode 100644
index 0000000..b4768c7
Binary files /dev/null and b/docs/.vitepress/public/img/boards/thingpulse-espgateway.jpg differ
diff --git a/docs/.vitepress/public/img/boards/tinypico.jpg b/docs/.vitepress/public/img/boards/tinypico.jpg
new file mode 100644
index 0000000..c440ab6
Binary files /dev/null and b/docs/.vitepress/public/img/boards/tinypico.jpg differ
diff --git a/docs/.vitepress/public/img/boards/ttgo-lora32-v1.jpg b/docs/.vitepress/public/img/boards/ttgo-lora32-v1.jpg
new file mode 100644
index 0000000..b9edca1
Binary files /dev/null and b/docs/.vitepress/public/img/boards/ttgo-lora32-v1.jpg differ
diff --git a/docs/.vitepress/public/img/boards/ttgo-t-beam.jpg b/docs/.vitepress/public/img/boards/ttgo-t-beam.jpg
new file mode 100644
index 0000000..d8efd0f
Binary files /dev/null and b/docs/.vitepress/public/img/boards/ttgo-t-beam.jpg differ
diff --git a/docs/.vitepress/public/img/boards/wt32-eth01.jpg b/docs/.vitepress/public/img/boards/wt32-eth01.jpg
new file mode 100644
index 0000000..c0820f8
Binary files /dev/null and b/docs/.vitepress/public/img/boards/wt32-eth01.jpg differ
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
index df4f95f..2b35a10 100644
--- a/docs/.vitepress/theme/custom.css
+++ b/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;
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index daa49b8..7931a9c 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/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()
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..c7b9736
--- /dev/null
+++ b/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).
diff --git a/docs/img/OpenMQTTGateway-Build-gitpod-env.png b/docs/img/OpenMQTTGateway-Build-gitpod-env.png
deleted file mode 100644
index de98bc1..0000000
Binary files a/docs/img/OpenMQTTGateway-Build-gitpod-env.png and /dev/null differ
diff --git a/docs/img/OpenMQTTGateway-Build-gitpod.png b/docs/img/OpenMQTTGateway-Build-gitpod.png
deleted file mode 100644
index ce6f31c..0000000
Binary files a/docs/img/OpenMQTTGateway-Build-gitpod.png and /dev/null differ
diff --git a/docs/index.md b/docs/index.md
index edf6bb3..ea2bcd9 100644
--- a/docs/index.md
+++ b/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 style="text-align: center;">
-<img src="./img/OpenMQTTGateway.png" alt="Overview of the protocols and compatible controllers" style="max-width: 100%; height: auto;">
+<div class="omg-section">
+  <h2>How it works</h2>
+  <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>
+  <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 ?
-
-MQTT, short for Message Queuing Telemetry Transport, is a lightweight messaging protocol ideal for IoT devices.
-
-An MQTT gateway or bridge plays a pivotal role in the MQTT ecosystem:
-* Protocol Translation: It converts non-MQTT protocols (like LoRa or Bluetooth) into MQTT, enabling broader network communication.
-* Data Aggregation: Combines data from multiple devices into single messages, optimizing network use.
-* Security: Incorporates features like SSL/TLS encryption to safeguard data during transmission.
-* Device Management: Handles tasks like firmware updates and remote configuration changes.
-
-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 class="omg-section">
+  <h2>What will you automate?</h2>
+  <div class="omg-grid">
+    <div v-for="uc in useCases" :key="uc.text" class="omg-card">
+      <span class="omg-card-icon">{{ uc.icon }}</span>
+      <span>{{ uc.text }}</span>
+    </div>
+  </div>
+  <p class="omg-caption">The limit is your imagination 😀</p>
 </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 style="text-align: center;">
+<div class="omg-section">
+  <h2>Support the project</h2>
+  <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
-
-[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 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>
 </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)
-* [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/)
-* [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/)
-* [Using low-cost wireless sensors in the unlicensed bands](https://lwn.net/Articles/921497/)
-* [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/)
+/* Videos */
+.omg-videos {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+  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
-[![Theengs Plug video ElektroMaker](https://img.youtube.com/vi/nUwMt9p2U7o/0.jpg)](https://www.youtube.com/watch?v=nUwMt9p2U7o&t=427s)
+/* Function pills */
+.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
-[![433Mhz and BLE gateway video by Andreas Spiess](https://img.youtube.com/vi/_gdXR1uklaY/0.jpg)](https://www.youtube.com/watch?v=_gdXR1uklaY)
+/* Product card */
+.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
-[![BLE gateway video by Andreas Spiess](https://img.youtube.com/vi/noUROhtf0E0/0.jpg)](https://www.youtube.com/watch?v=noUROhtf0E0)
+.omg-disclaimer {
+  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
-[![RTL_433 video by TECH MIND](https://img.youtube.com/vi/H-JXWbWjJYE/0.jpg)](https://www.youtube.com/watch?v=H-JXWbWjJYE)
-
-### LORA
-[![LORA video by Priceless Toolkit](https://img.youtube.com/vi/6DftaHxDawM/0.jpg)](https://www.youtube.com/watch?v=6DftaHxDawM)
-
-::: 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.
-:::
+@media (max-width: 640px) {
+  .omg-pipeline { flex-direction: column; }
+  .omg-arrow { transform: rotate(90deg); }
+}
+</style>
diff --git a/docs/participate/quick_start.md b/docs/participate/quick_start.md
index 11c3b19..ea96b94 100644
--- a/docs/participate/quick_start.md
+++ b/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:
 
diff --git a/docs/participate/support.md b/docs/participate/support.md
index 86cc933..f6501f6 100644
--- a/docs/participate/support.md
+++ b/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>
diff --git a/docs/prerequisites/board.md b/docs/prerequisites/board.md
index 6f259ca..9fa7305 100644
--- a/docs/prerequisites/board.md
+++ b/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"
 />
-
diff --git a/docs/prerequisites/broker.md b/docs/prerequisites/broker.md
index 3d10d9b..3f8c9d9 100644
--- a/docs/prerequisites/broker.md
+++ b/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)
diff --git a/docs/prerequisites/devices.md b/docs/prerequisites/devices.md
index 1aefec8..222ccb9 100644
--- a/docs/prerequisites/devices.md
+++ b/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). 
diff --git a/docs/setitup/actuators.md b/docs/setitup/actuators.md
index b05ce75..87a33a5 100644
--- a/docs/setitup/actuators.md
+++ b/docs/setitup/actuators.md
@@ -1,11 +1,11 @@
 # Actuators
 ## Compatible parts 
-|Module|Purpose|Where to Buy|
-|-|-|-|
-|LED|Basic led|-|
-|FASTLED|RGB Leds management|-|
-|BUZZER|-|-|
-|RELAY|Switch power circuit|-|
+|Module|Purpose|
+|-|-|
+|LED|Basic led|
+|FASTLED|RGB Leds management|
+|BUZZER|-|
+|RELAY|Switch power circuit|
 
 ## Pinout
 |Module| Boards|
diff --git a/docs/setitup/gsm.md b/docs/setitup/gsm.md
index 0d02a05..f472fed 100644
--- a/docs/setitup/gsm.md
+++ b/docs/setitup/gsm.md
@@ -1,10 +1,10 @@
 # GSM 2G gateway
 ## Compatible parts
 
-|Module|Purpose|Where to Buy|
-|-|-|-|
-|A6|GSM GPRS module|-|
-|A7|GSM GPRS module with GPS|-|
+|Module|Purpose|
+|-|-|
+|A6|GSM GPRS module|
+|A7|GSM GPRS module with GPS|
 
 ## Hardware setup
 
diff --git a/docs/setitup/ir.md b/docs/setitup/ir.md
index a7ab960..ee9f865 100644
--- a/docs/setitup/ir.md
+++ b/docs/setitup/ir.md
@@ -1,12 +1,12 @@
 # IR gateway
 ## Compatible parts
-|Module|Purpose|Where to Buy|
-|-|-|-|
-|IR diode|Emitting|-|
-|IR receiver|Receiving|-|
-|transistor 2N2222|Amplify uC signal for the IR diode|-|
-|330 ohms resistor|-|-|
-|220 ohms resistor|limit current to LED|-|
+|Module|Purpose|
+|-|-|
+|IR diode|Emitting|
+|IR receiver|Receiving|
+|transistor 2N2222|Amplify uC signal for the IR diode|
+|330 ohms resistor|-|
+|220 ohms resistor|limit current to LED|
 
 The IR setup can work with bc547 and a 4x3 LED-Matrix.
 
diff --git a/docs/setitup/rf.md b/docs/setitup/rf.md
index 5482c36..e4f41b3 100644
--- a/docs/setitup/rf.md
+++ b/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|
-|-|-|-|-|-|
-|SRX882 or SRX882S (recommended)|433Mhz Receiver|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|-|
-|SX1276/SX1278|433Mhz Transceiver|[RTL_433](../use/rf#supported-decoders)|Not Supported|-|
-|LilyGo/Heltec|433Mhz Transceiver|[RTL_433](../use/rf#supported-decoders)|Not Supported|-|
+|Module|Purpose|Compatible modules|Receiver Switching|
+|-|-|-|-|
+|SRX882 or SRX882S (recommended)|433Mhz Receiver|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|
+|SX1276/SX1278|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)
 
diff --git a/docs/setitup/sensors.md b/docs/setitup/sensors.md
index e18fb9b..3fc55d0 100644
--- a/docs/setitup/sensors.md
+++ b/docs/setitup/sensors.md
@@ -1,21 +1,21 @@
 # Sensors
 ## Compatible sensors
-|Module|Purpose|Where to Buy|
-|-|-|-|
-|DHT11|Temperature, Humidity|-|
-|DHT22|Temperature, Humidity|-|
-|HCSR501|PIR|-|
-|BH1750|Digital light|-|
-|BME280|Temperature, Humidity, Pressure|-|
-|BMP280|Temperature, Pressure|-|
-|C-37, YL-83, HM-RD|Leak, Water|-|
-|HTU21|Temperature, Humidity|-|
-|GPIO Input|Inputs|-|
-|GPIO KeyCode|Keycode|-|
-|INA226|Current, Voltage|-|
-|MQ2|Gas (flammable)|-|
-|TEMT6000|Luminosity|-|
-|TSL2561|Luminosity|-|
+|Module|Purpose|
+|-|-|
+|DHT11|Temperature, Humidity|
+|DHT22|Temperature, Humidity|
+|HCSR501|PIR|
+|BH1750|Digital light|
+|BME280|Temperature, Humidity, Pressure|
+|BMP280|Temperature, Pressure|
+|C-37, YL-83, HM-RD|Leak, Water|
+|HTU21|Temperature, Humidity|
+|GPIO Input|Inputs|
+|GPIO KeyCode|Keycode|
+|INA226|Current, Voltage|
+|MQ2|Gas (flammable)|
+|TEMT6000|Luminosity|
+|TSL2561|Luminosity|
 
 ## Pinout
 |Module|Arduino Pin| ESP8266 Pin|ESP32 Pin|
diff --git a/docs/upload/board-selector.md b/docs/upload/board-selector.md
index c4a920c..e31a913 100644
--- a/docs/upload/board-selector.md
+++ b/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>
diff --git a/docs/upload/gitpod.md b/docs/upload/gitpod.md
deleted file mode 100644
index 4cc9a8a..0000000
--- a/docs/upload/gitpod.md
+++ /dev/null
@@ -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.
diff --git a/docs/upload/index.md b/docs/upload/index.md
index 7ec95e2..f7b0586 100644
--- a/docs/upload/index.md
+++ b/docs/upload/index.md
@@ -1,79 +1,159 @@
-# Upload
-
-OpenMQTTGateway provides several installation approaches suited for different use cases. The quickest path uses pre-built binaries that work with standard configurations. For custom parameters or specific gateway module combinations, you can build firmware using your development environment. Alternatively, you can flash devices directly from your web browser without installing any software.
-
-<p align="center">
-  <img src="../img/upload.png" alt="Firmware upload process">
-</p>
-
-## Choosing Your Upload Method
-
-### Web-Based Installation
-
-The [web installation](web-install.md) method represents the easiest way to get started with OpenMQTTGateway. You can flash your device directly from your browser without downloading files or installing development tools. This method works on Windows, macOS, and Linux with Chrome, Edge, or Opera browsers.
-
-The web installer displays available environments for different boards and gateway configurations. Select your board type, connect via USB, and click the connect button. The installer handles everything automatically, including erasing old firmware and writing the new one. The web installer uses [ESP Web Tools](https://esphome.github.io/esp-web-tools/) technology to communicate directly with your ESP device.
-
-### Ready-to-Go Binary Installation
-
-[Downloading and installing pre-built binaries](binaries.md) offers control over the flashing process using desktop tools. Download the binary files for your board from the [GitHub releases page](https://github.com/1technophile/OpenMQTTGateway/releases).
-
-For ESP32 devices, you need the firmware binary, bootloader, and boot application partition files written to specific memory addresses. Windows users can use the ESP32 Flash Download Tool from Espressif. On Linux and macOS, the esptool.py command-line utility provides a straightforward upload method.
-
-This method works well for standard configurations without modifying source code. After flashing, you can still configure WiFi, MQTT broker settings, and basic parameters through the configuration portal.
-
-### Custom Build and Upload
-
-[Building from source](builds.md) becomes necessary when you need specific pin assignments, custom MQTT topics, or particular gateway module combinations not available in pre-built binaries.
-
-[PlatformIO](https://platformio.org/) provides the recommended build environment. After downloading the [source code from GitHub](https://github.com/1technophile/OpenMQTTGateway), you will find a `platformio.ini` file defining build environments for various hardware combinations.
-
-The configuration system uses a layering approach where default values from [`User_config.h`](https://github.com/1technophile/OpenMQTTGateway/blob/development/main/User_config.h) and [`config_XX.h`](https://github.com/1technophile/OpenMQTTGateway/tree/development/main) files can be overridden by build flags in `platformio.ini` or `environments.ini`. You can embed WiFi credentials and MQTT settings at build time for automatic connection on first boot.
-
-### Browser-Based Building with Gitpod
-
-For those who want to build custom firmware without setting up a local development environment, [Gitpod](gitpod.md) offers a cloud-based solution. By clicking on the [Gitpod link](https://gitpod.io#https://github.com/1technophile/OpenMQTTGateway/tree/development), you get a complete development environment running in your browser with PlatformIO already installed and configured.
-
-After the automatic initial build completes, modify the environment configuration by editing `environments.ini` and run build commands in the browser terminal. Download the generated firmware files and flash them using the binary installation method.
-
-## Configuring Network and MQTT Settings
-
-After flashing firmware, configure network connectivity and MQTT broker settings using either runtime or build-time approaches.
-
-### Runtime Configuration Portal
-
-When you power on a freshly flashed device, it creates a WiFi access point named OpenMQTTGateway or starting with OMG_. You can find detailed information about the [configuration portal here](portal.md).
-
-Connecting to this access point opens a portal where you configure your WiFi network, MQTT broker details, and optional security settings including TLS encryption and certificates. For devices with Ethernet, access the portal through the LAN IP address and configure WiFi as fallback connectivity.
-
-The portal accepts broker IP addresses or hostnames with mDNS support like homeassistant.local. Set a gateway password to protect future configuration changes, OTA updates, and web interface access.
-
-### Build-Time Configuration
-
-Alternatively, embed network and MQTT settings directly in firmware during the build process. Set parameters in `User_config.h` or add them as build flags in your PlatformIO environment definition. Store sensitive information in a separate `_env.ini` file excluded from version control.
-
-## Advanced Configuration Options
-
-Beyond basic connectivity, OpenMQTTGateway supports several [advanced features](advanced-configuration.md) that enhance security and integration capabilities.
-
-### Secure MQTT Connections
-
-For deployments over the internet or public networks, enable TLS encryption to secure communication between the gateway and MQTT broker. Configure your broker with a valid certificate and obtain the Certificate Authority certificate. The gateway can verify server identity against this certificate or connect with encryption without validation.
-
-Provide the CA certificate at build time in `default_server_cert.h` or paste it into the configuration portal. The gateway supports both self-signed certificates and those from public certificate authorities.
-
-### Home Assistant Auto-Discovery
-
-When you use [Home Assistant](https://www.home-assistant.io/) as your home automation platform, OpenMQTTGateway automatically creates device entries and sensors through Home Assistant's MQTT discovery protocol, enabled by default in all standard builds.
-
-Enable discovery in your Home Assistant MQTT integration settings and create a dedicated MQTT user. The gateway registers itself as a device and creates sensor entities automatically, appearing in Configuration → Devices section.
-
-### Topic Customization
-
-The gateway publishes messages to MQTT topics following the format `home/OpenMQTTGateway/GATEWAYtoMQTT`. Enable the `valueAsATopic` feature to append received values to the topic path, making topic-based filtering easier and avoiding warnings in certain controllers.
-
-## Next Steps
-
-After successfully uploading firmware and configuring your gateway, you can proceed to configure specific gateway modules for [RF](../setitup/rf.md), [IR](../setitup/ir.md), [Bluetooth](../setitup/ble.md), [LoRa](../setitup/lora.md), or other protocols you want to use. Each module has configuration options adjustable through MQTT commands or the web interface without rebuilding firmware.
-
-The [troubleshooting section](troubleshoot.md) covers common issues, but if you encounter problems not addressed here, the [OpenMQTTGateway community forum](https://community.openmqttgateway.com) provides an active place to ask questions and share solutions with other users.
+# Upload
+
+Getting OpenMQTTGateway onto your board takes three steps, whichever method you pick:
+
+<div class="omg-journey">
+  <div class="omg-step">
+    <span class="omg-step-num">1</span>
+    <strong>Flash the firmware</strong>
+    <span class="omg-step-sub">pick a method below</span>
+  </div>
+  <span class="omg-step-arrow">→</span>
+  <div class="omg-step">
+    <span class="omg-step-num">2</span>
+    <strong>Configure WiFi &amp; MQTT</strong>
+    <span class="omg-step-sub">through the <a href="./portal.html">portal</a></span>
+  </div>
+  <span class="omg-step-arrow">→</span>
+  <div class="omg-step">
+    <span class="omg-step-num">3</span>
+    <strong>Verify</strong>
+    <span class="omg-step-sub">gateway appears on your <a href="../getting-started.html#step-4-check-that-it-works">broker &amp; controller</a></span>
+  </div>
+</div>
+
+## Choose your installation method
+
+<div class="omg-methods">
+  <a class="omg-method" href="./web-install.html">
+    <span class="omg-method-badge">Easiest</span>
+    <h3>1. Web installer</h3>
+    <p><strong>Choose this if</strong> you want the fastest path: flash directly from your browser, nothing to install.</p>
+    <p class="omg-method-req">Needs Chrome, Edge or Opera and a data USB cable. Standard configurations only.</p>
+  </a>
+  <a class="omg-method" href="./binaries.html">
+    <h3>2. Ready-to-go binaries</h3>
+    <p><strong>Choose this if</strong> you prefer a desktop flashing tool (esptool.py, Espressif Flash Download Tool), or web flashing doesn't work for you.</p>
+    <p class="omg-method-req">Same pre-built firmware as the web installer, flashed from your computer.</p>
+  </a>
+  <a class="omg-method" href="./builds.html">
+    <h3>3. Build from source</h3>
+    <p><strong>Choose this if</strong> you need custom pin assignments, module combinations, or credentials embedded at build time.</p>
+    <p class="omg-method-req">Needs <a href="https://platformio.org/">PlatformIO</a>. Full control over the configuration.</p>
+  </a>
+</div>
+
+|                          | Web installer | Binaries | From source |
+|--------------------------|:---:|:---:|:---:|
+| No software to install   | ✅ | ❌ | ❌ |
+| Custom configuration     | ❌ | ❌ | ✅ |
+| Difficulty               | Easiest | Easy | Advanced |
+
+## After flashing: configure your gateway
+
+However you flashed, a freshly installed gateway starts its own WiFi access point (named `OpenMQTTGateway` or starting with `OMG_`). Connect to it and the [configuration portal](portal.md) lets you set your WiFi network, MQTT broker, and optional security settings — no rebuild needed.
+
+If you build from source you can alternatively [embed the network and MQTT settings at build time](builds.md), so the gateway connects automatically on first boot.
+
+## Going further
+
+* [Advanced configuration](advanced-configuration.md) — TLS-secured MQTT connections, certificates, OTA updates.
+* [Home Assistant integration](../integrate/home_assistant.md) — auto-discovery is enabled by default; your gateway and sensors appear automatically.
+* [Gateway configuration](../use/gateway.md) — MQTT topic structure and runtime commands per module.
+
+Stuck? Check the [troubleshooting page](troubleshoot.md), or ask on the [community forum](https://community.openmqttgateway.com).
+
+<style scoped>
+.omg-journey {
+  display: flex;
+  align-items: stretch;
+  gap: 8px;
+  margin: 24px 0;
+  flex-wrap: wrap;
+}
+.omg-step {
+  flex: 1 1 150px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+  gap: 4px;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 12px;
+  padding: 16px 12px;
+}
+.omg-step-num {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border-radius: 50%;
+  background: var(--vp-c-brand-1);
+  color: var(--vp-c-white, #fff);
+  font-weight: 700;
+  font-size: 14px;
+}
+.omg-step-sub {
+  color: var(--vp-c-text-2);
+  font-size: 13px;
+}
+.omg-step-arrow {
+  align-self: center;
+  color: var(--vp-c-brand-1);
+  font-size: 20px;
+  font-weight: 700;
+}
+.omg-methods {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+  gap: 16px;
+  margin: 16px 0 24px;
+}
+.omg-method {
+  position: relative;
+  display: block;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 12px;
+  padding: 20px;
+  text-decoration: none !important;
+  color: var(--vp-c-text-1);
+  transition: border-color 0.2s ease, transform 0.2s ease;
+}
+.omg-method:hover {
+  border-color: var(--vp-c-brand-1);
+  transform: translateY(-2px);
+}
+.omg-method h3 {
+  margin: 0 0 8px;
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--vp-c-brand-1);
+}
+.omg-method p {
+  margin: 0 0 8px;
+  font-size: 14px;
+  line-height: 1.5;
+}
+.omg-method-req {
+  color: var(--vp-c-text-2);
+  font-size: 13px !important;
+}
+.omg-method-badge {
+  position: absolute;
+  top: -10px;
+  right: 12px;
+  background: var(--vp-c-brand-1);
+  color: var(--vp-c-white, #fff);
+  border-radius: 10px;
+  padding: 2px 10px;
+  font-size: 12px;
+  font-weight: 600;
+}
+@media (max-width: 640px) {
+  .omg-journey { flex-direction: column; }
+  .omg-step-arrow { transform: rotate(90deg); }
+}
+</style>
diff --git a/docs/upload/troubleshoot.md b/docs/upload/troubleshoot.md
index d5c4158..6911009 100644
--- a/docs/upload/troubleshoot.md
+++ b/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.
 
diff --git a/docs/upload/web-install.md b/docs/upload/web-install.md
index fc0e8c8..56a28d6 100644
--- a/docs/upload/web-install.md
+++ b/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
 
-
-
-## Using OpenMQTTGateway ?
-Support open-source development through sponsorship and gain exclusive access to our private forum. Your questions, issues, and feature requests will receive priority attention, plus you'll gain insider access to our roadmap.
-
-<div style="text-align: center;">
-    <iframe src="https://github.com/sponsors/theengs/button" title="Sponsor Theengs" height="32" width="228" style="border: 0; border-radius: 6px;"></iframe>
-</div>
+Once the upload is complete, connect the gateway to your WiFi network and MQTT broker through the [configuration portal](portal.md).
 
diff --git a/docsgen/boards-info.js b/docsgen/boards-info.js
index 72717b9..ce52d05 100644
--- a/docsgen/boards-info.js
+++ b/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) {
diff --git a/environments.ini b/environments.ini
index 845cbbf..979d70a 100644
--- a/environments.ini
+++ b/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