core/org.meshtastic.sdk/SendBuilder

SendBuilder

Builder for an outbound MeshPacket. Created by RadioClient.send (DSL form).

Exactly one payload setter (text, data, position, or proto) must be called per builder. Calling more than one — or calling none — throws IllegalStateException from build.

When proto is used the entire packet is taken as-is; subsequent calls to to, channel, wantAck, or hopLimit throw IllegalStateException because they would silently overwrite caller-supplied wire fields. Set those on the MeshPacket you pass to proto instead.

Example:

val handle = client.send {
    text("hello world")
    to(NodeId(0xa1b2c3d4.toInt()))
    channel(ChannelIndex(2))
    wantAck()
    hopLimit(3)
}

Since

0.1.0

Functions

channel

fun channel(channel: ChannelIndex)

Set the ChannelIndex this packet is sent on. Defaults to channel 0.

data

fun data(portnum: PortNum, bytes: ByteArray)

Use bytes as the wire payload for portnum. Mutually exclusive with the other payload setters.

hopLimit

fun hopLimit(hops: Int?)

Override the per-packet hop limit. null (the default) leaves the proto-default 0 so the firmware applies its configured global default.

position

fun position(latLng: LatLng)

Encode a Position payload from latLng (latitude/longitude in degrees, optional altitude in meters). Mutually exclusive with the other payload setters. Uses latitude_i = (lat * 1e7).toInt() per firmware convention.

proto

fun proto(packet: MeshPacket)

Escape hatch — use packet verbatim as the entire outbound packet. After calling proto, the convenience setters to, channel, wantAck, and hopLimit all throw IllegalStateException.

text

fun text(text: String)

Encode text as a TEXT_MESSAGE_APP payload (UTF-8). Mutually exclusive with the other payload setters.

fun to(nodeId: NodeId)

Set the destination NodeId. Defaults to NodeId.BROADCAST.

wantAck

fun wantAck()

Shorthand for wantAck(true).

fun wantAck(value: Boolean)

Request a delivery ACK from the firmware. Defaults to false (no ACK requested).