Kotlin Multiplatform SDK for Meshtastic nodes. It connects to a node over Bluetooth LE, TCP or USB serial from Android, JVM and iOS, and over the node's WebSocket phone API from those targets and from browser or Node.js hosts (Kotlin/JS and Kotlin/Wasm).
The API reference (Dokka) is published from main. The SDK is pre-1.0, so APIs can change between minor versions; see docs/versioning.md.
A Kotlin library that talks to Meshtastic nodes over the PhoneAPI, the protocol the official Android and Apple clients use. It owns the wire-protocol details (handshake, NodeDB, ACK correlation, channel decryption, retries) and exposes them as coroutines, flows and sealed types.
Use it to build:
- Companion apps for Android, iOS and desktop.
- Headless gateways and telemetry collectors on the JVM.
- Browser and Node.js tools on Kotlin/JS or Kotlin/Wasm, running the engine in-process over
transport-websocket.
The SDK has no UI components, navigation or storage policy. docs/decisions/000-charter.md lists the non-goals.
// build.gradle.kts
dependencies {
implementation("org.meshtastic:sdk-core:0.2.0")
implementation("org.meshtastic:sdk-transport-tcp:0.2.0") // pick a transport
implementation("org.meshtastic:sdk-storage-sqldelight:0.2.0") // pick a storage
}Transport modules: transport-ble, transport-tcp, transport-serial (JVM and Android; on Android, jSerialComm or usb-serial-for-android) and transport-websocket. Storage: storage-sqldelight, InMemoryStorageProvider from core when nothing has to outlive the process, or your own StorageProvider. The sdk-bom platform aligns every module version; see bom/README.md.
API marked @since 0.3.0 is in snapshots only until 0.3.0 is released. That covers transport-websocket, the JS and Wasm klibs, and the discovery APIs.
Every push to main publishes the patch after the latest release as -SNAPSHOT (0.2.1-SNAPSHOT after 0.2.0) to the Sonatype Central snapshot repository:
// settings.gradle.kts
dependencyResolutionManagement {
repositories {
mavenCentral()
maven("https://central.sonatype.com/repository/maven-snapshots/") {
mavenContent { snapshotsOnly() }
}
}
}
// build.gradle.kts
dependencies {
implementation("org.meshtastic:sdk-core:0.2.1-SNAPSHOT")
}Snapshots are rebuilt on every commit to main. Depend on a released version for reproducible builds.
The full module matrix is in docs/architecture/module-graph.md. Deferred modules are tracked in docs/roadmap.md: transport-mqtt-proxy is R-11, and the remote-RPC modules (transport-rpc, host-rpc-server) are R-12, designed in docs/future/wasm-rpc-roadmap.md.
import org.meshtastic.sdk.RadioClient
import org.meshtastic.sdk.SendOutcome
import org.meshtastic.sdk.storage.sqldelight.SqlDelightStorageProvider
import org.meshtastic.sdk.transport.tcp.TcpTransport
suspend fun run() {
val client = RadioClient.Builder()
.transport(TcpTransport(host = "meshtastic.local", port = 4403))
.storage(SqlDelightStorageProvider(baseDir = "/tmp")) // empty string = in-memory
.build()
client.connect() // throws MeshtasticException on failure
val handle = client.sendText("hello mesh")
when (val outcome = handle.await()) { // suspends until terminal
SendOutcome.Success -> println("acked or rebroadcast heard")
is SendOutcome.Failure -> println("failed: ${outcome.reason}")
}
// Or observe progress:
// handle.state.collect { println(it) } // Queued → Sent → Acked/Delivered/Failed
}client.nodes never completes, so collect it in its own coroutine to observe NodeDB changes while sending:
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import org.meshtastic.sdk.NodeChange
import org.meshtastic.sdk.RadioClient
suspend fun observeAndSend(client: RadioClient) = coroutineScope {
val nodesJob = launch {
client.nodes.collect { change ->
when (change) {
is NodeChange.Snapshot -> println("seeded with ${change.nodes.size} nodes")
is NodeChange.Added -> println("+ ${change.node.user?.long_name}")
is NodeChange.Updated -> println("~ ${change.node.user?.long_name} (${change.changed})")
is NodeChange.Removed -> println("- ${change.nodeId}")
is NodeChange.WentOffline -> println("${change.nodeId} offline")
is NodeChange.CameOnline -> println("${change.nodeId} online")
}
}
}
client.sendText("hello mesh").await() // not blocked by the collector
nodesJob.cancel()
}Wire-generated proto fields are snake_case (user.long_name, not user.longName). On Android, set AndroidContextHolder.context = applicationContext in Application.onCreate() before constructing a SqlDelightStorageProvider; the integration guide covers this and the Bluetooth and USB setup.
Only the Builder.transport(...) line changes between transports. Each ships in its own artifact.
// Bluetooth LE: Android, iOS and JVM desktop, through Kable.
// The caller holds the Bluetooth permissions; see the integration guide.
import kotlinx.coroutines.flow.first
import org.meshtastic.sdk.transport.ble.BleScanner
import org.meshtastic.sdk.transport.ble.BleTransport
suspend fun firstBleNode(): BleTransport = BleTransport(BleScanner.scan().first())// USB serial: JVM (jSerialComm). Android uses AndroidSerialPorts or AndroidUsbSerialPorts.
import org.meshtastic.sdk.transport.serial.JvmSerialPorts
val portName = JvmSerialPorts.findMeshtastic().first().name // ports with a Meshtastic USB vendor ID
val transport = JvmSerialPorts.open(portName, baudRate = 115200)// TCP: Android, iOS and JVM
import org.meshtastic.sdk.transport.tcp.TcpTransport
val transport = TcpTransport(host = "meshtastic.local", port = 4403)// WebSocket phone API: every target, including JS and Wasm
import org.meshtastic.sdk.transport.websocket.WebSocketTransport
val transport = WebSocketTransport("ws://meshtastic.local")Discovery lives with each transport: BleScanner.scan() in transport-ble, mDNS through TcpDiscovery in transport-tcp, and findMeshtastic() with isLikelyMeshtastic() in transport-serial. TransportTarget.parse in core reads a ble:, tcp: or serial: spec string, the form the CLI sample takes. Each module's Module.md has the details.
The integration guide has per-platform setup: Android runtime permissions, foreground services on API 34+, USB intent filters and iOS Info.plist keys. The error-handling guide covers what to retry and what to surface. The full API is in docs/api-reference.md.
| Symptom | Likely cause | Fix |
|---|---|---|
connect() throws MeshtasticException.Transport on TCP |
Host unreachable, or the node's network API is off | Check the node's IP or hostname and that Wi-Fi or Ethernet is enabled. See TCP setup. |
connect() hangs or fails repeatedly over Bluetooth |
The node isn't bonded with the OS | Pair the node in the OS Bluetooth settings first. See Bluetooth. |
JvmSerialPorts.open(...) fails with permission denied |
Serial device permission not granted | On Linux, add the user to dialout. On Android, request USB permission first. See Serial. |
sendText throws MeshtasticException.PayloadTooLarge |
The text is over the 233-byte payload limit (DATA_PAYLOAD_LEN) |
Split the text. See Sending messages. |
connect() throws MeshtasticException.HandshakeTimeout |
The want_config_id reply never arrived |
Power-cycle the node, check its firmware version, then retry. See Build a RadioClient. |
Every published module builds jvm, androidTarget (minSdk = 26), iosArm64, iosX64 and iosSimulatorArm64 through the meshtastic.kmp.library convention plugin. core, testing and transport-websocket also publish js and wasmJs klibs through meshtastic.js.library (ADR-017). docs/architecture/module-graph.md has the dependency graph.
| Module | JVM | Android (minSdk 26) |
iOS Arm64 | iOS Sim Arm64 | iOS X64 | JS | Wasm | Notes |
|---|---|---|---|---|---|---|---|---|
core |
✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | Transport-agnostic engine; re-exports the org.meshtastic:protobufs types. |
transport-ble |
✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | Kable. Web targets use the browser's Web Bluetooth backend. |
transport-tcp |
✓ | ✓ | ✓ | ✓ | ✓ | — | — | Ktor sockets; mDNS discovery per platform. |
transport-websocket |
✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | Ktor client (CIO on JVM and Android, Darwin on iOS, the platform WebSocket on JS and Wasm). Needs firmware#12412 (ESP32) or #12413 (meshtasticd), both unmerged; plain ws:// on meshtasticd needs #12414. |
transport-serial |
✓ | ✓ | — | — | — | — | — | Android: jSerialComm, or usb-serial-for-android (compileOnly, the host adds it). The iOS klibs carry only the common types; iOS has no serial backend. |
storage-sqldelight |
✓ | ✓ | ✓ | ✓ | ✓ | — | — | SQLDelight: JDBC driver on the JVM, Android driver on Android, native driver on iOS. |
testing |
✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | FakeRadioTransport and TestClock for commonTest. |
✓ means built and tested in CI. — means no artifact for that target, or no platform API for that transport.
The JS and Wasm klibs (org.meshtastic:sdk-core-js, org.meshtastic:sdk-core-wasm-js) are compiled into the consumer's own bundle, Compose Multiplatform for web included. transport-websocket reaches a node from either, and a host can supply its own RadioTransport (Web Bluetooth, Web Serial). CI tests both targets on Node.js, not in a browser.
docs/protocol.md: wire protocol (PhoneAPI, MeshPacket, channel encryption, MQTT proxy).docs/api-reference.md: public Kotlin signatures.docs/error-taxonomy.md: what throws, what returnsAdminResult, what surfaces asMeshEvent.docs/glossary.md: NodeNum and NodeId,request_idandpacket_id, channel hash.docs/architecture/: handshake FSM, engine actor, storage and module graph.docs/integration-guide.md: dependencies, per-transport setup, storage and lifecycle in a host app.docs/consumer-guides/error-handling.md: what to retry and what to surface.docs/decisions/: ADRs.docs/roadmap.md: deferred items.docs/versioning.md: SemVer and ABI policy.docs/security.md: threat model and scope.docs/manual-tests.md: device conformance suite that CI can't run.docs/ci-cd.md: GitHub Actions workflows.docs/samples.md: what each sample demonstrates.
git clone git@github.com:meshtastic/meshtastic-sdk.git
cd meshtastic-sdk
./gradlew checkcheck builds and runs the tests, Spotless, detekt, checkKotlinAbi and :core:verifyModuleBoundary. It needs:
- JDK 21.
- The Android SDK platform named by
androidCompileSdkingradle/libs.versions.toml, withANDROID_HOMEset. - Node.js on
PATHfor thejsandwasmJstargets; Gradle doesn't download it. - Xcode on macOS for the iOS targets.
docs/ci-cd.md lists the targeted commands.
- Android API 26 (Android 8.0) or later. Every Android artifact sets
minSdk = 26, so an app with a lowerminSdkfails to resolve the dependency. See Platform support. - iOS 14 or later for the Bluetooth and TCP transports.
- A JDK 17 or later runtime on the JVM. The bytecode targets JDK 17; the build toolchain is JDK 21.
- kotlinx-coroutines 1.8.1 or later for
core,storage-sqldelightandtransport-serial, which compile against that floor;transport-tcp,transport-websocketandtransport-bleneed 1.11.0 through Ktor and Kable. A newer pin in your build wins at resolution.
Sign every commit with the Developer Certificate of Origin (DCO):
git commit -s -m "Your message"CONTRIBUTING.md has the full flow.
GPL-3.0-or-later. See LICENSE and docs/decisions/004-licensing.md.
meshtastic/firmware: the device-side reference for protocol behavior.meshtastic/protobufs: the wire schema, consumed as the publishedorg.meshtastic:protobufsartifact.meshtastic/Meshtastic-Androidandmeshtastic/Meshtastic-Apple: the official clients, used for cross-validation.meshtastic/MQTTastic-Client-KMP: sibling KMP library for direct MQTT broker use.