Multiplatform Bluetooth® Mesh Library

The multiplatform Bluetooth® Mesh API for iOS, Android, Web, Windows, Linux and macOS.

As app developers, we have worked with every major Bluetooth® Mesh library available in 2025. None of them met our requirements for features, ease of use, and documentation. We found it difficult to get started, to debug issues, and to create apps that run on multiple platforms; every additional platform meant learning new concepts, APIs, and corner cases. Above all, there was no well-maintained library for web applications or for servers and gateways running Linux.

After completing two large projects using existing technology, we decided to build our own. The BluKo Mesh Library is designed for ease of use, whether you are building mobile apps for iOS and Android or software for Linux-based systems such as gateways and wall panels.

A unique feature is the ability to include this library in a browser-based application using Web Bluetooth. This allows you to create web apps that interact directly with Bluetooth® Mesh networks.

Target Platforms

  • Android using Kotlin
  • iOS and iPadOS using Swift
  • Web browsers using TypeScript or JavaScript
  • Linux/Windows/macOS using Node.js or Java/JVM

This library is not designed for embedded systems; it targets mobile and desktop apps, powerful gateways, or even server systems.

Key Features

  • Single codebase and single API across all supported platforms.
  • Supports native, modern async APIs – no need to manage callbacks.
  • Integrates with native platform features for bearer, storage, and logging.
  • Created by app developers for app developers – no cryptic, low-level APIs.
  • Supports all Bluetooth® Mesh 1.0.1 features like provisioning, GATT proxies, groups, and all specified models.
  • Includes extensive documentation and sample code to get you started in hours instead of weeks.

One API, Many Languages

The same concepts, the same call order, the same names – written the way each language expects.

Provision a Device

Open the network, let the device identify itself, provision it, and connect to it as a proxy.

Kotlin

val network = MeshNetwork.getOrCreateSingle(storage, logger, acknowledgedMessageTimeout = 30.seconds)
val networkKey = network.networkKeys.getStored().first()

val provisioningBearer = GattProvisioningProxyBearer.fromScan(logger = logger)
val device = network.identifyDevice(provisioningBearer, provisioningBearer.serviceData, attentionDuration = 5.seconds)
val node = device.provision(networkKey, name = "Desk Lamp")

network.connectToProvisionedNode(provisioningBearer, node)

Configure a Node

Hand the node an application key, create a group, bind the key to a model, and subscribe the model to the group.

Kotlin

val appKey = network.applicationKeys.create(boundNetworkKey = networkKey, name = "Lighting")
node.applicationKeys.add(appKey)

val livingRoom = network.groups.create(name = "Living Room")

val elementModels = node.elements[0u].models.getStored().orEmpty()
val lamp = elementModels.filterIsInstance<LightLightnessServerModel>().single()
lamp.boundApplicationKeys.bind(appKey)
lamp.subscriptions.add(livingRoom)

Control a Model

Every setter returns the state the node reports back, typed for that model.

Kotlin

val status = lamp.lightnessActual.setAcknowledged(appKey, lightness = 0x8000u)
println("Lamp is at ${status.presentLightness}")

Read a Sensor

Ask a sensor for a property and get exactly that property back, decoded and typed, including the spec’s “unknown” sentinels.

Kotlin

val temperature = sensor.forProperty(PresentAmbientTemperature).value.request(appKey)

when (val celsius = temperature.characteristic.celsius) {
    is Known -> println("${celsius.value} °C")
    Unknown -> println("The sensor has no reading")
}

Follow Live Updates

Incoming messages and stored state arrive through whatever your language already uses for a stream of values – no callbacks to register and no listeners to unregister.

Kotlin

lamp.lightnessActual.statuses.collect { status ->
    println("Lamp changed to ${status.presentLightness}")
}

Import and Export a Network

Networks move in and out as Mesh Configuration Database JSON, the format other provisioners read and write.

Kotlin

val networkId = MeshIo.importFromJson(storage, json, logger = logger)
val exportedJson = MeshIo.exportToJson(storage, network)

Compatibility

Spec Version Level of Support
Mesh Protocol 1.0.1 full
Mesh Protocol 1.1.1 partial
Mesh Model 1.0.1 full
Mesh Model 1.1.1 partial
Device Properties 2026-02-04 full
Mesh Configuration Database Profile 1.0.1 full
Ambient Light Sensor NLC Profile 1.0.1 full
Basic Lightness Controller NLC Profile 1.0.1 full
Basic Scene Selector NLC Profile 1.0.1 full
Dimming Control NLC Profile 1.0.1 full
Energy Monitor NLC Profile 1.0.1 full
Occupancy Sensor NLC Profile 1.0.1 full

Mesh Features

  • Provisioning with and without OOB (input, output, static) for increased security
  • Configuration (manage keys, set up publish/subscribe, heartbeats, relay, proxy, friend, etc.)
  • Send and receive client and server messages
  • All address types like unicast addresses, groups, and virtual labels
  • Scenes with store and recall
  • Proxy filter setup
  • IV Index update and secure network beacons (SNB)
  • Import and export networks using the Mesh Configuration Database Profile
  • Custom native implementations of bearers, storage, and logging possible

Will be added on demand:

  • Key Refresh Procedure

Architecture

What many developers don’t know is that Bluetooth® Mesh itself is “just software” sitting on top of Bluetooth® LE. While Bluetooth® LE needs an actual hardware chip plus native APIs, Bluetooth® Mesh just uses the existing hardware Bluetooth® LE as a bearer.

We used this to our advantage: all platform-agnostic code is written once and can be used from various programming languages on various operating systems.

Since the Bluetooth® Mesh code needs to interact with the target platform code eventually, there are a couple of native components to fill the gaps. Those components are decoupled using strict and stable interfaces, making it easy for you to implement your own. Alternatively, you can also use one of the many components we provide directly.

The BluKo Mesh Library core as a single block holding everything platform-agnostic - API, core, logic, crypto and messages. Three ports are carved
              out of its edge, one each for the bearer, storage and logging interfaces.
              Attached to those ports sit the interchangeable native implementations:
              a Bluetooth® LE bearer, SQLite storage and a console logger.
The multiplatform core talks to your platform through three interfaces. Use the implementations we ship, or plug in your own.

Pluggable Bearer ★

The bearer creates a point-to-point GATT connection to unprovisioned devices and proxy nodes. We ship implementations for Core Bluetooth (iOS, iPadOS, macOS), Android, Web Bluetooth (Chrome, Chromium) and JVM (Linux, Windows, macOS). Advertising bearers are also supported, but need to be implemented manually.

Pluggable Storage ★

During provisioning, a lot of data about the network and its nodes is generated. That data is stored in the central device database (CDB) and needs to be available to your application code.

The data may be stored in plain text files, in a local database, on a remote server, or in any other way. We provide ready-made implementations for local SQLite storage on all supported platforms, as well as a direct integration with the BluKo Mesh Synchronization infrastructure. You may also provide custom storage implementations if needed.

Pluggable Logging ★

Integrate your app’s own logging with the logging generated by the library. We recommend implementing the logging interface yourself to integrate optimally with your app, but basic debugging versions as well as an SLF4J implementation are provided.

Supported Bluetooth® Mesh Models

All models of the Bluetooth® Mesh model specification 1.0.1 are supported, as well as some models addded in 1.1. This includes (but is not limited to):

  • All generic models like on/off, level, power, battery, location and their setup servers.
  • All time and scenes models like time, scene, scheduler and their setup servers.
  • All sensor models including setup server and all device property IDs.
  • All lighting models like lightness, CTL, HSL, xyL, LC and their setup servers.

FAQ

1. Can I use the BluKo Mesh Library inside an Electron desktop app?

Yes, that is possible by using the TypeScript version together with a Node.js Bluetooth® LE bearer.

2. Why would I want to run a Bluetooth® Mesh stack on a server?

Good question. Using the BluKo Mesh Library on a server (or in the cloud) allows you to extend the mesh network beyond the physical location where the nodes are commissioned. For example, you can forward all Bluetooth® LE advertising packets over a WebSocket, bridging the physical mesh network with virtual nodes on a server. That is basically Bluetooth Mesh over IP, and it actually works very well by dramatically reducing the complexity of the gateways, by making it a “dumb” bridge.

3. What are the advantages of using a multi-platform Bluetooth® Mesh library?

If you create an app that targets more than one platform or operating system, it will lower the costs and time to market because:

  • developers do not need to learn multiple concepts and multiple APIs.
  • developers know that all features are available equally on all platforms.
  • developers can trust that error handling, encoding, decoding, etc., work the same on all platforms.

Additionally, you gain the flexibility to use Kotlin Multiplatform code for everything or only pick it where it makes the most sense. e.g.,

  • an iOS app with a native SwiftUI user interface using the BluKo Mesh Library for communication
  • or a Kotlin Multiplatform app using the same code for iOS and Android all the way through
  • a Bluetooth® Mesh app running inside a browser, maybe even downloaded from one of the mesh devices or a gateway
  • a Linux gateway that is part of the mesh network, performing protocol translation to MQTT, Modbus, etc.

4. Can I import and export the Central DB JSON?

Yes, the BluKo Mesh Library is compatible with the Mesh Configuration Database Profile as specified by the Bluetooth® SIG. However, for a production app, we do not recommend manual export/import of the CDB as it is prone to errors. Instead, consider using BluKo Mesh Sync, which will transparently synchronize the CDB with multiple devices using a reliable, offline-first 2-way sync engine. If you use our library, it only takes one line of code to add synchronization.

Availability

This library is still under development, with a first public version planned for 2026. Let us know if you are interested, and we will schedule a demo and talk you through the current state of development.


Funded by EFRE and ESF