feat: SDK improvements for Meshtastic-Android hard cutover (#1)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jamesarich

build.gradle.kts

@@ -16,17 +16,29 @@ plugins {
     alias(libs.plugins.spotless)
     alias(libs.plugins.detekt) apply false
     alias(libs.plugins.kover)
-    alias(libs.plugins.axionRelease)
+    // axionRelease applied conditionally below — it fails to apply when this build is
+    // included as a Gradle composite build because the root project is not yet available.
+    alias(libs.plugins.axionRelease) apply false
 }
 
-scmVersion {
-    tag {
-        prefix.set("v")
+// Only configure SCM versioning when running as a standalone build. When included as a
+// composite build (gradle.parent != null), version management is unnecessary and the plugin
+// errors out trying to reach the root project too early.
+if (gradle.parent == null) {
+    apply(plugin = "pl.allegro.tech.build.axion-release")
+    configure<pl.allegro.tech.build.axion.release.domain.VersionConfig> {
+        tag {
+            prefix.set("v")
+        }
+        versionIncrementer("incrementPatch")
     }
-    versionIncrementer("incrementPatch")
 }
 
-val resolvedVersion: String = scmVersion.version
+val resolvedVersion: String = if (gradle.parent == null) {
+    extensions.getByType<pl.allegro.tech.build.axion.release.domain.VersionConfig>().version
+} else {
+    "0.0.0-composite"
+}
 
 allprojects {
     group = "org.meshtastic"

core/api/core.klib.api

@@ -10,7 +10,16 @@ package org.meshtastic.sdk
 import org.meshtastic.proto.AdminMessage
 import org.meshtastic.proto.Channel
 import org.meshtastic.proto.Config
+import org.meshtastic.proto.DeviceConnectionStatus
+import org.meshtastic.proto.DeviceMetadata
+import org.meshtastic.proto.DeviceUIConfig
+import org.meshtastic.proto.HamParameters
+import org.meshtastic.proto.KeyVerificationAdmin
 import org.meshtastic.proto.ModuleConfig
+import org.meshtastic.proto.NodeRemoteHardwarePinsResponse
+import org.meshtastic.proto.Position
+import org.meshtastic.proto.SensorConfig
+import org.meshtastic.proto.SharedContact
 import org.meshtastic.proto.User
 import kotlin.time.Duration
 import kotlin.time.Instant
@@ -29,6 +38,44 @@ import kotlin.time.Instant
  */
 public interface AdminApi {
 
+    // ── Remote targeting ────────────────────────────────────────────────────
+
+    /**
+     * Return an [AdminApi] instance that targets [dest] instead of the local device.
+     *
+     * All calls on the returned instance route admin messages to the specified remote node
+     * over the mesh. Note: `editSettings`, `batch`, `getDeviceConnectionStatus`, and lifecycle
+     * commands (`reboot`, `shutdown`, `factoryReset`, `nodeDbReset`) work identically — the
+     * firmware handles admin-over-mesh transparently.
+     *
+     * ```kotlin
+     * val remoteAdmin = client.admin.forNode(NodeId(0x12345678.toInt()))
+     * remoteAdmin.setConfig(config) // → sent to remote node
+     * ```
+     *
+     * @param dest the target node's [NodeId]
+     * @return a remote-targeting [AdminApi] instance
+     * @since 0.2.0
+     */
+    public fun forNode(dest: NodeId): AdminApi
+
+    // ── Device info ─────────────────────────────────────────────────────────
+
+    /**
+     * Request [DeviceMetadata] from the device (firmware version, hardware model, etc.).
+     *
+     * For the local node, this is cached during handshake and available via
+     * [RadioClient.deviceConfig]. For remote nodes, use [forNode] to target the desired node:
+     *
+     * ```kotlin
+     * val metadata = client.admin.forNode(remoteNodeId).getDeviceMetadata()
+     * ```
+     *
+     * @return the device's metadata
+     * @since 0.2.0
+     */
+    public suspend fun getDeviceMetadata(): AdminResult<DeviceMetadata>
+
     // ── Configs ─────────────────────────────────────────────────────────────
 
     /** Read a single [Config] section from the device. */
@@ -75,6 +122,130 @@ public interface AdminApi {
     /** Mark [node] as ignored — packets from it are filtered before reaching apps. */
     public suspend fun setIgnored(node: NodeId, ignored: Boolean): AdminResult<Unit>
 
+    /**
+     * Toggle mute state on [node] — muted nodes do not forward packets.
+     *
+     * Note: The firmware uses a toggle primitive (`toggle_muted_node`), so calling this
+     * always flips the current state. Track local mute state if you need idempotent behavior.
+     */
+    public suspend fun toggleMuted(node: NodeId): AdminResult<Unit>
+
+    // ── Position ────────────────────────────────────────────────────────────
+
+    /** Set a fixed GPS position for the device (disables GPS module). */
+    public suspend fun setFixedPosition(position: Position): AdminResult<Unit>
+
+    /** Remove the fixed position and re-enable GPS. */
+    public suspend fun removeFixedPosition(): AdminResult<Unit>
+
+    // ── Device UI Config ────────────────────────────────────────────────────
+
+    /** Read the device's UI configuration (display preferences, language, etc.). */
+    public suspend fun getUIConfig(): AdminResult<DeviceUIConfig>
+
+    /** Write the device's UI configuration. */
+    public suspend fun storeUIConfig(config: DeviceUIConfig): AdminResult<Unit>
+
+    // ── Canned Messages ─────────────────────────────────────────────────────
+
+    /** Read the canned message module's preset messages. */
+    public suspend fun getCannedMessages(): AdminResult<String>
+
+    /** Write the canned message module's preset messages (pipe-delimited). */
+    public suspend fun setCannedMessages(messages: String): AdminResult<Unit>
+
+    // ── Ringtone ────────────────────────────────────────────────────────────
+
+    /** Read the device's ringtone (RTTTL format). */
+    public suspend fun getRingtone(): AdminResult<String>
+
+    /** Write the device's ringtone (RTTTL format). */
+    public suspend fun setRingtone(rtttl: String): AdminResult<Unit>
+
+    // ── Device status ───────────────────────────────────────────────────────
+
+    /** Read the device's connection status (WiFi, BLE, Ethernet, MQTT). */
+    public suspend fun getDeviceConnectionStatus(): AdminResult<DeviceConnectionStatus>
+
+    /** Read the remote hardware pin configuration of [node]. */
+    public suspend fun getRemoteHardwarePins(): AdminResult<NodeRemoteHardwarePinsResponse>
+
+    // ── Ham radio ───────────────────────────────────────────────────────────
+
+    /** Configure the device for amateur radio use (sets call sign, disables encryption). */
+    public suspend fun setHamMode(params: HamParameters): AdminResult<Unit>
+
+    // ── DFU / file management ───────────────────────────────────────────────
+
+    /**
+     * Enter DFU (firmware update) mode. The device will reboot into its bootloader.
+     *
+     * This is a fire-and-forget admin write; [AdminResult.Success] means the request was queued
+     * locally, not that the device stayed connected long enough to acknowledge the reboot.
+     */
+    public suspend fun enterDfuMode(): AdminResult<Unit>
+
+    /** Delete a file from the device's filesystem. */
+    public suspend fun deleteFile(path: String): AdminResult<Unit>
+
+    // ── Backup / Restore ────────────────────────────────────────────────────
+
+    /** Back up device preferences to the specified [location]. */
+    public suspend fun backupPreferences(
+        location: AdminMessage.BackupLocation = AdminMessage.BackupLocation.FLASH,
+    ): AdminResult<Unit>
+
+    /** Restore device preferences from the specified [location]. */
+    public suspend fun restorePreferences(
+        location: AdminMessage.BackupLocation = AdminMessage.BackupLocation.FLASH,
+    ): AdminResult<Unit>
+
+    /** Remove a stored preference backup from [location]. */
+    public suspend fun removeBackupPreferences(
+        location: AdminMessage.BackupLocation = AdminMessage.BackupLocation.FLASH,
+    ): AdminResult<Unit>
+
+    // ── Node removal ────────────────────────────────────────────────────────
+
+    /** Remove a node from the device's NodeDB by its node number. */
+    public suspend fun removeNode(node: NodeId): AdminResult<Unit>
+
+    // ── Input / Display ─────────────────────────────────────────────────────
+
+    /** Set the device's scale calibration value (e-ink display DPI). */
+    public suspend fun setScale(scale: Int): AdminResult<Unit>
+
+    /** Send a synthetic input event to the device (button press, touch, etc.). */
+    public suspend fun sendInputEvent(event: AdminMessage.InputEvent): AdminResult<Unit>
+
+    // ── Contacts ────────────────────────────────────────────────────────────
+
+    /** Add a shared contact to the device's contact list. */
+    public suspend fun addContact(contact: SharedContact): AdminResult<Unit>
+
+    // ── Key verification ────────────────────────────────────────────────────
+
+    /** Initiate or respond to a key verification exchange. */
+    public suspend fun keyVerification(verification: KeyVerificationAdmin): AdminResult<Unit>
+
+    // ── OTA updates ─────────────────────────────────────────────────────────
+
+    /** Reboot into OTA update mode after [after] (default: immediately). */
+    public suspend fun rebootOta(after: Duration = Duration.ZERO): AdminResult<Unit>
+
+    /** Send an OTA event (firmware update control). */
+    public suspend fun otaRequest(event: AdminMessage.OTAEvent): AdminResult<Unit>
+
+    // ── Sensor ──────────────────────────────────────────────────────────────
+
+    /** Configure a sensor attached to the device. */
+    public suspend fun setSensorConfig(config: SensorConfig): AdminResult<Unit>
+
+    // ── Simulator ───────────────────────────────────────────────────────────
+
+    /** Exit the firmware simulator mode (development only). */
+    public suspend fun exitSimulator(): AdminResult<Unit>
+
     // ── Lifecycle ───────────────────────────────────────────────────────────
 
     /**
@@ -101,14 +272,25 @@ public interface AdminApi {
     /**
      * Wipe the device's NodeDB, forcing a fresh discovery cycle on the mesh.
      *
-     * @param preserveFavorites when `true` (default), entries marked as favorites are kept. The
-     *   firmware does not currently expose a separate flag for this; on devices that always erase
-     *   the entire NodeDB, the SDK's [setFavorite] state on local entries is the only persistence.
+     * The firmware always preserves favorite-marked entries during the wipe (this is
+     * firmware-enforced behavior). The `nodedb_reset` proto field uses proto3 semantics where
+     * only `true` can be encoded — a "wipe everything including favorites" mode is not
+     * available through this command.
+     *
+     * The device will reboot after the reset completes.
      */
-    public suspend fun nodeDbReset(preserveFavorites: Boolean = true): AdminResult<Unit>
+    public suspend fun nodeDbReset(): AdminResult<Unit>
 
     // ── Time ────────────────────────────────────────────────────────────────
 
+    /**
+     * Set the device's wall clock from raw Unix time seconds without sending position data.
+     *
+     * This uses `AdminMessage.set_time_only` directly and is fire-and-forget; [AdminResult.Success]
+     * means the packet was queued locally.
+     */
+    public suspend fun setTimeOnly(unixTime: Int): AdminResult<Unit>
+
     /**
      * Set the device's wall clock to [at] (default: `Clock.System.now()`).
      *
@@ -127,6 +309,14 @@ public interface AdminApi {
      * or commit fails, the result reflects that failure and the block's return value is discarded.
      */
     public suspend fun <T> editSettings(block: suspend AdminEdit.() -> T): AdminResult<T>
+
+    /**
+     * Exception-based counterpart to [editSettings] that also exposes batched getter helpers.
+     *
+     * Getter failures throw [AdminResultException] via [getOrThrow]. If [block] throws, the SDK
+     * does not send `commit_edit_settings`; firmware eventually discards the buffered edits.
+     */
+    public suspend fun <T> batch(block: suspend AdminBatchScope.() -> T): T
 }
 
 /**
@@ -146,3 +336,15 @@ public interface AdminEdit {
     public suspend fun setFavorite(node: NodeId, favorite: Boolean)
     public suspend fun setIgnored(node: NodeId, ignored: Boolean)
 }
+
+/**
+ * Receiver type for [AdminApi.batch] — combines [AdminEdit] setters with getter helpers.
+ *
+ * Getter failures throw [AdminResultException] via [getOrThrow]. Setters share the same deferred
+ * commit semantics as [AdminApi.editSettings].
+ */
+public interface AdminBatchScope : AdminEdit {
+    public suspend fun getConfig(type: AdminMessage.ConfigType): Config
+    public suspend fun getModuleConfig(type: AdminMessage.ModuleConfigType): ModuleConfig
+    public suspend fun listChannels(): List<Channel>
+}

core/api/jvm/core.api

@@ -11,7 +11,7 @@ import kotlin.time.Duration
 import kotlin.time.Duration.Companion.seconds
 
 /**
- * Tunables for the engine's built-in auto-reconnect supervisor.
+ * Configuration for the engine's built-in auto-reconnect supervisor.
  *
  * Configure on the [RadioClient.Builder] via
  * [autoReconnect(...)][RadioClient.Builder.autoReconnect].

core/src/commonMain/kotlin/org/meshtastic/sdk/AdminApi.kt

@@ -10,11 +10,12 @@ package org.meshtastic.sdk
 import org.meshtastic.proto.DeviceMetrics
 import org.meshtastic.proto.Telemetry
 /**
- * Curated battery health and state information.
+ * Curated battery health and state information reported by the device.
  *
  * @property percent charge level (0..100).
  * @property voltageVolts raw battery voltage, if reported.
  * @property pluggedIn `true` if the device is currently drawing external power.
+ * @since 0.1.0
  */
 public data class BatteryStatus(
     public val percent: Int?,
@@ -23,9 +24,10 @@ public data class BatteryStatus(
 )
 
 /**
- * Converts protobuf [DeviceMetrics] to [BatteryStatus].
+ * Converts protobuf [DeviceMetrics] into a normalized [BatteryStatus] snapshot.
  *
  * Maps the firmware's `>= 101` level sentinel to [BatteryStatus.pluggedIn].
+ * @since 0.1.0
  */
 public fun DeviceMetrics.toBatteryStatus(): BatteryStatus? {
     if (battery_level == null && voltage == null) return null