kmp-ble-mesh/com.atruedev.kmpble.mesh

Package-level declarations

Types

data class AccessMessage(val opcode: MeshOpcode, val parameters: ByteArray, val isAcknowledged: Boolean = true)

An Access Layer message for application-level communication.

data class ApplicationKey(val index: KeyIndex, val key: ByteArray, val boundNetKeyIndex: KeyIndex, val name: String = "AppKey ") : MeshKey

Application Key bound to a Network Key.

CompositionDataUnavailable

data class CompositionDataUnavailable(val nodeAddress: MeshAddress.UnicastAddress, val recoveryHint: String = "Composition data not available. Verify the node is connected and configured.") : ConfigurationError

ConfigurationError

sealed interface ConfigurationError : MeshError

Errors returned by the Configuration Client.

ConfigurationRejected

data class ConfigurationRejected(val opcode: Int, val statusCode: UByte, val recoveryHint: String = "Configuration command was rejected by the node. Check that the operation is valid for this node.") : ConfigurationError

DecryptionFailed

data class DecryptionFailed(val details: String, val recoveryHint: String = "Decryption failure. Possible IV Index mismatch, wrong key, or corrupted PDU.") : MeshCryptoError

DeviceAlreadyProvisioned

data class DeviceAlreadyProvisioned(val uuid: String, val recoveryHint: String = "Device is already provisioned on another network. Reset the device first.") : ProvisioningError

DeviceKey

data class DeviceKey(val key: ByteArray) : MeshKey

Device Key unique to a single node.

ElementLocation

enum ElementLocation : Enum<ElementLocation>

Element location descriptor as defined by the Bluetooth SIG.

EncryptionFailed

data class EncryptionFailed(val details: String, val recoveryHint: String = "Encryption failure. Verify that the correct keys are configured for this network.") : MeshCryptoError

ExperimentalMeshApi

@RequiresOptIn(level = RequiresOptIn.Level.WARNING, message = "This BLE Mesh API is experimental and may change in future releases.")

@Target(allowedTargets = [AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.TYPEALIAS])

annotation class ExperimentalMeshApi

Marks APIs that are experimental and may change without notice.

InMemoryMeshStateStore

class InMemoryMeshStateStore : MeshStateStore

In-memory implementation of MeshStateStore for testing.

InvalidParameters

data class InvalidParameters(val message: String, val recoveryHint: String = "Invalid parameters for mesh operation.") : MeshError

IvIndex

@JvmInline

value class IvIndex(val value: UInt)

Represents the current IV Index state of the mesh network.

KeyIndex

@JvmInline

value class KeyIndex(val value: UShort)

12-bit key index (0x000-0xFFF).

KeyRefreshPhase

enum KeyRefreshPhase : Enum<KeyRefreshPhase>

Key Refresh procedure phases for a NetworkKey.

MeshAddress

sealed interface MeshAddress : Comparable<MeshAddress>

Address types used in BLE Mesh networking.

MeshCryptoError

sealed interface MeshCryptoError : MeshError

Errors related to mesh cryptography.

MeshDsl

@DslMarker

annotation class MeshDsl

DSL marker to prevent invalid nesting in MeshNetworkBuilder.

MeshElement

data class MeshElement(val index: Int, val unicastAddress: MeshAddress.UnicastAddress, val location: ElementLocation = ElementLocation.UNKNOWN, val models: List<MeshModelId> = emptyList())

An addressable entity within a MeshNode.

MeshError

sealed interface MeshError

Root of the BLE Mesh error hierarchy.

MeshException

data class MeshException(val error: MeshError) : Exception

Exception wrapper for MeshError values, allowing them to be thrown.

MeshKey

sealed interface MeshKey

Base type for all mesh keys.

MeshMessage

data class MeshMessage(val source: MeshAddress.UnicastAddress, val destination: MeshAddress, val opcode: MeshOpcode, val parameters: ByteArray, val appKey: ApplicationKey?)

A complete mesh message sent or received via the public API.

MeshMessageResponse

data class MeshMessageResponse(val opcode: MeshOpcode, val parameters: ByteArray)

Response to an acknowledged mesh message.

MeshModelId

@JvmInline

value class MeshModelId(val value: UInt)

Identifies a mesh model on an element.

MeshNetwork

interface MeshNetwork : AutoCloseable

A BLE Mesh network.

MeshNetworkBuilder

class MeshNetworkBuilder

Builder DSL for MeshNetwork configuration.

MeshNetworkState

data class MeshNetworkState(val ivIndex: IvIndex, val unicastAddress: MeshAddress.UnicastAddress, val networkKeys: List<NetworkKey>, val applicationKeys: List<ApplicationKey>, val nodes: List<PersistedNodeState>, val groupAddresses: List<MeshAddress.GroupAddress> = emptyList(), val lastUpdatedTimestamp: Long = 0)

Serializable snapshot of the complete mesh network state.

MeshNode

data class MeshNode(val unicastAddress: MeshAddress.UnicastAddress, val deviceKey: DeviceKey, val elements: List<MeshElement>, val features: NodeFeatures = NodeFeatures(), val ttl: UByte = DEFAULT_TTL, val networkKeys: List<NetworkKey> = emptyList(), val applicationKeys: List<ApplicationKey> = emptyList())

A provisioned node on the BLE Mesh network.

MeshNotSupported

data class MeshNotSupported(val message: String = "BLE Mesh is not supported on this platform") : Exception, MeshError

MeshOpcode

@JvmInline

value class MeshOpcode(val value: UInt)

Operation code for mesh model messages.

MeshStateStore

interface MeshStateStore

Persistence SPI for BLE Mesh network state.

MeshTransportError

sealed interface MeshTransportError : MeshError

Errors related to mesh transport (bearer, proxy, network).

MessageRejected

data class MessageRejected(val reason: String, val recoveryHint: String = "The mesh message was rejected by the network layer (possible replay or key issue).") : MeshTransportError

MessageTimeout

data class MessageTimeout(val operation: String, val timeout: Duration, val recoveryHint: String = "No response received from mesh node. Check that the device is powered and in range.") : MeshTransportError

NetworkKey

data class NetworkKey(val index: KeyIndex, val key: ByteArray, val name: String = "NetKey ", val phase: KeyRefreshPhase = KeyRefreshPhase.NORMAL) : MeshKey

Network Key shared by all nodes in a (sub)net.

NetworkPdu

data class NetworkPdu(val ivi: Int, val nid: Int, val ctl: Int, val ttl: Int, val seq: UInt, val src: MeshAddress.UnicastAddress, val dst: MeshAddress, val transportPdu: ByteArray, val netMic: ByteArray)

A complete Network PDU ready for transmission over a bearer.

NodeFeatures

data class NodeFeatures(val relay: Boolean = false, val proxy: Boolean = false, val friend: Boolean = false, val lowPower: Boolean = false)

Features supported by a mesh node.

NodeNotFound

data class NodeNotFound(val address: MeshAddress.UnicastAddress, val recoveryHint: String = "Node not found in network. Verify the unicast address.") : MeshError

OobAuthenticationFailed

data class OobAuthenticationFailed(val method: String, val recoveryHint: String = "Verify the OOB key matches the device, or try a different OOB method.") : ProvisioningError

PersistedNodeState

data class PersistedNodeState(val unicastAddress: MeshAddress.UnicastAddress, val deviceKey: DeviceKey, val lastSequenceNumber: UInt, val features: NodeFeatures = NodeFeatures())

Per-node state that must be persisted across restarts.

ProvisioningError

sealed interface ProvisioningError : MeshError

Errors that occur during the provisioning process.

ProvisioningFailed

data class ProvisioningFailed(val phase: ProvisioningPhase, val reason: String, val recoveryHint: String = "Retry provisioning. Verify the device is in range and not already provisioned.") : ProvisioningError

ProvisioningPhase

enum ProvisioningPhase : Enum<ProvisioningPhase>

Phases of the provisioning protocol for error reporting.

ProvisioningTimeout

data class ProvisioningTimeout(val timeout: Duration, val recoveryHint: String = "Increase provisioning timeout or verify device responsiveness.") : ProvisioningError

ProxyConnection

interface ProxyConnection : AutoCloseable

A connection to a GATT Proxy node.

ProxyConnectionFailed

data class ProxyConnectionFailed(val reason: String, val recoveryHint: String = "Verify the proxy node is in range and has the proxy feature enabled.") : MeshTransportError

ProxyDisconnected

data class ProxyDisconnected(val reason: String, val recoveryHint: String = "Proxy connection lost. Reconnecting automatically if reconnection strategy is configured.") : MeshTransportError

ProxyMessageType

enum ProxyMessageType : Enum<ProxyMessageType>

Message type carried in a Proxy PDU.

ProxyPdu

data class ProxyPdu(val sar: ProxySarType, val messageType: ProxyMessageType, val data: ByteArray)

A Proxy PDU as carried over the GATT Proxy bearer.

ProxySarType

enum ProxySarType : Enum<ProxySarType>

Proxy SAR (Segmentation and Reassembly) type.

TransportPdu

data class TransportPdu(val isSegmented: Boolean, val akf: Boolean, val aid: Int, val seqZero: Int, val segO: Int, val segN: Int, val payload: ByteArray, val transportMic: ByteArray)

A Transport PDU before network-layer encryption.

Functions

MeshNetwork

actual fun MeshNetwork(builder: MeshNetworkBuilder.() -> Unit): MeshNetwork

Android implementation of MeshNetwork factory.

expect fun MeshNetwork(builder: MeshNetworkBuilder.() -> Unit): MeshNetwork

Platform-specific factory for MeshNetwork.

actual fun MeshNetwork(builder: MeshNetworkBuilder.() -> Unit): MeshNetwork

iOS implementation of MeshNetwork factory.

actual fun MeshNetwork(builder: MeshNetworkBuilder.() -> Unit): MeshNetwork

JVM implementation -- BLE Mesh is not supported on JVM.