@tempivo/sensor-beacon 0.1.1 → 0.2.0

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

@@ -0,0 +1,168 @@
+package com.tempivo.sensor.beacon
+
+import android.app.Application
+import kotlinx.coroutines.delay
+import pl.efento.mobile.bluetooth.EfentoBluetooth
+import pl.efento.mobile.bluetooth.api.SensorConnection
+import pl.efento.mobile.bluetooth.api.SensorLegacyConnection
+import pl.efento.mobile.bluetooth.exception.InvalidResetCodeException
+import pl.efento.mobile.bluetooth.exception.UnsupportedCommandException
+import pl.efento.mobile.bluetooth.model.BluetoothMacAddress
+import pl.efento.mobile.bluetooth.model.sensor.Rule
+import pl.efento.mobile.bluetooth.model.sensor.RuleCalendar
+import pl.efento.mobile.bluetooth.model.sensor.SensorConfiguration
+
+/**
+ * Internal adapter to the sensor BLE runtime. Keep vendor types inside this file.
+ */
+internal object SensorBleRuntime {
+    private val initMonitor = Any()
+    @Volatile private var initialized = false
+
+    fun initialize(application: Application) {
+        if (initialized) return
+        synchronized(initMonitor) {
+            if (initialized) return
+            EfentoBluetooth.init(application)
+            initialized = true
+        }
+    }
+
+    fun mapError(e: Throwable): TempivoSensorException {
+        if (e is TempivoSensorException) return e
+        val className = e.javaClass.name
+        return when {
+            e is InvalidResetCodeException || className.contains("InvalidResetCode") ->
+                TempivoSensorException(TempivoSensorException.Code.INVALID_PIN, "Invalid PIN.", e)
+            e is UnsupportedCommandException || className.contains("UnsupportedCommand") ->
+                TempivoSensorException(TempivoSensorException.Code.UNSUPPORTED_COMMAND, "Unsupported command.", e)
+            className.contains("NotConnected") ->
+                TempivoSensorException(TempivoSensorException.Code.NOT_CONNECTED, "Not connected.", e)
+            else ->
+                TempivoSensorException(TempivoSensorException.Code.UNKNOWN, "Sensor request failed.", e)
+        }
+    }
+
+    suspend fun connect(
+        application: Application,
+        serial: String,
+        bluetoothMac: String,
+        pin: Int,
+        legacy: Boolean,
+    ): Session {
+        initialize(application)
+        val mac = BluetoothMacAddress(bluetoothMac)
+        // PIN stays on the connection: set, trigger, calibration writes, and many other commands check it.
+        return if (legacy) {
+            val c =
+                EfentoBluetooth.sensorLegacyConnection(
+                    deviceID = serial,
+                    bluetoothMacAddress = mac,
+                    resetCode = pin,
+                    encryptionKey = "",
+                )
+            c.connect()
+            if (pin >= 0) c.resetCode = pin
+            Session.Legacy(c)
+        } else {
+            val c =
+                EfentoBluetooth.sensorConnection(
+                    deviceID = serial,
+                    bluetoothMacAddress = mac,
+                    resetCode = pin,
+                    encryptionKey = "",
+                )
+            c.connect()
+            if (pin >= 0) c.resetCode = pin
+            Session.Modern(c)
+        }
+    }
+
+    suspend fun disconnect(session: Session?) {
+        when (session) {
+            is Session.Modern -> runCatching { session.connection.disconnect() }
+            is Session.Legacy -> runCatching { session.connection.disconnect() }
+            null -> Unit
+        }
+    }
+
+    suspend fun readConfiguration(session: Session): SensorConfiguration {
+        return when (session) {
+            is Session.Modern -> modernGetConfiguration(session.connection)
+            is Session.Legacy ->
+                throw TempivoSensorException(
+                    TempivoSensorException.Code.UNSUPPORTED_COMMAND,
+                    "Configuration rules require a current-generation sensor session.",
+                )
+        }
+    }
+
+    suspend fun writeRules(session: Session, rules: List<Rule>, calendars: List<RuleCalendar>) {
+        when (session) {
+            is Session.Modern -> {
+                val base = modernGetConfiguration(session.connection)
+                val next = base.copy(rules = rules.take(12), ruleCalendars = calendars.take(6))
+                session.connection.commands.setConfiguration(next) { }
+            }
+            is Session.Legacy ->
+                throw TempivoSensorException(
+                    TempivoSensorException.Code.UNSUPPORTED_COMMAND,
+                    "Configuration rules require a current-generation sensor session.",
+                )
+        }
+    }
+
+    suspend fun triggerTransmission(session: Session): TempivoSensorSession.TriggerResult {
+        return when (session) {
+            is Session.Modern -> {
+                session.connection.commands.triggerCommunicationWithServer { }
+                TempivoSensorSession.TriggerResult(ok = true, supported = true)
+            }
+            is Session.Legacy -> {
+                try {
+                    session.connection.cellularCommands.triggerCommunicationWithServer { }
+                    TempivoSensorSession.TriggerResult(ok = true, supported = true)
+                } catch (e: UnsupportedCommandException) {
+                    TempivoSensorSession.TriggerResult(ok = false, supported = false)
+                }
+            }
+        }
+    }
+
+    suspend fun readCalibration(session: Session): TempivoSensorCalibration {
+        return when (session) {
+            is Session.Modern -> {
+                val ext = session.connection.commands.getExtendedConfiguration { }
+                TempivoSensorCalibrationDecoder.decode(ext.laboratoryCalibrationTimestamp)
+            }
+            is Session.Legacy -> TempivoSensorCalibration(null, null)
+        }
+    }
+
+    fun compileRules(cfg: TempivoSensorConfiguration): Pair<List<Rule>, List<RuleCalendar>> =
+        PartnerBleRules.compile(cfg)
+
+    fun decompile(cfg: SensorConfiguration): TempivoSensorConfiguration =
+        PartnerBleRules.decompile(cfg)
+
+    private suspend fun modernGetConfiguration(modern: SensorConnection): SensorConfiguration {
+        var last: Exception? = null
+        repeat(3) { attempt ->
+            try {
+                if (attempt > 0) {
+                    runCatching { modern.commands.getDeviceInfo { } }
+                }
+                return modern.commands.getConfiguration { }
+            } catch (e: Exception) {
+                last = e
+                if (attempt < 2) delay(400)
+            }
+        }
+        throw last ?: TempivoSensorException(TempivoSensorException.Code.UNKNOWN, "Could not read configuration.")
+    }
+
+    sealed class Session {
+        class Modern(val connection: SensorConnection) : Session()
+        class Legacy(val connection: SensorLegacyConnection) : Session()
+    }
+}

package/android/library/src/main/java/com/tempivo/sensor/beacon/TempivoSensorBeaconDecoder.kt

@@ -155,8 +155,7 @@ object TempivoSensorBeaconDecoder {
         var measurementCounter: Long? = null
         var readingTimestampUnix: Long? = null
         var readingTimestampIso: String? = null
-        var periodBaseSeconds: Int? = null
-        var periodFactor: Int? = null
+        var measurementIntervalSeconds: Int? = null
         val readings = mutableListOf<TempivoSensorBeaconReading>()
 
         if (adv03 != null && adv03.isNotEmpty()) {
@@ -170,8 +169,7 @@ object TempivoSensorBeaconDecoder {
                     measurementCounter = parsed.measurementCounter
                     readingTimestampUnix = parsed.readingTimestampUnix
                     readingTimestampIso = parsed.readingTimestampIso
-                    periodBaseSeconds = parsed.periodBaseSeconds
-                    periodFactor = parsed.periodFactor
+                    measurementIntervalSeconds = parsed.measurementIntervalSeconds
                 }
                 0x02 -> {
                     val fw5 = fw5Summary(adv03)
@@ -233,26 +231,13 @@ object TempivoSensorBeaconDecoder {
             measurementCounter = measurementCounter,
             readingTimestampUnix = readingTimestampUnix,
             readingTimestampIso = readingTimestampIso,
-            periodBaseSeconds = periodBaseSeconds,
-            periodFactor = periodFactor,
+            measurementIntervalSeconds = measurementIntervalSeconds,
             readings = readings,
             readingsCount = readingsCount,
             summary = sumOut.ifEmpty { null },
         )
     }
 
-    /** Firmware 7+ → modern (`false`); older families → legacy (`true`). */
-    fun legacyHintFromFirmware(firmware: String?): Boolean? {
-        if (firmware.isNullOrBlank()) return null
-        val t = firmware.trim()
-        if (t.startsWith("FW 5", ignoreCase = true)) return true
-        val m = Regex("""^(\d+)\.\d+""").find(t) ?: return null
-        val major = m.groupValues[1].toIntOrNull() ?: return null
-        if (major >= 7) return false
-        if (major >= 1) return true
-        return null
-    }
-
     private data class Adv03Parsed(
         val firmware: String?,
         val batteryOk: Boolean?,
@@ -261,8 +246,7 @@ object TempivoSensorBeaconDecoder {
         val measurementCounter: Long?,
         val readingTimestampUnix: Long?,
         val readingTimestampIso: String?,
-        val periodBaseSeconds: Int?,
-        val periodFactor: Int?,
+        val measurementIntervalSeconds: Int?,
     )
 
     private fun fw5Summary(frame: ByteArray): String? {
@@ -360,7 +344,7 @@ object TempivoSensorBeaconDecoder {
 
     private fun parseFw6Adv03(adv03: ByteArray): Adv03Parsed {
         if (adv03.size < ADV_FRAME_03_LEN) {
-            return Adv03Parsed(null, null, null, null, null, null, null, null, null)
+            return Adv03Parsed(null, null, null, null, null, null, null, null)
         }
         val fwRaw = ((adv03[7].toInt() and 0xFF) shl 8) or (adv03[8].toInt() and 0xFF)
         val major = (fwRaw shr 11) and 0x1F
@@ -399,8 +383,7 @@ object TempivoSensorBeaconDecoder {
             measurementCounter = measurementCounter,
             readingTimestampUnix = readingTimestampUnix,
             readingTimestampIso = readingTimestampIso,
-            periodBaseSeconds = pbase,
-            periodFactor = pfact,
+            measurementIntervalSeconds = pbase * pfact,
         )
     }
 }

package/android/library/src/main/java/com/tempivo/sensor/beacon/TempivoSensorBeaconScanner.kt

@@ -118,7 +118,6 @@ class TempivoSensorBeaconScanner(
         val summary =
             telemetry?.summary?.takeIf { it.isNotEmpty() }
                 ?: serial
-        val legacyHint = TempivoSensorBeaconDecoder.legacyHintFromFirmware(telemetry?.firmware)
         return TempivoSensorBeaconDevice(
             deviceId = addr,
             bluetoothMacAddress = macColons,
@@ -126,7 +125,6 @@ class TempivoSensorBeaconScanner(
             rssi = result.rssi,
             telemetry = telemetry,
             summary = summary,
-            legacyHint = legacyHint,
         )
     }
 

package/android/library/src/main/java/com/tempivo/sensor/beacon/TempivoSensorBeaconTypes.kt

@@ -20,8 +20,8 @@ data class TempivoSensorBeaconTelemetry(
     val measurementCounter: Long? = null,
     val readingTimestampUnix: Long? = null,
     val readingTimestampIso: String? = null,
-    val periodBaseSeconds: Int? = null,
-    val periodFactor: Int? = null,
+    /** Sample interval from the advertisement, in seconds. */
+    val measurementIntervalSeconds: Int? = null,
     val readings: List<TempivoSensorBeaconReading> = emptyList(),
     val readingsCount: Int = 0,
     val summary: String? = null,
@@ -37,6 +37,4 @@ data class TempivoSensorBeaconDevice(
     val rssi: Int,
     val telemetry: TempivoSensorBeaconTelemetry?,
     val summary: String?,
-    /** `true` for older firmware families; `false` for current; `null` if unknown. */
-    val legacyHint: Boolean?,
 )

package/android/library/src/main/java/com/tempivo/sensor/beacon/TempivoSensorCalibration.kt

@@ -0,0 +1,36 @@
+package com.tempivo.sensor.beacon
+
+import java.util.Calendar
+import java.util.Locale
+import java.util.TimeZone
+
+data class TempivoSensorCalibration(
+    val laboratoryCalibrationDate: String?,
+    val laboratoryCalibrationTimestamp: Long?,
+)
+
+object TempivoSensorCalibrationDecoder {
+    private const val SECONDS_PER_DAY = 86_400L
+
+    fun decode(raw: Long?): TempivoSensorCalibration {
+        if (raw == null || raw <= 0L) {
+            return TempivoSensorCalibration(null, null)
+        }
+        val date =
+            if (raw < 100_000L) {
+                isoDateUtc(raw * SECONDS_PER_DAY)
+            } else {
+                isoDateUtc(raw)
+            }
+        return TempivoSensorCalibration(date, raw)
+    }
+
+    private fun isoDateUtc(unixSeconds: Long): String {
+        val cal = Calendar.getInstance(TimeZone.getTimeZone("UTC"), Locale.US)
+        cal.timeInMillis = unixSeconds * 1000L
+        val y = cal.get(Calendar.YEAR)
+        val m = cal.get(Calendar.MONTH) + 1
+        val d = cal.get(Calendar.DAY_OF_MONTH)
+        return String.format(Locale.US, "%04d-%02d-%02d", y, m, d)
+    }
+}

package/android/library/src/main/java/com/tempivo/sensor/beacon/TempivoSensorError.kt

@@ -0,0 +1,18 @@
+package com.tempivo.sensor.beacon
+
+class TempivoSensorException(
+    val code: Code,
+    message: String,
+    cause: Throwable? = null,
+) : Exception(message, cause) {
+    enum class Code {
+        INVALID_PIN,
+        INVALID_QR,
+        INVALID_CONFIG,
+        NOT_CONNECTED,
+        UNSUPPORTED_COMMAND,
+        RUNTIME_UNAVAILABLE,
+        CONNECT_FAILED,
+        UNKNOWN,
+    }
+}

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

@@ -0,0 +1,171 @@
+package com.tempivo.sensor.beacon
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+data class TempivoTemperatureAlert(
+    val type: String,
+    val channel: String,
+    val lowC: Double? = null,
+    val highC: Double? = null,
+    val minC: Double? = null,
+    val maxC: Double? = null,
+    val hysteresisC: Double? = null,
+    val transmitOnBreach: Boolean = true,
+    val transmitOnReturn: Boolean = true,
+)
+
+data class TempivoSchedule(
+    val always: Boolean,
+    val weekdays: List<Int> = emptyList(),
+    val from: String? = null,
+    val to: String? = null,
+    val utcOffsetMinutes: Int = 0,
+)
+
+data class TempivoSensorConfiguration(
+    val temperatureAlerts: List<TempivoTemperatureAlert>,
+    val schedule: TempivoSchedule,
+)
+
+object TempivoSensorProfile {
+    private val timeRe = Regex("^([01]\\d|2[0-3]):([0-5]\\d)$")
+
+    fun parseJson(json: String): TempivoSensorConfiguration {
+        val root =
+            try {
+                JSONObject(json)
+            } catch (_: Exception) {
+                throw TempivoSensorException(TempivoSensorException.Code.INVALID_CONFIG, "Configuration is not valid JSON.")
+            }
+        return parse(root)
+    }
+
+    fun parse(root: JSONObject): TempivoSensorConfiguration {
+        if (root.has("profiles") && root.optJSONArray("profiles") != null) {
+            throw invalid("Pass one profile from GET /devices/config-profiles/{slug}, not the list.")
+        }
+        val body =
+            root.optJSONObject("profile")?.takeIf {
+                it.has("temperatureAlerts") || it.has("schedule") || it.has("slug")
+            } ?: root
+        if (!body.has("temperatureAlerts") && body.has("alarmRules")) {
+            throw invalid("Use a config profile with temperatureAlerts (GET /devices/config-profiles/{slug}), not alarmRules.")
+        }
+        val alerts = mutableListOf<TempivoTemperatureAlert>()
+        val arr = body.optJSONArray("temperatureAlerts") ?: JSONArray()
+        for (i in 0 until arr.length()) {
+            val item = arr.optJSONObject(i) ?: throw invalid("temperatureAlerts[$i] must be an object.")
+            alerts.add(parseAlert(item, i))
+        }
+        return TempivoSensorConfiguration(alerts, parseSchedule(body.optJSONObject("schedule")))
+    }
+
+    fun toJson(cfg: TempivoSensorConfiguration): String {
+        val root = JSONObject()
+        val arr = JSONArray()
+        for (a in cfg.temperatureAlerts) {
+            val o = JSONObject()
+            o.put("type", a.type)
+            o.put("channel", a.channel)
+            if (a.lowC != null) o.put("lowC", a.lowC)
+            if (a.highC != null) o.put("highC", a.highC)
+            if (a.minC != null) o.put("minC", a.minC)
+            if (a.maxC != null) o.put("maxC", a.maxC)
+            if (a.hysteresisC != null) o.put("hysteresisC", a.hysteresisC)
+            o.put("transmitOnBreach", a.transmitOnBreach)
+            if (a.type == "range") o.put("transmitOnReturn", a.transmitOnReturn)
+            arr.put(o)
+        }
+        root.put("temperatureAlerts", arr)
+        val s = JSONObject()
+        if (cfg.schedule.always) {
+            s.put("always", true)
+        } else {
+            val days = JSONArray()
+            cfg.schedule.weekdays.forEach { days.put(it) }
+            s.put("weekdays", days)
+            s.put("from", cfg.schedule.from)
+            s.put("to", cfg.schedule.to)
+            s.put("utcOffsetMinutes", cfg.schedule.utcOffsetMinutes)
+        }
+        root.put("schedule", s)
+        return root.toString()
+    }
+
+    private fun parseAlert(item: JSONObject, index: Int): TempivoTemperatureAlert {
+        val channel = item.optString("channel")
+        if (channel != "ambient" && channel != "probe") {
+            throw invalid("temperatureAlerts[$index].channel must be ambient or probe.")
+        }
+        val hysteresis = if (item.has("hysteresisC") && !item.isNull("hysteresisC")) item.optDouble("hysteresisC") else 1.0
+        val transmit = if (item.has("transmitOnBreach")) item.optBoolean("transmitOnBreach", true) else true
+        val transmitOnReturn = if (item.has("transmitOnReturn")) item.optBoolean("transmitOnReturn", true) else true
+        return when (item.optString("type")) {
+            "range" -> {
+                if (!item.has("lowC") || !item.has("highC")) {
+                    throw invalid("temperatureAlerts[$index] needs lowC and highC.")
+                }
+                val low = item.optDouble("lowC")
+                val high = item.optDouble("highC")
+                if (high <= low) throw invalid("temperatureAlerts[$index]: highC must be greater than lowC.")
+                TempivoTemperatureAlert(
+                    "range",
+                    channel,
+                    lowC = low,
+                    highC = high,
+                    hysteresisC = hysteresis,
+                    transmitOnBreach = transmit,
+                    transmitOnReturn = transmitOnReturn,
+                )
+            }
+            "min" -> {
+                if (!item.has("minC")) throw invalid("temperatureAlerts[$index] needs minC.")
+                TempivoTemperatureAlert("min", channel, minC = item.optDouble("minC"), hysteresisC = hysteresis, transmitOnBreach = transmit)
+            }
+            "max" -> {
+                if (!item.has("maxC")) throw invalid("temperatureAlerts[$index] needs maxC.")
+                TempivoTemperatureAlert("max", channel, maxC = item.optDouble("maxC"), hysteresisC = hysteresis, transmitOnBreach = transmit)
+            }
+            else -> throw invalid("temperatureAlerts[$index].type must be range, min, or max.")
+        }
+    }
+
+    private fun parseSchedule(raw: JSONObject?): TempivoSchedule {
+        if (raw == null || raw.optBoolean("always", false)) return TempivoSchedule(always = true)
+        val weekdays = raw.optJSONArray("weekdays") ?: throw invalid("schedule.weekdays is required.")
+        val days = mutableListOf<Int>()
+        for (i in 0 until weekdays.length()) {
+            val n = weekdays.optInt(i, -1)
+            if (n !in 0..6) throw invalid("schedule.weekdays must be 0 to 6.")
+            days.add(n)
+        }
+        if (days.isEmpty()) throw invalid("schedule.weekdays is required.")
+        val from = raw.optString("from")
+        val to = raw.optString("to")
+        if (!timeRe.matches(from) || !timeRe.matches(to)) {
+            throw invalid("schedule.from and schedule.to must be HH:MM.")
+        }
+        if (!raw.has("utcOffsetMinutes")) throw invalid("schedule.utcOffsetMinutes is required.")
+        return TempivoSchedule(
+            always = false,
+            weekdays = days,
+            from = from,
+            to = to,
+            utcOffsetMinutes = raw.optInt("utcOffsetMinutes"),
+        )
+    }
+
+    fun minutesFromHhmm(value: String): Int {
+        val m = timeRe.matchEntire(value) ?: throw invalid("Invalid time $value.")
+        return m.groupValues[1].toInt() * 60 + m.groupValues[2].toInt()
+    }
+
+    fun hhmmFromMinutes(minutes: Int): String {
+        val clamped = minutes.coerceIn(0, 1439)
+        return String.format(java.util.Locale.US, "%02d:%02d", clamped / 60, clamped % 60)
+    }
+
+    private fun invalid(message: String): TempivoSensorException =
+        TempivoSensorException(TempivoSensorException.Code.INVALID_CONFIG, message)
+}

package/android/library/src/main/java/com/tempivo/sensor/beacon/TempivoSensorQr.kt

@@ -0,0 +1,82 @@
+package com.tempivo.sensor.beacon
+
+import org.json.JSONObject
+import java.util.Locale
+
+data class TempivoSensorQr(
+    val serial: String,
+    val pin: String,
+    val model: String?,
+    val sessionType: TempivoSensorSession.SessionType,
+    val bluetoothMac: String,
+)
+
+object TempivoSensorQrParser {
+    const val DEFAULT_MODEL = "HC7"
+
+    fun normalizeSerial(value: String): String =
+        value.trim().uppercase(Locale.US).replace(Regex("[^A-Z0-9]"), "")
+
+    fun bluetoothMacFromSerial(serial: String): String {
+        val key = normalizeSerial(serial)
+        if (key.length != 12 || !key.matches(Regex("[0-9A-F]{12}"))) {
+            throw TempivoSensorException(TempivoSensorException.Code.INVALID_QR, "Serial must be 12 hex characters.")
+        }
+        return buildString(17) {
+            for (i in 0 until 12 step 2) {
+                if (isNotEmpty()) append(':')
+                append(key, i, i + 2)
+            }
+        }
+    }
+
+    fun sessionTypeFromModel(model: String?): TempivoSensorSession.SessionType {
+        if (model.isNullOrBlank()) return TempivoSensorSession.SessionType.MODERN
+        val m = model.trim().uppercase(Locale.US).replace("-", "")
+        return if (m == "HC5" || m.startsWith("6")) {
+            TempivoSensorSession.SessionType.LEGACY
+        } else {
+            TempivoSensorSession.SessionType.MODERN
+        }
+    }
+
+    fun parse(json: String): TempivoSensorQr {
+        val rec =
+            try {
+                JSONObject(json.trim())
+            } catch (_: Exception) {
+                throw TempivoSensorException(TempivoSensorException.Code.INVALID_QR, "QR is not valid JSON.")
+            }
+        val snRaw =
+            when {
+                rec.has("sn") && !rec.isNull("sn") -> rec.opt("sn")?.toString().orEmpty()
+                else -> ""
+            }
+        val serial = normalizeSerial(snRaw)
+        val pin = pinFrom(rec)
+        if (serial.length < 8) {
+            throw TempivoSensorException(TempivoSensorException.Code.INVALID_QR, "QR is missing serial (sn).")
+        }
+        if (pin.isEmpty()) {
+            throw TempivoSensorException(TempivoSensorException.Code.INVALID_QR, "QR is missing PIN.")
+        }
+        val model = rec.optString("model").trim().ifEmpty { DEFAULT_MODEL }
+        val hex = if (serial.length == 12) serial else serial.takeLast(12)
+        return TempivoSensorQr(
+            serial = serial,
+            pin = pin,
+            model = model,
+            sessionType = sessionTypeFromModel(model),
+            bluetoothMac = bluetoothMacFromSerial(hex),
+        )
+    }
+
+    private fun pinFrom(rec: JSONObject): String {
+        val raw = if (rec.has("pin") && !rec.isNull("pin")) rec.opt("pin") else rec.opt("resetCode")
+        return when (raw) {
+            null, JSONObject.NULL -> ""
+            is Number -> raw.toLong().toString()
+            else -> raw.toString().trim()
+        }
+    }
+}