Telemetry and edge data

How does a BLE to MQTT gateway get sensor data to a broker?

A BLE to MQTT gateway is a device with a Bluetooth LE radio and a network connection that collects readings from nearby BLE sensors, either by listening to the advertisements they broadcast or by connecting to them over GATT, turns each reading into an MQTT message on a topic, and publishes it to a broker. It can be an ESP32 running firmware such as OpenMQTTGateway, a Raspberry Pi or other computer running Theengs Gateway or your own Python, or an edge runtime that forwards local MQTT to a cloud broker.

TL;DR

Most BLE to MQTT gateways listen to sensor advertisements and publish decoded readings, connecting over GATT only when a sensor does not broadcast its values. OpenMQTTGateway and Theengs Gateway cover common sensors, while bleak and Paho on Linux, or ESP-IDF on an ESP32, let you build your own. Whether readings survive depends on buffering between gateway and broker.

Learning objectives

After reading this article you will be able to:

  • Explain when a gateway should listen to BLE advertisements and when it must connect over GATT
  • Compare ready-made BLE to MQTT gateways with building one on an ESP32 or on Linux
  • Design topics and offline buffering so readings survive a broker that is unreachable

Key points

Bluetooth LE sensors cannot reach a broker on their own: they have a short-range radio and no IP connection. A gateway sits near them, hears or polls them over Bluetooth LE, and speaks MQTT to a broker over Wi-Fi, Ethernet or cellular. A gateway design comes down to three choices: how it reads the sensors, how it names and shapes the messages, and what it does when the broker cannot be reached.

BLE to MQTT gateway data flow

A BLE to MQTT gateway runs a loop: receive a reading over Bluetooth LE, decode it, publish it to a topic, and keep it until the broker has it. In more detail:

  1. Receive. The gateway either scans for advertisements, which many sensors use to broadcast their latest values, or connects to a sensor and reads or subscribes to a GATT characteristic.
  2. Decode. Advertisement payloads and characteristic values are bytes in a format the sensor maker chose. A decoder, such as the Theengs Decoder library or your own code, turns them into named values like temperature and battery.
  3. Publish. The gateway sends each reading to the MQTT broker on a topic, with a quality of service level and, if wanted, the retain flag.
  4. Buffer. If the broker is unreachable, the gateway holds readings until it is back, or drops them.

The broker then fans each message out to every subscriber, such as a time-series database, a dashboard or a home automation system. That separation is the point of MQTT: the gateway never needs to know who is listening.

BLE advertisement scanning vs GATT connections

A gateway should scan advertisements whenever the sensor broadcasts its readings, and connect over GATT only when it does not. Listening costs the gateway nothing per sensor, while every connection takes one of a small number of slots.

  • Passive scanning receives what devices broadcast without connecting or sending anything. ESPHome describes it as how a proxy receives broadcast sensor data. BLE advertising explains what fits in those packets.
  • Active scanning asks each device for an extra scan response. ESPHome says it is typically only needed when first adding a device.
  • Connecting over GATT lets the gateway read values the sensor does not broadcast, subscribe to notifications, or write settings. Connections are limited: ESPHome gives an ESP32 Bluetooth proxy three connection slots by default and up to nine, and Home Assistant says most CSR-based USB adapters hold five connections at a time and most Broadcom adapters seven.

A gateway that only listens can cover as many broadcasting sensors as it can hear. A gateway that must connect to each one has to take turns, which delays readings.

BLE to MQTT gateway options

The main BLE to MQTT gateway options are ready-made gateway software on an ESP32 or a computer, a gateway you build yourself on Linux or an ESP32, and an edge runtime that carries local MQTT to a cloud broker. Each entry below gets the same fields, from the project’s own docs and repository, as of October 2026.

OptionWhat it isRuns onReads BLE byMQTTLicenceBest forLimits
OpenMQTTGatewayFirmware that bridges BLE, 433 and 315 MHz RF, infrared and LoRa to MQTTESP32, ESP32-S3, ESP32-C3 and ESP8266 boardsDecoding advertisements of supported sensorsPublishes to your brokerGPL-3.0A cheap, flashed device per room or zoneSensors outside its decoder list need work; one shared 2.4 GHz radio on ESP32
Theengs GatewayPython BLE to MQTT gateway built on the Theengs DecoderRaspberry Pi, Windows, macOS and other computersDecoding advertisements of supported sensorsPublishes JSON, with Home Assistant discoveryGPL-3.0Using a computer you already run near the sensorsNeeds a full computer and a working Bluetooth adapter
ESPHome Bluetooth proxyAn ESP32 that extends Home Assistant’s Bluetooth reachESP32 boardsForwarding advertisements, plus active connectionsNone directly; uses ESPHome’s native API to Home AssistantOpen source (ESPHome)Home Assistant installationsNot an MQTT gateway on its own
Your own Linux gatewayBlueZ with the bleak library and the Eclipse Paho MQTT clientLinux, also macOS and Windows for bleakScanning or GATT connections, in your codePaho supports MQTT 3.1, 3.1.1 and 5.0Bleak MIT; Paho EPL-2.0 or EDL-1.0Unusual sensors, custom payloads, your own bufferingYou own decoding, reliability and updates
Your own ESP32 firmwareESP-IDF’s Bluetooth LE stack with its ESP-MQTT clientESP32 familyScanning or GATT connections, in your codeESP-MQTT supports MQTT 5.0Your ownProducts that ship a gatewayFirmware work; radio shared with Wi-Fi
AWS IoT Greengrass on the gatewayAn edge runtime with a local MQTT broker and an MQTT bridge to AWS IoT CoreLinux and Windows core devicesNot at all; your component or another gateway publishes to itLocal broker, bridged to AWS IoT CoreOpen source runtimeFleets that already use AWS IoTAdds the reading side on top; ties the cloud side to AWS

Theengs Gateway uses OpenMQTTGateway’s topic structure and message format, and its docs describe it as usable on its own or alongside OpenMQTTGateway. AWS IoT Greengrass and Azure IoT Edge compares the two main edge runtimes in more depth.

Linux gateway with bleak and Paho

A Linux gateway can run a bleak scanner, decode each advertisement in its callback, and publish the result with the Paho client. Bleak is a cross-platform Python Bluetooth LE client whose Linux backend uses BlueZ, and Paho is the Eclipse Foundation’s MQTT client. A minimal sketch that publishes raw manufacturer data looks like this:

import asyncio, json, time
import paho.mqtt.client as mqtt
from bleak import BleakScanner

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="gw-hall-2")
client.max_queued_messages_set(10000)   # QoS 1 messages held in memory while disconnected
client.connect_async("broker.local", 1883)
client.loop_start()

def on_advertisement(device, adv):
    for company_id, data in adv.manufacturer_data.items():
        reading = {"rssi": adv.rssi, "company": company_id,
                   "raw": data.hex(), "seen": time.time()}
        client.publish(f"site/hall-2/ble/{device.address}/raw",
                       json.dumps(reading), qos=1)

async def main():
    async with BleakScanner(on_advertisement):
        await asyncio.Event().wait()   # scan until the process is stopped

asyncio.run(main())

A real gateway adds a decoder for each sensor type, TLS and credentials for the broker, and a durable buffer. Bleak’s scanner accepts scanning_mode="passive" where the platform allows it; its docs note that passive scanning is not supported on macOS, and Home Assistant says passive scanning on Linux needs BlueZ 5.63 or later with experimental features enabled.

ESP32 vs Linux gateways

An ESP32 is cheaper and smaller, but it shares one radio between Wi-Fi and Bluetooth, while a Linux machine has more memory and storage for buffering. Espressif’s coexistence guide says each ESP32 board has a single 2.4 GHz RF module, shared by time-division multiplexing, and that a BLE scan can be interrupted when Wi-Fi needs the radio. ESPHome recommends a board with Ethernet for a Bluetooth proxy for the same reason, so the radio is not busy carrying Wi-Fi traffic.

A Linux gateway can hold days of readings on disk and run several services side by side. It needs more power and more upkeep. Many deployments put a few ESP32 listeners near the sensors and one Linux machine with the broker, or with a bridge to a cloud broker.

Bluetooth Mesh sensor data to MQTT

To bridge Bluetooth Mesh sensors, the gateway becomes a node of the mesh: it is provisioned, subscribed to the addresses the sensors publish to, and republishes what it receives over MQTT. Bluetooth Mesh is a different system from plain advertising sensors. Devices join through provisioning, publish messages to addresses, and need the network and application keys to read them, so a gateway that is not a member hears nothing useful. The Bluetooth SIG lists sensors among the four classes of mesh models, so readings arrive in a defined format the gateway can decode. On an ESP32, Espressif’s ESP-BLE-MESH component, built on the Zephyr Bluetooth Mesh stack, supports provisioning and node features such as Proxy and Relay, so one board can be both the mesh node and the MQTT client. The MQTT side is the same as for any other gateway.

MQTT topic naming and payload shape

A BLE gateway should name topics by where and what, with the sensor’s identity as a level, and put the time the reading was taken in the payload. A topic such as site/hall-2/ble/<sensor-id>/temperature lets a subscriber use MQTT’s wildcards: + matches exactly one level and # matches all levels below, so site/+/ble/# collects every BLE reading on the site.

A few rules keep the data usable:

  • Use a stable sensor identifier. Bluetooth LE allows devices to use private addresses that change over time, a privacy feature in the Core Specification’s Generic Access Profile. If a sensor does that, take its identity from its payload or from pairing, not from the address.
  • Put the gateway in the payload, not the topic, if two gateways can hear the same sensor, so subscribers can drop the duplicate reading.
  • Timestamp at the gateway when the sensor does not, and keep that time separate from when the broker received the message, the same distinction a store-and-forward data logger keeps.
  • Retain the latest value of each measurement, so a dashboard that subscribes later sees it at once. MQTT 5.0 stores a retained message as the topic’s latest value and sends it to future subscribers.
  • Use QoS 1 and duplicate-safe consumers. QoS 1 messages are assured to arrive, but duplicates can occur, so subscribers should ignore a reading they have already stored.

BLE readings during a broker outage

BLE readings survive a broker outage only if the gateway buffers them, because MQTT’s own session state applies to a client that has connected before and only for as long as the session lasts. In MQTT 5.0, if the Session Expiry Interval is zero or absent, the session ends when the network connection closes. When it is greater than zero, the client and server keep session state after disconnecting, including QoS 1 and QoS 2 messages that are not yet complete. Message Expiry Interval lets a publisher say how long a message stays useful.

What gets kept while disconnected depends on the client:

  • Eclipse Paho for Python keeps QoS 1 and QoS 2 publishes in an in-memory queue and sends them after the connection is made again, up to a limit you set with max_queued_messages_set, where 0 means unlimited. A QoS 0 publish made while disconnected is not kept. An in-memory queue is lost if the gateway process restarts or loses power.
  • AWS IoT Greengrass has an MQTT spooler for messages to AWS IoT Core. It stores them in memory by default, 2.5 MB unless configured otherwise, rejects new messages when full, and discards QoS 0 messages while offline unless keepQos0WhenOffline is set. From nucleus version 2.11.0 it can spool to disk instead.

For readings that matter, write each one to local storage before publishing and delete it only after the broker acknowledges it, the same pattern as an outbox. Size that storage for the longest outage you expect. Collecting device data without internet covers the wider design.

Offline Protocol and BLE gateways

Offline Protocol is not a BLE to MQTT gateway. It does not read advertisements or GATT characteristics from third-party sensors, and its docs state that no MQTT bridge ships with the SDK. A bridge to a broker is code you write.

It helps with a related job: getting records from people’s phones and other devices to a gateway that is not always in reach of them, such as inspection results or readings a technician collected in a dead zone. The SDK’s Python package runs a full peer on a Linux, macOS or Windows gateway, with a Bluetooth LE central role over bleak, a peripheral role over bless on macOS and Linux, peer streams on the local network and an internet relay. Phones running the SDK can hand encrypted records to that gateway when they come within range or reach the same network, and your code on the gateway publishes them to the broker. The backend delivery guide describes how to keep each record until the destination has accepted it, rather than treating an MQTT acknowledgement as the end of the job.

Frequently asked questions

Can an ESP32 be a BLE to MQTT gateway?

Yes. Firmware such as OpenMQTTGateway turns an ESP32 into one, and ESP-IDF provides both a Bluetooth LE stack and an MQTT client for custom firmware. Espressif notes that Wi-Fi and Bluetooth share one 2.4 GHz radio on the ESP32, so Wi-Fi traffic can interrupt a BLE scan window.

Is an ESPHome Bluetooth proxy a BLE to MQTT gateway?

Not exactly. An ESPHome Bluetooth proxy extends Home Assistant's Bluetooth reach and talks to Home Assistant through ESPHome's native API, so readings reach MQTT only if Home Assistant or something else publishes them there.

Which MQTT QoS should a BLE gateway use?

QoS 1 suits most sensor readings, because the message is assured to arrive and the subscriber can ignore duplicates by reading ID or timestamp. QoS 0 can lose messages, and QoS 2 costs an extra exchange for exactly once delivery on each hop.

How many BLE sensors can one gateway connect to at once?

It depends on the adapter. ESPHome gives an ESP32 proxy three connection slots by default and up to nine, and Home Assistant says most CSR-based USB adapters hold five connections and most Broadcom adapters seven. Sensors that broadcast in advertisements need no connection at all.

Does a BLE to MQTT gateway need the internet?

No. It needs a network path to a broker, and a broker on the local network works with no internet access. The internet matters only if the broker, or a bridge it forwards to, is in the cloud.

Sources

Build it with Offline Protocol

The Python and Linux gateway guide shows how to run a full Offline Protocol peer on a gateway with persistent state, so phones and other devices can hand it records over the local network or Bluetooth LE before your own code publishes them to a broker.

Read the Python gateway guide