core/org.meshtastic.sdk/AdminApi

AdminApi

Device configuration and control RPCs.

Each method maps onto a single AdminMessage round-trip with the local device. Failures that are part of the normal operating envelope (timeout, unauthorized, session-key expiry, node unreachable for remote-admin paths) surface as typed AdminResult variants. Catastrophic failures (transport gone, engine torn down) throw MeshtasticException.

Acquired via RadioClient.admin. Available only while the client is connected.

Since

0.1.0

Functions

addContact

abstract suspend fun addContact(contact: SharedContact): AdminResult<Unit>

Add a shared contact to the device's contact list.

backupPreferences

abstract suspend fun backupPreferences(location: AdminMessage.BackupLocation = AdminMessage.BackupLocation.FLASH): AdminResult<Unit>

Back up device preferences to the specified location.

batch

abstract suspend fun <T> batch(block: suspend AdminBatchScope.() -> T): T

Exception-based counterpart to editSettings that also exposes batched getter helpers.

deleteFile

abstract suspend fun deleteFile(path: String): AdminResult<Unit>

Delete a file from the device's filesystem.

editSettings

abstract suspend fun <T> editSettings(block: suspend AdminEdit.() -> T): AdminResult<T>

Run block inside a begin_edit_settings / commit_edit_settings envelope so the device applies all writes atomically (avoids reboot-mid-edit corruption).

enterDfuMode

abstract suspend fun enterDfuMode(): AdminResult<Unit>

Enter DFU (firmware update) mode. The device will reboot into its bootloader.

exitSimulator

abstract suspend fun exitSimulator(): AdminResult<Unit>

Exit the firmware simulator mode (development only).

factoryReset

abstract suspend fun factoryReset(preserveBleBonds: Boolean = true): AdminResult<Unit>

Erase device state and reset to factory defaults.

forNode

abstract fun forNode(dest: NodeId): AdminApi

Return an AdminApi instance that targets dest instead of the local device.

getCannedMessages

abstract suspend fun getCannedMessages(): AdminResult<String>

Read the canned message module's preset messages.

getChannel

abstract suspend fun getChannel(index: ChannelIndex): AdminResult<Channel>

Read the Channel at index (0..7).

getConfig

abstract suspend fun getConfig(type: AdminMessage.ConfigType): AdminResult<Config>

Read a single Config section from the device.

getDeviceConnectionStatus

abstract suspend fun getDeviceConnectionStatus(): AdminResult<DeviceConnectionStatus>

Read the device's connection status (WiFi, BLE, Ethernet, MQTT).

getDeviceMetadata

abstract suspend fun getDeviceMetadata(): AdminResult<DeviceMetadata>

Request DeviceMetadata from the device (firmware version, hardware model, etc.).

getModuleConfig

abstract suspend fun getModuleConfig(type: AdminMessage.ModuleConfigType): AdminResult<ModuleConfig>

Read a single ModuleConfig section from the device.

getOwner

abstract suspend fun getOwner(): AdminResult<User>

Read the local node's User (long name / short name / hardware model / public key).

getRemoteHardwarePins

abstract suspend fun getRemoteHardwarePins(): AdminResult<NodeRemoteHardwarePinsResponse>

Read the remote hardware pin configuration of node.

getRingtone

abstract suspend fun getRingtone(): AdminResult<String>

Read the device's ringtone (RTTTL format).

getUIConfig

abstract suspend fun getUIConfig(): AdminResult<DeviceUIConfig>

Read the device's UI configuration (display preferences, language, etc.).

keyVerification

abstract suspend fun keyVerification(verification: KeyVerificationAdmin): AdminResult<Unit>

Initiate or respond to a key verification exchange.

listChannels

abstract suspend fun listChannels(): AdminResult<List<Channel>>

Read every configured channel (indices 0..7).

lockdown

abstract suspend fun lockdown(auth: LockdownAuth): AdminResult<Unit>

Provision, unlock, or lock the device's storage lockdown (MESHTASTIC_LOCKDOWN hardened firmware builds only).

nodeDbReset

abstract suspend fun nodeDbReset(): AdminResult<Unit>

Wipe the device's NodeDB, forcing a fresh discovery cycle on the mesh.

otaRequest

abstract suspend fun otaRequest(event: AdminMessage.OTAEvent): AdminResult<Unit>

Send an OTA event (firmware update control).

reboot

abstract suspend fun reboot(after: Duration = Duration.ZERO): AdminResult<Unit>

Reboot the device after after (default: immediately).

rebootOta

abstract suspend fun rebootOta(after: Duration = Duration.ZERO): AdminResult<Unit>

Reboot into OTA update mode after after (default: immediately).

removeBackupPreferences

abstract suspend fun removeBackupPreferences(location: AdminMessage.BackupLocation = AdminMessage.BackupLocation.FLASH): AdminResult<Unit>

Remove a stored preference backup from location.

removeFixedPosition

abstract suspend fun removeFixedPosition(): AdminResult<Unit>

Remove the fixed position and re-enable GPS.

removeNode

abstract suspend fun removeNode(node: NodeId): AdminResult<Unit>

Remove a node from the device's NodeDB by its node number.

restorePreferences

abstract suspend fun restorePreferences(location: AdminMessage.BackupLocation = AdminMessage.BackupLocation.FLASH): AdminResult<Unit>

Restore device preferences from the specified location.

sendInputEvent

abstract suspend fun sendInputEvent(event: AdminMessage.InputEvent): AdminResult<Unit>

Send a synthetic input event to the device (button press, touch, etc.).

setAmbientLightingConfig

suspend fun AdminApi.setAmbientLightingConfig(block: ModuleConfig.AmbientLightingConfig.() -> ModuleConfig.AmbientLightingConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.AmbientLightingConfig in a single call.

setAudioConfig

suspend fun AdminApi.setAudioConfig(block: ModuleConfig.AudioConfig.() -> ModuleConfig.AudioConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.AudioConfig in a single call.

setBluetoothConfig

suspend fun AdminApi.setBluetoothConfig(block: Config.BluetoothConfig.() -> Config.BluetoothConfig): AdminResult<Unit>

Convenience: build and send a Config.BluetoothConfig in a single call.

setCannedMessageConfig

suspend fun AdminApi.setCannedMessageConfig(block: ModuleConfig.CannedMessageConfig.() -> ModuleConfig.CannedMessageConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.CannedMessageConfig in a single call.

setCannedMessages

abstract suspend fun setCannedMessages(messages: String): AdminResult<Unit>

Write the canned message module's preset messages (pipe-delimited).

setChannel

abstract suspend fun setChannel(channel: Channel): AdminResult<Unit>

Write a Channel. The slot is determined by Channel.index.

setConfig

abstract suspend fun setConfig(config: Config): AdminResult<Unit>

Write a Config section to the device.

setDetectionSensorConfig

suspend fun AdminApi.setDetectionSensorConfig(block: ModuleConfig.DetectionSensorConfig.() -> ModuleConfig.DetectionSensorConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.DetectionSensorConfig in a single call.

setDeviceConfig

suspend fun AdminApi.setDeviceConfig(block: Config.DeviceConfig.() -> Config.DeviceConfig): AdminResult<Unit>

Convenience: build and send a Config.DeviceConfig in a single call.

setDisplayConfig

suspend fun AdminApi.setDisplayConfig(block: Config.DisplayConfig.() -> Config.DisplayConfig): AdminResult<Unit>

Convenience: build and send a Config.DisplayConfig in a single call.

setExternalNotificationConfig

suspend fun AdminApi.setExternalNotificationConfig(block: ModuleConfig.ExternalNotificationConfig.() -> ModuleConfig.ExternalNotificationConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.ExternalNotificationConfig in a single call.

setFavorite

abstract suspend fun setFavorite(node: NodeId, favorite: Boolean): AdminResult<Unit>

Mark node as a favorite (persisted in firmware NodeDB).

setFixedPosition

abstract suspend fun setFixedPosition(position: Position): AdminResult<Unit>

Set a fixed GPS position for the device (disables GPS module).

setHamMode

abstract suspend fun setHamMode(params: HamParameters): AdminResult<Unit>

Configure the device for amateur radio use (sets call sign, disables encryption).

setIgnored

abstract suspend fun setIgnored(node: NodeId, ignored: Boolean): AdminResult<Unit>

Mark node as ignored — packets from it are filtered before reaching apps.

setLoraConfig

suspend fun AdminApi.setLoraConfig(block: Config.LoRaConfig.() -> Config.LoRaConfig): AdminResult<Unit>

Convenience: build and send a Config.LoRaConfig in a single call.

setModuleConfig

abstract suspend fun setModuleConfig(config: ModuleConfig): AdminResult<Unit>

Write a ModuleConfig section to the device.

setMqttConfig

suspend fun AdminApi.setMqttConfig(block: ModuleConfig.MQTTConfig.() -> ModuleConfig.MQTTConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.MQTTConfig in a single call.

setNeighborInfoConfig

suspend fun AdminApi.setNeighborInfoConfig(block: ModuleConfig.NeighborInfoConfig.() -> ModuleConfig.NeighborInfoConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.NeighborInfoConfig in a single call.

setNetworkConfig

suspend fun AdminApi.setNetworkConfig(block: Config.NetworkConfig.() -> Config.NetworkConfig): AdminResult<Unit>

Convenience: build and send a Config.NetworkConfig in a single call.

setOwner

abstract suspend fun setOwner(user: User): AdminResult<Unit>

Update the local node's User. Persists across reboots.

setPaxcounterConfig

suspend fun AdminApi.setPaxcounterConfig(block: ModuleConfig.PaxcounterConfig.() -> ModuleConfig.PaxcounterConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.PaxcounterConfig in a single call.

setPositionConfig

suspend fun AdminApi.setPositionConfig(block: Config.PositionConfig.() -> Config.PositionConfig): AdminResult<Unit>

Convenience: build and send a Config.PositionConfig in a single call.

setPowerConfig

suspend fun AdminApi.setPowerConfig(block: Config.PowerConfig.() -> Config.PowerConfig): AdminResult<Unit>

Convenience: build and send a Config.PowerConfig in a single call.

setRangeTestConfig

suspend fun AdminApi.setRangeTestConfig(block: ModuleConfig.RangeTestConfig.() -> ModuleConfig.RangeTestConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.RangeTestConfig in a single call.

setRemoteHardwareConfig

suspend fun AdminApi.setRemoteHardwareConfig(block: ModuleConfig.RemoteHardwareConfig.() -> ModuleConfig.RemoteHardwareConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.RemoteHardwareConfig in a single call.

setRingtone

abstract suspend fun setRingtone(rtttl: String): AdminResult<Unit>

Write the device's ringtone (RTTTL format).

setScale

abstract suspend fun setScale(scale: Int): AdminResult<Unit>

Set the device's scale calibration value (e-ink display DPI).

setSecurityConfig

suspend fun AdminApi.setSecurityConfig(block: Config.SecurityConfig.() -> Config.SecurityConfig): AdminResult<Unit>

Convenience: build and send a Config.SecurityConfig in a single call.

setSensorConfig

abstract suspend fun setSensorConfig(config: SensorConfig): AdminResult<Unit>

Configure a sensor attached to the device.

setSerialConfig

suspend fun AdminApi.setSerialConfig(block: ModuleConfig.SerialConfig.() -> ModuleConfig.SerialConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.SerialConfig in a single call.

setStatusMessageConfig

suspend fun AdminApi.setStatusMessageConfig(block: ModuleConfig.StatusMessageConfig.() -> ModuleConfig.StatusMessageConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.StatusMessageConfig in a single call.

setStoreForwardConfig

suspend fun AdminApi.setStoreForwardConfig(block: ModuleConfig.StoreForwardConfig.() -> ModuleConfig.StoreForwardConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.StoreForwardConfig in a single call.

setTelemetryConfig

suspend fun AdminApi.setTelemetryConfig(block: ModuleConfig.TelemetryConfig.() -> ModuleConfig.TelemetryConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.TelemetryConfig in a single call.

setTime

abstract suspend fun setTime(at: Instant? = null): AdminResult<Unit>

Set the device's wall clock to at (default: Clock.System.now()).

setTimeOnly

abstract suspend fun setTimeOnly(unixTime: Int): AdminResult<Unit>

Set the device's wall clock from raw Unix time seconds without sending position data.

setTrafficManagementConfig

suspend fun AdminApi.setTrafficManagementConfig(block: ModuleConfig.TrafficManagementConfig.() -> ModuleConfig.TrafficManagementConfig): AdminResult<Unit>

Convenience: build and send a ModuleConfig.TrafficManagementConfig in a single call.

shutdown

abstract suspend fun shutdown(after: Duration = Duration.ZERO): AdminResult<Unit>

Power down the device after after (default: immediately).

storeUIConfig

abstract suspend fun storeUIConfig(config: DeviceUIConfig): AdminResult<Unit>

Write the device's UI configuration.

toggleMuted

abstract suspend fun toggleMuted(node: NodeId): AdminResult<Unit>

Toggle mute state on node — muted nodes do not forward packets.