core/org.meshtastic.sdk/MeshEvent

MeshEvent

Side-channel event from the SDK engine.

These are non-packet events: queue status updates, errors, key-verification prompts, etc. Emitted via RadioClient.events alongside RadioClient.packets and RadioClient.nodes.

Since

0.1.0

Inheritors

LockdownStatusChanged

Types

CongestionWarning

data class CongestionWarning(val metrics: CongestionMetrics) : MeshEvent

Emitted when congestion metrics cross a threshold level. Clients should use metrics to decide whether to delay non-urgent sends.

DeviceRebooted

data class DeviceRebooted(val reason: String = "device reported reboot") : MeshEvent

Device reported FromRadio.rebooted = true — the radio restarted mid-session (crash, intentional reboot via admin, firmware update, or brownout). The engine treats this as a forced disconnect: pending sends fail, handshake state resets, and ConnectionState transitions to Disconnected. Higher-level reconnect policy (if any) then restarts the session from scratch.

ExternalConfigChange

data class ExternalConfigChange(val kind: ExternalChangeKind) : MeshEvent

An external source (another admin client) pushed a configuration change to the connected device. The engine has already applied the update to local state (RadioClient.config, RadioClient.channels). Subscribers should refresh any cached configuration.

FileInfoReceived

data class FileInfoReceived(val info: FileInfo) : MeshEvent

The device announced a file in its on-device filesystem (sent during the handshake or after file operations).

IdentityRebound

data class IdentityRebound(val previousNodeNum: NodeId, val newNodeNum: NodeId, val reason: String = "device factory reset or identity change") : MeshEvent

The connected device reported a different NodeNum than the one previously persisted for this transport identity (e.g. factory reset, radio swap, or hostname re-pointed at a different physical radio).

KeyVerification

data class KeyVerification(val prompt: KeyVerificationPrompt) : MeshEvent

Key verification prompt (e.g., "confirm the radio's public key").

LockdownStatusChanged

data class LockdownStatusChanged(val status: LockdownStatus) : MeshEvent

The connected device reported its hardened-build lockdown state.

MqttConnected

data object MqttConnected : MeshEvent

Emitted when the device's MQTT connection state changes to connected.

MqttDisconnected

data class MqttDisconnected(val reason: String? = null) : MeshEvent

Emitted when the device's MQTT connection drops.

MqttProxyMessage

data class MqttProxyMessage(val message: MqttClientProxyMessage) : MeshEvent

The device asked the host to relay an MQTT message on its behalf (MQTT client proxy).

Notification

data class Notification(val notification: ClientNotification) : MeshEvent

Device emitted a notification.

PacketsDropped

data class PacketsDropped(val flow: DroppedFlow, val count: Int) : MeshEvent

A flow dropped messages due to subscriber backpressure.

ProtocolWarning

data class ProtocolWarning(val message: String, val details: Map<String, Any?> = emptyMap()) : MeshEvent

Protocol-level warning (malformed data, unexpected state, etc.).

QueueStatusChanged

data class QueueStatusChanged(val status: QueueStatus) : MeshEvent

Device's transmit queue status changed.

SecurityWarning

sealed interface SecurityWarning : MeshEvent

Security-relevant warning from the device, surfaced as typed sub-variants so that hosts can react without string-parsing. These arrive from org.meshtastic.proto.ClientNotification but the engine also still re-emits the raw Notification for callers that want the underlying wire payload.

StorageDegraded

data class StorageDegraded(val reason: String) : MeshEvent

Storage backend reported a persistent I/O failure (disk full, permission denied, locked database, etc.) and the engine has dropped into degraded mode. Subsequent storage writes are skipped for the remainder of the session; in-memory state continues to flow on RadioClient.packets, RadioClient.nodes, and RadioClient.events so the user-visible session is preserved, but nothing is written to disk until the next RadioClient.connect.

TransportError

data class TransportError(val error: MeshtasticException.Transport) : MeshEvent

A transport-level error occurred.

XmodemPacket

data class XmodemPacket(val packet: XModem) : MeshEvent

An XModem file-transfer frame arrived from the device.