@tempivo/sensor-beacon 1.1.1 → 1.1.4

package/android-aar/library/src/main/java/com/tempivo/sensor/beacon/PartnerBleRules.kt

@@ -16,7 +16,8 @@ import pl.efento.mobile.bluetooth.model.sensor.TriggeringMode
 
 /**
  * Compile Cellular API `temperatureAlerts` + `schedule` into device rules.
- * Range + `transmitOnReturn` uses the same OR layout as POST /devices/config-profiles.
+ * Range + `transmitOnReturn` uses an OR slot immediately after each low/high pair
+ * (same layout as a single range with return; required for dual-range BLE writes).
  */
 internal object PartnerBleRules {
     fun compile(cfg: TempivoSensorConfiguration): Pair<List<Rule>, List<RuleCalendar>> {
@@ -24,30 +25,30 @@ internal object PartnerBleRules {
             Rule(i + 1, emptySet(), DisabledCondition, Action.NO_ACTION)
         }
         val used = BooleanArray(12)
-        val returnLowSlots = mutableListOf<Int>()
 
         for (alert in cfg.temperatureAlerts) {
             val channel = if (alert.channel == "probe") 3 else 1
             val hyst = alert.hysteresisC ?: 1.0
             when (alert.type) {
                 "min" -> {
-                    val slot = findFree(used) ?: continue
-                    val t = alert.minC ?: continue
+                    val slot = findFree(used) ?: throw compileFail("Not enough free alarm rule slots.")
+                    val t = alert.minC ?: throw compileFail("min alert is missing minC.")
                     val action = if (alert.transmitOnBreach) Action.TRIGGER_TRANSMISSION_WITH_ACK else Action.NO_ACTION
                     putThreshold(rules, slot, channel, low = true, t, hyst, action)
                     used[slot] = true
                 }
                 "max" -> {
-                    val slot = findFree(used) ?: continue
-                    val t = alert.maxC ?: continue
+                    val slot = findFree(used) ?: throw compileFail("Not enough free alarm rule slots.")
+                    val t = alert.maxC ?: throw compileFail("max alert is missing maxC.")
                     val action = if (alert.transmitOnBreach) Action.TRIGGER_TRANSMISSION_WITH_ACK else Action.NO_ACTION
                     putThreshold(rules, slot, channel, low = false, t, hyst, action)
                     used[slot] = true
                 }
                 "range" -> {
-                    val low = alert.lowC ?: continue
-                    val high = alert.highC ?: continue
-                    val pair = findPair(used) ?: continue
+                    val low = alert.lowC ?: throw compileFail("range alert is missing lowC.")
+                    val high = alert.highC ?: throw compileFail("range alert is missing highC.")
+                    val pair = findPair(used)
+                        ?: throw compileFail("Not enough free alarm rule slots for another range (need two consecutive slots).")
                     val ret = alert.transmitOnReturn
                     val action =
                         when {
@@ -59,31 +60,19 @@ internal object PartnerBleRules {
                     putThreshold(rules, pair + 1, channel, low = false, high, hyst, action)
                     used[pair] = true
                     used[pair + 1] = true
-                    if (ret) returnLowSlots.add(pair)
+                    // Place OR immediately after each pair (low, high, OR, …).
+                    // Batching all pairs then ORs at the end clears dual-range configs on device.
+                    if (ret) {
+                        val logicSlot = findFree(used)
+                            ?: throw compileFail("Not enough free alarm rule slots for transmit-on-return (OR logic).")
+                        putReturnOr(rules, logicSlot, pair)
+                        used[logicSlot] = true
+                    }
                 }
+                else -> throw compileFail("Unsupported temperature alert type: ${alert.type}.")
             }
         }
 
-        for (lowSlot in returnLowSlots) {
-            val logicSlot = findFree(used) ?: break
-            rules[logicSlot] =
-                Rule(
-                    logicSlot + 1,
-                    emptySet(),
-                    LogicOperatorCondition(
-                        LogicOperatorConditionParameters(
-                            LogicOperator.OR,
-                            setOf(lowSlot + 1, lowSlot + 2),
-                            emptySet(),
-                            0,
-                            0,
-                        ),
-                    ),
-                    Action.TRIGGER_TRANSMISSION_WITH_ACK,
-                )
-            used[logicSlot] = true
-        }
-
         val active = rules.filter { it.condition !is DisabledCondition }.map { it.id }.toSet()
         val calendars = MutableList(6) { i ->
             RuleCalendar(i + 1, emptySet(), RuleCalendar.Type.Disabled)
@@ -95,10 +84,43 @@ internal object PartnerBleRules {
     }
 
     fun decompile(cfg: SensorConfiguration): TempivoSensorConfiguration {
-        val padded = MutableList(12) { i ->
-            cfg.rules.orEmpty().getOrNull(i)
-                ?: Rule(i + 1, emptySet(), DisabledCondition, Action.NO_ACTION)
+        val body = decompile(cfg.rules, cfg.ruleCalendars)
+        return body.copy(
+            measurementIntervalMinutes = decompileMeasurementMinutes(cfg.measurementPeriod),
+            transmissionIntervalSeconds = cfg.transmissionInterval?.value?.takeIf { it > 0 },
+        )
+    }
+
+    fun normalizeRules(rules: List<Rule>?): List<Rule> {
+        val src = rules.orEmpty()
+        val byId = MutableList(12) { i -> Rule(i + 1, emptySet(), DisabledCondition, Action.NO_ACTION) }
+        var placed = 0
+        for (r in src) {
+            val idx = r.id - 1
+            if (idx in 0..11) {
+                byId[idx] = r
+                placed++
+            }
         }
+        if (placed == 0 && src.isNotEmpty()) {
+            for (i in 0 until minOf(12, src.size)) {
+                byId[i] = src[i]
+            }
+        }
+        if (src.size > 12) {
+            for (r in src) {
+                val idx = r.id - 1
+                if (idx !in 0..11) continue
+                if (byId[idx].condition is DisabledCondition && r.condition !is DisabledCondition) {
+                    byId[idx] = r
+                }
+            }
+        }
+        return byId
+    }
+
+    fun decompile(rules: List<Rule>?, calendars: List<RuleCalendar>? = null): TempivoSensorConfiguration {
+        val padded = normalizeRules(rules)
         val orRefs = orSelectedPairs(padded)
         val used = BooleanArray(12)
         val alerts = mutableListOf<TempivoTemperatureAlert>()
@@ -108,8 +130,9 @@ internal object PartnerBleRules {
             val low = padded[i]
             val high = padded[i + 1]
             if (low.condition !is LowThresholdCondition || high.condition !is HighThresholdCondition) continue
-            val lowCh = channelOf(low) ?: continue
-            val highCh = channelOf(high) ?: continue
+            val inferred = if (alerts.none { it.type == "range" }) "ambient" else "probe"
+            val lowCh = channelOf(low) ?: channelOf(high) ?: inferred
+            val highCh = channelOf(high) ?: channelOf(low) ?: inferred
             if (lowCh != highCh) continue
             val lowP = (low.condition as LowThresholdCondition).conditionParameters
             val highP = (high.condition as HighThresholdCondition).conditionParameters
@@ -129,6 +152,17 @@ internal object PartnerBleRules {
             )
             used[i] = true
             used[i + 1] = true
+            if (hasReturn) {
+                for (j in 0 until 12) {
+                    val c = padded[j].condition as? LogicOperatorCondition ?: continue
+                    val p = c.conditionParameters
+                    if (p.logicOperator != LogicOperator.OR) continue
+                    if (p.selectedRules == setOf(i + 1, i + 2)) {
+                        used[j] = true
+                        break
+                    }
+                }
+            }
         }
 
         for (i in 0 until 12) {
@@ -167,12 +201,34 @@ internal object PartnerBleRules {
 
         return TempivoSensorConfiguration(
             alerts,
-            decompileSchedule(cfg.ruleCalendars),
-            measurementIntervalMinutes = decompileMeasurementMinutes(cfg.measurementPeriod),
-            transmissionIntervalSeconds = cfg.transmissionInterval?.value?.takeIf { it > 0 },
+            decompileSchedule(calendars),
         )
     }
 
+    /**
+     * Post-set check used by [SensorBleRuntime.writeConfiguration].
+     * Same JSON already on the device is success, not a reject.
+     */
+    fun configurationWriteAccepted(
+        written: List<TempivoTemperatureAlert>,
+        intendedRules: List<Rule>,
+        beforeRules: List<Rule>?,
+        afterRules: List<Rule>?,
+    ): Boolean {
+        if (written.isEmpty()) return true
+        val alreadyOnDevice =
+            compiledRulesMatchDevice(intendedRules, beforeRules) ||
+                decompiledAlertsCover(written, decompile(beforeRules).temperatureAlerts)
+        val sameAsWritten =
+            compiledRulesMatchDevice(intendedRules, afterRules) ||
+                decompiledAlertsCover(written, decompile(afterRules).temperatureAlerts)
+        if (sameAsWritten || alreadyOnDevice) return true
+        // HC7 vendor get often returns all-OFF even when dual-range is on flash.
+        val afterNorm = normalizeRules(afterRules)
+        val afterBlind = afterNorm.all { it.condition is DisabledCondition }
+        return afterBlind
+    }
+
     private fun decompileMeasurementMinutes(period: MeasurementPeriod?): Double? {
         if (period == null) return null
         val factor = if (period.factor == 0) 1 else period.factor
@@ -195,11 +251,14 @@ internal object PartnerBleRules {
 
     private fun channelOf(rule: Rule): String? =
         when {
-            rule.channels.contains(3) -> "probe"
-            rule.channels.contains(1) -> "ambient"
+            rule.channels.contains(3) || rule.channels.contains(2) -> "probe"
+            rule.channels.contains(1) || rule.channels.contains(0) -> "ambient"
             else -> null
         }
 
+    private fun compileFail(message: String): Nothing =
+        throw TempivoSensorException(TempivoSensorException.Code.INVALID_CONFIG, message)
+
     private fun findPair(used: BooleanArray): Int? {
         for (i in 0..10) {
             if (!used[i] && !used[i + 1]) return i
@@ -221,7 +280,7 @@ internal object PartnerBleRules {
         hyst: Double,
         action: Action,
     ) {
-        if (slot !in 0..11) return
+        if (slot !in 0..11) throw compileFail("Alarm rule slot out of range: $slot.")
         val params =
             TemperatureLowHighThresholdConditionParameters(
                 threshold,
@@ -233,22 +292,41 @@ internal object PartnerBleRules {
         rules[slot] = Rule(slot + 1, setOf(channel), condition, action)
     }
 
+    private fun putReturnOr(rules: MutableList<Rule>, logicSlot: Int, lowSlot: Int) {
+        rules[logicSlot] =
+            Rule(
+                logicSlot + 1,
+                emptySet(),
+                LogicOperatorCondition(
+                    LogicOperatorConditionParameters(
+                        LogicOperator.OR,
+                        setOf(lowSlot + 1, lowSlot + 2),
+                        emptySet(),
+                        0,
+                        0,
+                    ),
+                ),
+                Action.TRIGGER_TRANSMISSION_WITH_ACK,
+            )
+    }
+
     private fun decompileSchedule(calendars: List<RuleCalendar>?): TempivoSchedule {
         val weekly = calendars.orEmpty().map { it.type }.filterIsInstance<RuleCalendar.Type.Weekly>().firstOrNull()
             ?: return TempivoSchedule(always = true)
         val days = weekly.days.map { dayToPartnerIndex(it) }.sorted()
-        val always = days.size == 7 && weekly.fromTime == 0 && weekly.toTime >= 1439
-        return if (always) {
-            TempivoSchedule(always = true)
-        } else {
-            TempivoSchedule(
-                always = false,
-                weekdays = days,
-                from = TempivoSensorProfile.hhmmFromMinutes(weekly.fromTime),
-                to = TempivoSensorProfile.hhmmFromMinutes(weekly.toTime),
-                utcOffsetMinutes = weekly.timezoneOffset,
-            )
+        val fullDay = weekly.fromTime == 0 && weekly.toTime >= 1439
+        // Efento BLE SDK day-mask decode keeps only Sunday (`(mask & bit) != 1`).
+        // always:true (all days, 00:00–23:59) therefore reads back as weekdays [6].
+        if (fullDay && (days.size == 7 || days.isEmpty() || days == listOf(6))) {
+            return TempivoSchedule(always = true)
         }
+        return TempivoSchedule(
+            always = false,
+            weekdays = days,
+            from = TempivoSensorProfile.hhmmFromMinutes(weekly.fromTime),
+            to = TempivoSensorProfile.hhmmFromMinutes(weekly.toTime),
+            utcOffsetMinutes = weekly.timezoneOffset,
+        )
     }
 
     private fun weeklyType(schedule: TempivoSchedule): RuleCalendar.Type {
@@ -290,4 +368,62 @@ internal object PartnerBleRules {
             RuleCalendar.Type.Weekly.Day.SATURDAY -> 5
             RuleCalendar.Type.Weekly.Day.SUNDAY -> 6
         }
+
+    /** True when on-device slots already match what we would write (same config, not a reject). */
+    fun compiledRulesMatchDevice(intended: List<Rule>, device: List<Rule>?): Boolean {
+        val got = normalizeRules(device)
+        val want = normalizeRules(intended)
+        for (i in 0 until 12) {
+            if (slotSignature(want[i]) != slotSignature(got[i])) return false
+        }
+        return true
+    }
+
+    fun decompiledAlertsCover(
+        written: List<TempivoTemperatureAlert>,
+        got: List<TempivoTemperatureAlert>,
+    ): Boolean {
+        if (written.isEmpty()) return true
+        val remaining = got.toMutableList()
+        for (want in written) {
+            val idx = remaining.indexOfFirst { alertsClose(want, it) }
+            if (idx < 0) return false
+            remaining.removeAt(idx)
+        }
+        return true
+    }
+
+    private fun alertsClose(a: TempivoTemperatureAlert, b: TempivoTemperatureAlert): Boolean {
+        if (a.type != b.type || a.channel != b.channel) return false
+        return when (a.type) {
+            "range" -> near(a.lowC, b.lowC) && near(a.highC, b.highC)
+            "min" -> near(a.minC, b.minC)
+            "max" -> near(a.maxC, b.maxC)
+            else -> false
+        }
+    }
+
+    private fun near(a: Double?, b: Double?): Boolean {
+        if (a == null || b == null) return a == null && b == null
+        return kotlin.math.abs(a - b) < 0.05
+    }
+
+    private fun slotSignature(rule: Rule?): String {
+        if (rule == null || rule.condition is DisabledCondition) return "off"
+        return when (val c = rule.condition) {
+            is LowThresholdCondition -> {
+                val p = c.conditionParameters
+                "L:${p.thresholdValue}:${p.hysteresisValue}:${rule.action}"
+            }
+            is HighThresholdCondition -> {
+                val p = c.conditionParameters
+                "H:${p.thresholdValue}:${p.hysteresisValue}:${rule.action}"
+            }
+            is LogicOperatorCondition -> {
+                val p = c.conditionParameters
+                "O:${p.logicOperator}:${p.selectedRules.sorted()}:${rule.action}"
+            }
+            else -> "?:${c.javaClass.simpleName}:${rule.action}"
+        }
+    }
 }

package/android-aar/library/src/main/java/com/tempivo/sensor/beacon/SensorBleRuntime.kt

@@ -88,6 +88,26 @@ internal object SensorBleRuntime {
             next = next.copy(transmissionInterval = TransmissionInterval(sec))
         }
         session.connection.commands.setConfiguration(next) { }
+        if (cfg.temperatureAlerts.isEmpty()) return
+        val after = modernGetConfiguration(session.connection)
+        if (PartnerBleRules.configurationWriteAccepted(cfg.temperatureAlerts, rules, base.rules, after.rules)) {
+            return
+        }
+        val verify = decompile(after)
+        val slots =
+            (0 until 12).joinToString(",") { i ->
+                val r = after.rules.orEmpty().getOrNull(i)
+                when (r?.condition) {
+                    is pl.efento.mobile.bluetooth.model.sensor.LowThresholdCondition -> "LOW"
+                    is pl.efento.mobile.bluetooth.model.sensor.HighThresholdCondition -> "HIGH"
+                    is pl.efento.mobile.bluetooth.model.sensor.LogicOperatorCondition -> "OR"
+                    else -> "OFF"
+                }
+            }
+        throw TempivoSensorException(
+            TempivoSensorException.Code.UNKNOWN,
+            "Device alarm rules do not match the configuration that was written (readback ${verify.temperatureAlerts.size}/${cfg.temperatureAlerts.size} slots=$slots).",
+        )
     }
 
     suspend fun triggerTransmission(session: Session): TempivoSensorSession.TriggerResult {

package/android-aar/library/src/main/java/com/tempivo/sensor/beacon/TempivoSensorProfile.kt

@@ -68,6 +68,7 @@ object TempivoSensorProfile {
             val item = arr.optJSONObject(i) ?: throw invalid("temperatureAlerts[$i] must be an object.")
             alerts.add(parseAlert(item, i))
         }
+        assertAlertSlotBudget(alerts)
         val intervals = parseOptionalIntervals(body)
         return TempivoSensorConfiguration(
             alerts,
@@ -111,6 +112,33 @@ object TempivoSensorProfile {
         return root.toString()
     }
 
+
+    private fun assertAlertSlotBudget(alerts: List<TempivoTemperatureAlert>) {
+        val used = BooleanArray(12)
+        fun findPair(): Int? {
+            for (i in 0..10) if (!used[i] && !used[i + 1]) return i
+            return null
+        }
+        fun findFree(): Int? {
+            for (i in 0 until 12) if (!used[i]) return i
+            return null
+        }
+        for (alert in alerts) {
+            if (alert.type == "range") {
+                val pair = findPair() ?: throw invalid("Not enough free alarm rule slots for another range (need two consecutive slots).")
+                used[pair] = true
+                used[pair + 1] = true
+                if (alert.transmitOnReturn) {
+                    val logic = findFree() ?: throw invalid("Not enough free alarm rule slots for transmit-on-return (OR logic).")
+                    used[logic] = true
+                }
+            } else {
+                val slot = findFree() ?: throw invalid("Not enough free alarm rule slots.")
+                used[slot] = true
+            }
+        }
+    }
+
     private fun parseOptionalIntervals(body: JSONObject): Pair<Double?, Int?> {
         var measurement: Double? = null
         var transmission: Int? = null

package/android-aar/library/src/main/java/com/tempivo/sensor/beacon/TempivoSensorSession.kt

@@ -1,14 +1,17 @@
 package com.tempivo.sensor.beacon
 
 import android.content.Context
+import android.util.Base64
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 import kotlinx.coroutines.withContext
+import org.json.JSONObject
 
 /**
- * GATT session: connect, read/write alert rules and schedule, trigger uplink, read lab calibration date.
+ * GATT session: connect (SDK), alert rules via raw ProtoConfig 0x0C/0x0D, trigger/calibration via SDK.
  */
 class TempivoSensorSession(
     context: Context,
@@ -20,6 +23,11 @@ class TempivoSensorSession(
     private val application = context.applicationContext as android.app.Application
     private val mutex = Mutex()
     private var session: SensorBleRuntime.Session? = null
+    private var sdkConnected = false
+    private var lastSerial = ""
+    private var lastMac = ""
+    private var lastPin = ""
+    private var lastDeviceId = ""
 
     suspend fun connect(
         serial: String,
@@ -39,6 +47,7 @@ class TempivoSensorSession(
             mutex.withLock {
                 SensorBleRuntime.disconnect(session)
                 session = null
+                sdkConnected = false
                 session =
                     withContext(Dispatchers.Main) {
                         SensorBleRuntime.connect(
@@ -48,6 +57,11 @@ class TempivoSensorSession(
                             pin = trimmedPin,
                         )
                     }
+                sdkConnected = true
+                lastSerial = serial
+                lastMac = bluetoothMac
+                lastPin = trimmedPin
+                lastDeviceId = resolvedDeviceId
             }
         } catch (e: Throwable) {
             throw SensorBleRuntime.mapError(e).let {
@@ -70,35 +84,97 @@ class TempivoSensorSession(
 
     suspend fun disconnect() {
         mutex.withLock {
+            EfentoRawConfigTransfer.closeLink()
             SensorBleRuntime.disconnect(session)
             session = null
+            sdkConnected = false
+            lastSerial = ""
+            lastMac = ""
+            lastPin = ""
+            lastDeviceId = ""
         }
     }
 
     suspend fun getConfiguration(): TempivoSensorConfiguration {
-        return runGatt {
-            SensorBleRuntime.decompile(SensorBleRuntime.readConfiguration(requireSession()))
-        }
+        // Partner apps should use JS decompile of protoBase64; AAR returns the JSON shell fields only.
+        return TempivoSensorProfile.parseJson(getConfigurationJson())
     }
 
-    suspend fun getConfigurationJson(): String = TempivoSensorProfile.toJson(getConfiguration())
+    /** Always raw GATT ProtoConfig get (0x0C). Vendor SDK getConfiguration is not used for rules. */
+    suspend fun getConfigurationJson(): String {
+        val proto =
+            withRawConfigLink {
+                EfentoRawConfigTransfer.readProtoConfig(
+                    context = application,
+                    address = it,
+                    bluetoothMac = lastMac,
+                    pin = lastPin,
+                )
+            }
+        val b64 = Base64.encodeToString(proto, Base64.NO_WRAP)
+        return JSONObject()
+            .put("temperatureAlerts", org.json.JSONArray())
+            .put("schedule", JSONObject().put("always", true))
+            .put("protoBase64", b64)
+            .put("configSource", "rawGatt")
+            .toString()
+    }
 
     suspend fun setConfiguration(configuration: TempivoSensorConfiguration) {
-        runGatt {
-            SensorBleRuntime.writeConfiguration(requireSession(), configuration)
-        }
+        setConfigurationJson(TempivoSensorProfile.toJson(configuration))
     }
 
+    /** Partner JSON is not written here. Use [writeProtoConfigBase64] from JS after encode. */
     suspend fun setConfigurationJson(json: String) {
-        setConfiguration(TempivoSensorProfile.parseJson(json))
+        TempivoSensorProfile.parseJson(json)
+        throw TempivoSensorException(
+            TempivoSensorException.Code.UNSUPPORTED_COMMAND,
+            "Use writeProtoConfigBase64 after encoding partner config to ProtoConfig.",
+        )
+    }
+
+    /** Raw GATT set (0x0D): full ProtoConfig bytes as base64. */
+    suspend fun writeProtoConfigBase64(base64: String) {
+        val proto =
+            try {
+                Base64.decode(base64, Base64.DEFAULT)
+            } catch (e: IllegalArgumentException) {
+                throw TempivoSensorException(
+                    TempivoSensorException.Code.INVALID_CONFIG,
+                    "protoBase64 is missing or invalid.",
+                    e,
+                )
+            }
+        if (proto.isEmpty()) {
+            throw TempivoSensorException(
+                TempivoSensorException.Code.INVALID_CONFIG,
+                "protoBase64 is missing or invalid.",
+            )
+        }
+        withRawConfigLink {
+            EfentoRawConfigTransfer.writeProtoConfig(
+                context = application,
+                address = it,
+                bluetoothMac = lastMac,
+                pin = lastPin,
+                proto = proto,
+            )
+            ByteArray(0)
+        }
     }
 
     suspend fun triggerTransmission(): TriggerResult {
-        return runGatt { SensorBleRuntime.triggerTransmission(requireSession()) }
+        return runGatt {
+            ensureSdkConnected()
+            SensorBleRuntime.triggerTransmission(requireSession())
+        }
     }
 
     suspend fun getCalibration(): TempivoSensorCalibration {
-        return runGatt { SensorBleRuntime.readCalibration(requireSession()) }
+        return runGatt {
+            ensureSdkConnected()
+            SensorBleRuntime.readCalibration(requireSession())
+        }
     }
 
     fun connectBlocking(qr: TempivoSensorQr, deviceId: String, bluetoothMac: String) =
@@ -112,6 +188,8 @@ class TempivoSensorSession(
 
     fun setConfigurationJsonBlocking(json: String) = runBlocking { setConfigurationJson(json) }
 
+    fun writeProtoConfigBase64Blocking(base64: String) = runBlocking { writeProtoConfigBase64(base64) }
+
     fun triggerTransmissionBlocking(): TriggerResult = runBlocking { triggerTransmission() }
 
     fun getCalibrationBlocking(): TempivoSensorCalibration = runBlocking { getCalibration() }
@@ -120,6 +198,59 @@ class TempivoSensorSession(
         session
             ?: throw TempivoSensorException(TempivoSensorException.Code.NOT_CONNECTED, "Not connected.")
 
+    private fun requireRawAddress(): String {
+        if (lastMac.isEmpty() || lastPin.isEmpty()) {
+            throw TempivoSensorException(TempivoSensorException.Code.NOT_CONNECTED, "Not connected. Scan and connect first.")
+        }
+        // Prefer scan/SDK device id when it looks like a BLE address; else MAC.
+        val id = lastDeviceId.trim()
+        val idHex = id.replace(":", "").replace("-", "")
+        return if (idHex.length == 12 && idHex.all { it.isDigit() || it in 'a'..'f' || it in 'A'..'F' }) {
+            id
+        } else {
+            lastMac
+        }
+    }
+
+    private suspend fun <T> withRawConfigLink(body: suspend (String) -> T): T {
+        val address = requireRawAddress()
+        releaseSdkForRaw()
+        return try {
+            withContext(Dispatchers.IO) { body(address) }
+        } catch (e: Throwable) {
+            throw SensorBleRuntime.mapError(e)
+        }
+    }
+
+    private suspend fun releaseSdkForRaw() {
+        mutex.withLock {
+            val didDisconnect = sdkConnected
+            if (sdkConnected) {
+                SensorBleRuntime.disconnect(session)
+                session = null
+                sdkConnected = false
+            }
+            if (didDisconnect) delay(1_000)
+        }
+    }
+
+    private suspend fun ensureSdkConnected() {
+        if (sdkConnected && session != null) return
+        if (lastSerial.isEmpty() || lastMac.isEmpty() || lastPin.isEmpty() || lastDeviceId.isEmpty()) {
+            throw TempivoSensorException(TempivoSensorException.Code.NOT_CONNECTED, "Not connected.")
+        }
+        session =
+            withContext(Dispatchers.Main) {
+                SensorBleRuntime.connect(
+                    application = application,
+                    deviceId = lastDeviceId,
+                    bluetoothMac = lastMac,
+                    pin = lastPin,
+                )
+            }
+        sdkConnected = true
+    }
+
     private suspend fun <T> runGatt(block: suspend () -> T): T {
         try {
             return mutex.withLock { block() }