0 Fork 0

Files

T

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

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

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

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

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

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


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

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

2026-08-03 10:23:43 -05:00

5.7 KiB

Raw Permalink Blame History

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:

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 for other cases, or get a pre-flashed Theengs Bridge 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 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:

In Home Assistant go to Settings → Add-ons → Add-on store, install Mosquitto broker and start it.
Install the MQTT integration (Settings → Devices & services → Add integration → MQTT) if it isn't set up already.
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 on any always-on machine, or see the broker page for alternatives.

Step 2 — Flash the firmware from your browser

Open the web installer in Chrome, Edge or Opera (Firefox and Safari don't support web flashing).
Connect the board to your computer with the USB cable.
Pick the firmware matching your board and use case — the two most flashed:
- Bluetooth on a generic ESP32: esp32dev-ble
- RF on a LILYGO LoRa32: lilygo-rtl_433 (the radio frequency is configurable afterwards)
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.

Step 3 — Connect the gateway to your WiFi and broker

After flashing, the gateway starts its own WiFi access point:

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).
A configuration page opens (on Android, accept "stay connected without internet"). Click Configure WiFi.
Select your WiFi network and enter its password.
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.
Click Save. The gateway restarts and joins your network.

The full list of portal fields is described on the configuration portal page.

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: connect to your broker and look for home/OpenMQTTGateway/LWT = online and messages under home/OpenMQTTGateway/.

Something not right? Head to the troubleshooting page or ask on the community forum.

Where to go next

More RF options — other compatible boards and firmwares, transmitting, frequency tuning, and protocol details in RF hardware setup and RF usage.
Infrared — wire an IR emitter/receiver following the IR hardware setup.
Tune the gateway — the WebUI and gateway commands let you configure it at runtime over MQTT.
Other controllers — OpenHAB, Node-RED, Jeedom, AWS IoT.
Full Home Assistant details — Home Assistant integration.

5.7 KiB Raw Permalink Blame History