Raised when the peripheral is ready to resolve the characteristic and the characteristic is absent from the device's GATT database. Ready to resolve means Peripheral.services is populated and Peripheral.state is a stable State.Connected substate other than State.Connected.ServiceChanged.

DecodedObservation

sealed interface DecodedObservation<out T>

Typed equivalent of com.atruedev.kmpble.gatt.Observation.

DecodeFailureException

class DecodeFailureException(val bytes: ByteArray, cause: Throwable) : PeripheralCodecException

Raised when a BleDecoder rejects a value read from a characteristic. The raw bytes are preserved for logging or inspection of the malformed payload, and the underlying decoder exception is preserved as the cause.

Framer

interface Framer

Wraps and recovers payloads on a stream transport (L2CAP CoC, an MTU-spanning concatenation, etc.).

FrameTooLargeException

class FrameTooLargeException(val size: Long, val maxSize: Int) : RuntimeException

Thrown from Unframer.feed when a length prefix exceeds the configured cap. Indicates a malformed stream or hostile peer; the Unframer should not be reused.

Int16Codec

object Int16Codec : BleCodec<Int>

Little-endian signed 16-bit integer codec (-32768..32767). Strict size on decode.

Int32Codec

object Int32Codec : BleCodec<Int>

Little-endian signed 32-bit integer codec. Strict size on decode.

Int8Codec

object Int8Codec : BleCodec<Int>

Single-byte signed integer codec (-128..127). Strict size on decode.

LengthPrefixFramer

class LengthPrefixFramer(maxFrameSize: Int = DEFAULT_MAX_FRAME_SIZE) : Framer

Length-prefix framing: each frame is [length: uint32 LE][payload: bytes].

PeripheralCodecException

sealed class PeripheralCodecException : RuntimeException

Sealed root of failures raised by readAs / writeAs / observeAs that originate inside the codec layer (as opposed to the underlying BLE op).

PeripheralNotReadyException

class PeripheralNotReadyException(val serviceUuid: Uuid, val characteristicUuid: Uuid, val currentState: State) : PeripheralCodecException

Raised when the peripheral is not ready to resolve the characteristic: discovery has not completed, the cached service list is pending invalidation (State.Connected.ServiceChanged), or the peripheral is disconnecting/disconnected. Retry after Peripheral.state reaches State.Connected.Ready, reconnecting first if necessary. The currentState is captured at dispatch time for diagnostics.

RawBytesCodec

object RawBytesCodec : BleCodec<ByteArray>

Codec that passes bytes through unchanged. Defensive copies on both sides.

TypedL2capChannel

class TypedL2capChannel<T> : AutoCloseable

A typed, framed view over an L2capChannel.

Uint16Codec

object Uint16Codec : BleCodec<Int>

Little-endian unsigned 16-bit integer codec (0..65535). Strict size on decode.

Uint32Codec

object Uint32Codec : BleCodec<Long>

Little-endian unsigned 32-bit integer codec (0..4_294_967_295). Strict size on decode.

Uint8Codec

object Uint8Codec : BleCodec<Int>

Single-byte unsigned integer codec (0..255). Common for level/enum characteristics like Battery Level (0x2A19).

Unframer

interface Unframer

Stateful inverse of Framer.frame. Implementations buffer partial frames across feed calls; each call returns zero or more complete payloads.

Utf8StringCodec

object Utf8StringCodec : BleCodec<String>

UTF-8 string codec. decode throws on malformed UTF-8 byte sequences via ByteArray.decodeToString with throwOnInvalidSequence = true. The exact exception type is platform-dependent (CharacterCodingException on JVM, kotlin.io.CharacterCodingException on Native); treat as a generic decode failure.

Functions

asBleDataDecoder

fun <T> BleDecoder<T>.asBleDataDecoder(): BleDataDecoder<T>

Bridge a BleDecoder to work with BleData input.

asBleDataEncoder

fun <T> BleEncoder<T>.asBleDataEncoder(): BleDataEncoder<T>

Bridge a BleEncoder to produce BleData via BleData factory.

asBleDecoder

fun <T> BleDataDecoder<T>.asBleDecoder(): BleDecoder<T>

Bridge a BleDataDecoder to work with ByteArray input.

asBleEncoder

fun <T> BleDataEncoder<T>.asBleEncoder(): BleEncoder<T>

Bridge a BleDataEncoder to produce ByteArray via BleData.toByteArray.

bimap

fun <A, B> BleCodec<A>.bimap(encode: (B) -> A, decode: (A) -> B): BleCodec

Transform both directions of this codec.

bleCodec

fun <T> bleCodec(encoder: BleEncoder<T>, decoder: BleDecoder<T>): BleCodec<T>

Combine a standalone BleEncoder and BleDecoder into a BleCodec.

contramap

fun <A, B> BleDataEncoder.contramap(transform: (A) -> B): BleDataEncoder<A>

Transform the input of this BleData encoder.

fun <A, B> BleEncoder.contramap(transform: (A) -> B): BleEncoder<A>

Transform the input of this encoder.

decodeFramed

fun <T> Flow<ByteArray>.decodeFramed(decoder: BleDecoder<T>, framer: Framer = LengthPrefixFramer(), onDecodeFailure: (ByteArray) -> Unit = {}): Flow<T>

Combines unframing and decoding into one operator: byte chunks in, typed values out.

decodeManufacturerData

fun <T> Advertisement.decodeManufacturerData(companyId: Int, decoder: BleDataDecoder<T>): T?

Decode manufacturer-specific data. Zero-copy on iOS.

decodeServiceData

fun <T> Advertisement.decodeServiceData(serviceUuid: Uuid, decoder: BleDataDecoder<T>): T?

Decode service-specific data. Zero-copy on iOS.

fold

inline fun <T, R> DecodedObservation<T>.fold(onValue: (T) -> R, onDisconnected: () -> R): R

Eliminate a DecodedObservation by applying the matching function.

framedConnections

fun <T> L2capListener.framedConnections(codec: BleCodec<T>, framer: Framer = LengthPrefixFramer(), onDecodeFailure: (ByteArray) -> Unit = {}): Flow<TypedL2capChannel<T>>

Accept incoming L2CAP connections and pre-wrap each one as a TypedL2capChannel using the supplied codec and framer.

framedIncoming

fun <T> L2capChannel.framedIncoming(decoder: BleDecoder<T>, framer: Framer = LengthPrefixFramer(), onDecodeFailure: (ByteArray) -> Unit = {}): Flow<T>

Decode framed payloads from the L2CAP incoming stream.

incoming

fun <T> L2capChannel.incoming(decoder: BleDecoder<T>): Flow<T>

Decode each incoming L2CAP packet into a typed value.

indicate

suspend fun <T> GattServer.indicate(characteristicUuid: Uuid, device: Identifier, value: T, encoder: BleDataEncoder<T>)

Encode a value directly to BleData and send it as an indication.

suspend fun <T> GattServer.indicate(characteristicUuid: Uuid, device: Identifier, value: T, encoder: BleEncoder<T>)

Encode a value and send it as an indication.

map

fun <A, B> BleDataDecoder<A>.map(transform: (A) -> B): BleDataDecoder

Transform the output of this BleData decoder.

fun <A, B> BleDecoder<A>.map(transform: (A) -> B): BleDecoder

Transform the output of this decoder.

notify

suspend fun <T> GattServer.notify(characteristicUuid: Uuid, device: Identifier?, value: T, encoder: BleDataEncoder<T>)

Encode a value directly to BleData and send it as a notification.

suspend fun <T> GattServer.notify(characteristicUuid: Uuid, device: Identifier?, value: T, encoder: BleEncoder<T>)

Encode a value and send it as a notification.

observe

fun <T> Peripheral.observe(characteristic: Characteristic, decoder: BleDecoder<T>, backpressure: BackpressureStrategy = BackpressureStrategy.Latest): Flow<DecodedObservation<T>>

Observe decoded observations, including disconnect events.

observeAs

fun <T> Peripheral.observeAs(serviceUuid: Uuid, characteristicUuid: Uuid, decoder: BleDecoder<T>, backpressure: BackpressureStrategy = BackpressureStrategy.Latest, onDecodeFailure: (ByteArray) -> Unit = {}): Flow<T>

Observes notifications/indications from a characteristic addressed by service+characteristic UUID, decoding each payload with decoder.

observeValues

fun <T> Peripheral.observeValues(characteristic: Characteristic, decoder: BleDecoder<T>, backpressure: BackpressureStrategy = BackpressureStrategy.Latest): Flow<T>

Observe decoded values with transparent reconnection.

read

suspend fun <T> Peripheral.read(characteristic: Characteristic, decoder: BleDecoder<T>): T

Read a characteristic and decode the result.

readAs

suspend fun <T> Peripheral.readAs(serviceUuid: Uuid, characteristicUuid: Uuid, decoder: BleDecoder<T>): Result<T>

Reads a characteristic by service+characteristic UUID and decodes the value.

unframedBy

fun Flow<ByteArray>.unframedBy(framer: Framer): Flow<ByteArray>

Adapts a stream of byte chunks (e.g. from an L2CAP CoC incoming flow) into a stream of complete framed payloads.

write

suspend fun <T> L2capChannel.write(value: T, encoder: BleEncoder<T>)

Encode a value and write it to the L2CAP channel.

suspend fun <T> Peripheral.write(characteristic: Characteristic, value: T, encoder: BleEncoder<T>, writeType: WriteType = WriteType.WithResponse)

Encode a value and write it to a characteristic.

writeAs

suspend fun <T> Peripheral.writeAs(serviceUuid: Uuid, characteristicUuid: Uuid, value: T, encoder: BleEncoder<T>, writeType: WriteType = WriteType.WithResponse): Result<Unit>

Encodes value with encoder and writes it to a characteristic addressed by service+characteristic UUID. Failure cases mirror readAs:

writeFramed

suspend fun <T> L2capChannel.writeFramed(value: T, encoder: BleEncoder<T>, framer: Framer = LengthPrefixFramer())

Encode a value, frame the bytes, and write the framed packet.