@tempivo/sensor-beacon 0.3.3 → 0.4.7

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+Partner-facing changes to `@tempivo/sensor-beacon`. Logging starts **2026-09-01**; earlier npm versions are not listed here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.4.7] - 2026-09-01
+
+### Added
+
+- Shared connect helpers: `tryParseSensorQrJson`, `parseSensorQrForConnect`, `buildSensorQrConnectJson`, `draftSensorQrConnectJsonFromScanDevice`, `mergeScanTargetIntoSensorQr`, `sensorQrSerialMatchesSelected`, `resolveSensorBleConnectCredentialsFromPin`, `formatSensorReadingLine`, `normalizeSensorStickerModel`.
+- `parseSensorConfigurationFromDevice` / `parseSensorConfigurationFromDeviceJson` for relaxed interval parsing on GATT readback.
+- README: config examples with `measurementIntervalMinutes` and `transmissionIntervalSeconds`, connect tips, alert slot budget, API profile helper.
+
+### Changed
+
+- `triggerTransmission()` returns `{ ok }` only (`supported` removed).
+- Native scan `readings[].typeHex` is a human label (e.g. `temperature`); `text` is value + unit (e.g. `23.5 °C`).
+- Default product model is **HC7** when sticker firmware is missing or `0.0.0`.
+- iOS `getCalibration()` always includes `laboratoryCalibrationDate` and `laboratoryCalibrationTimestamp` (null when unset).
+
+### Fixed
+
+- iOS scan telemetry: live temperatures in `telemetry.readings` during active scan.
+- BLE connect: use scan `deviceId` + MAC and PIN-derived encryption key (not numeric reset code alone).
+- `getConfiguration()` no longer rejects devices with sub-60-minute measurement intervals already stored on hardware.
+- Android `triggerTransmission()`: unsupported firmware command returns `{ ok: false }` instead of throwing.

package/README.md

@@ -84,15 +84,128 @@ sub.remove();
 
 `startScan` and `connect` request Bluetooth permission. Sticker PIN is required on `connect`. Wrong PIN is `invalidPin`.
 
+**Connect tips:** stop scan before GATT connect. Pass the scan row’s `deviceId` and MAC when they differ from the sticker serial (`parseSensorQrForConnect`). 5–6 digit PINs map to an encryption key internally; numeric `resetCode` alone is not enough on all devices.
+
 If a bundler misses native BLE, import `@tempivo/sensor-beacon/react-native`.
 
+The Expo config plugin sets **minSdk 26**, Android BLE permissions, and **`NSBluetoothAlwaysUsageDescription`**. Add **`NSCameraUsageDescription`** yourself if you scan sticker QR with the device camera.
+
+**Native BLE API**
+
+| Export | Purpose |
+|--------|---------|
+| `isNativeSensorBeaconAvailable()` | `true` when the Expo dev build / RN app includes the native module (false in Expo Go and most web builds). |
+| `requestPermissions()` | Request Bluetooth permission explicitly; `startScan` and `connect` call this automatically. |
+| `startScan` / `stopScan` / `isScanning` | Active BLE scan for manufacturer `0x026C`. |
+| `addDeviceFoundListener` | Callback per discovered device (includes `telemetry` when decoded). |
+| `connect` / `disconnect` | GATT session with parsed QR (`TempivoSensorQr`). |
+| `getConfiguration` / `setConfigurationJson` | Read / write alert rules, schedule, optional intervals. |
+| `triggerTransmission` | Ask firmware to uplink now; returns `{ ok }`. |
+| `getCalibration` | Laboratory calibration date from extended config. |
+
+### QR + connect helpers
+
+Shared with the Tempivo app (same sticker JSON, PIN → encryption key, serial match checks):
+
+```ts
+import {
+  parseSensorQrForConnect,
+  draftSensorQrConnectJsonFromScanDevice,
+  buildSensorQrConnectJson,
+  sensorQrSerialMatchesSelected,
+  formatSensorReadingLine,
+  resolveSensorBleConnectCredentialsFromPin,
+} from '@tempivo/sensor-beacon/react-native';
+
+// After scan: draft QR from a row (model from sticker or FW hint)
+const draft = draftSensorQrConnectJsonFromScanDevice(device);
+
+// Connect: parse sticker + merge selected row deviceId / MAC
+const qr = parseSensorQrForConnect(stickerJson, selectedDevice);
+await connect(qr);
+
+// Scan list: same reading line as in-app
+formatSensorReadingLine({ typeHex: 'temperature', text: '23.5 °C' });
+```
+
+Use `tryParseSensorQrJson` for camera QR (invalid JSON → null). Use `parseSensorQrJson` when the payload must be valid HC7 sticker JSON.
+
 ## Config JSON
 
 Same as Cellular API config profiles (`temperatureAlerts` + `schedule`). You can build it yourself. Profiles are only for REST reuse.
 
+**Alerts only** (intervals unchanged on the device):
+
+```json
+{
+  "schedule": { "always": true },
+  "temperatureAlerts": [
+    {
+      "type": "range",
+      "channel": "probe",
+      "lowC": -30,
+      "highC": -10,
+      "hysteresisC": 0.5,
+      "transmitOnBreach": true,
+      "transmitOnReturn": true
+    }
+  ]
+}
+```
+
+**Min and max alerts** (single threshold; no `transmitOnReturn`):
+
+```json
+{
+  "schedule": { "always": true },
+  "temperatureAlerts": [
+    {
+      "type": "min",
+      "channel": "probe",
+      "minC": -25,
+      "hysteresisC": 0.5,
+      "transmitOnBreach": true
+    },
+    {
+      "type": "max",
+      "channel": "ambient",
+      "maxC": 8,
+      "hysteresisC": 1,
+      "transmitOnBreach": true
+    }
+  ]
+}
+```
+
+**Weekday schedule** (Mon–Fri 08:00–18:00, UTC+1):
+
+```json
+{
+  "schedule": {
+    "weekdays": [0, 1, 2, 3, 4],
+    "from": "08:00",
+    "to": "18:00",
+    "utcOffsetMinutes": 60
+  },
+  "temperatureAlerts": [
+    {
+      "type": "range",
+      "channel": "probe",
+      "lowC": 2,
+      "highC": 8,
+      "hysteresisC": 0.5
+    }
+  ]
+}
+```
+
+**Alerts + sample and uplink intervals** (each optional field is written when present; omit to leave that interval unchanged):
+
 ```json
 {
   "schedule": { "always": true },
+  "measurementIntervalMinutes": 60,
+  "transmissionIntervalSeconds": 3600,
   "temperatureAlerts": [
     {
       "type": "range",
@@ -107,6 +220,25 @@ Same as Cellular API config profiles (`temperatureAlerts` + `schedule`). You can
 }
 ```
 
+```ts
+await setConfigurationJson({
+  schedule: { always: true },
+  measurementIntervalMinutes: 60,
+  transmissionIntervalSeconds: 3600,
+  temperatureAlerts: [
+    {
+      type: 'range',
+      channel: 'probe',
+      lowC: -30,
+      highC: -10,
+      hysteresisC: 0.5,
+    },
+  ],
+});
+const applied = await getConfiguration();
+await triggerTransmission();
+```
+
 | Field | Meaning |
 |------|---------|
 | `temperatureAlerts` | Alert list. Empty array is valid. |
@@ -114,7 +246,18 @@ Same as Cellular API config profiles (`temperatureAlerts` + `schedule`). You can
 
 Ignored over BLE: `slug`, `name`. Do not pass `alarmRules`.
 
-Optional intervals (same limits as Cellular API): `measurementIntervalMinutes` (60–600), `transmissionIntervalSeconds` (3600–604800). When both are set, uplink must be at most 60× the measurement interval. Omitted fields leave the device’s current intervals unchanged.
+**Optional intervals** (same limits as Cellular API):
+
+| Field | Write (`setConfigurationJson`) | Read (`getConfiguration`) |
+|------|--------------------------------|---------------------------|
+| `measurementIntervalMinutes` | 60–600. Omitted: leave device value. | Returns current device value (may be below 60 if set outside the SDK). |
+| `transmissionIntervalSeconds` | 3600–604800 (1 h–7 d). Omitted: leave device value. | Returns current device value. |
+
+When **both** are set on write, uplink must be at most **60×** the measurement interval. Example: 60 min sampling → max `3600` s uplink; 120 min → max `7200` s.
+
+Use `parseSensorConfigurationJson` to validate before write. Use `parseSensorConfigurationFromDevice` / `parseSensorConfigurationFromDeviceJson` when parsing a **readback** from the device (relaxed interval rules). For `GET /devices/config-profiles/{slug}`, use `configurationFromApiProfile(response.profile)` or pass the `{ profile }` envelope directly to `setConfigurationJson`.
+
+**Alert slot budget:** the device has **12** rule slots. A `range` with default `transmitOnReturn: true` uses **two** slots (breach + return). Up to **4** such ranges, or more min/max alerts if you disable `transmitOnReturn` on ranges.
 
 **Each `temperatureAlerts[]` item**
 
@@ -151,9 +294,10 @@ Sticker QR is JSON. Parse with `parseSensorQrJson`.
 |------|------|---------|
 | `serial` | string | Device serial, 12 hex chars, no colons. From QR `sn`. |
 | `pin` | string | Sticker PIN. Required on `connect`. Also accepted as QR `resetCode`. |
-| `model` | string | Optional. Firmware from the last scan wins when present. |
-| `sessionType` | `modern` \| `legacy` | GATT path. Firmware 7+ is `modern`. Firmware 6.x is `legacy`. |
-| `bluetoothMac` | string | BLE MAC with colons, derived from `serial`. |
+| `model` | string | Optional. Defaults to **HC7**. **HC5** is rejected. |
+| `sessionType` | `modern` | Always modern GATT (HC7 / firmware 7+). |
+| `bluetoothMac` | string | BLE MAC with colons, derived from `serial` or scan row. |
+| `deviceId` | string | Optional. Platform BLE id from scan. Pass when connecting to a selected scan row. |
 
 ## Scan result
 
@@ -172,7 +316,7 @@ Filter manufacturer data on company id **0x026C**. Active scanning is on so scan
 
 | Field | Meaning |
 |------|---------|
-| `firmware` | `major.minor.patch`, e.g. `7.3.4`. Firmware 7+ is modern GATT. |
+| `firmware` | `major.minor.patch`, e.g. `7.3.4`. Partner GATT requires firmware 7+. |
 | `batteryOk` | Battery status flag. |
 | `encryptionEnabled` | Advertisement payload encryption flag. |
 | `cellularStatus` | `ble_only`, `cell_ok`, `no_server`, or `net_issue`. |
@@ -188,11 +332,11 @@ Filter manufacturer data on company id **0x026C**. Active scanning is on so scan
 
 | Field | Meaning |
 |------|---------|
-| `typeHex` | Slot type, e.g. `0x01` temperature, `0x02` humidity. |
+| `typeHex` | Measurement label, e.g. `temperature`, `humidity` (not a raw hex code on native scan). |
 | `raw24` | Undecoded 24-bit payload. |
-| `text` | Display value with unit, e.g. `21.8 °C`. |
+| `text` | Display value with unit, e.g. `21.8 °C`. Use `formatSensorReadingLine(reading)` for `temperature: 21.8 °C`. |
 
-`triggerTransmission()` returns `{ ok, supported }`. `supported: false` is not an error.
+`triggerTransmission()` returns `{ ok }`. `ok: false` means the firmware rejected the command; it is not thrown as an error.
 
 `getCalibration()` returns `{ laboratoryCalibrationDate, laboratoryCalibrationTimestamp }`. Date is `YYYY-MM-DD`, or null if unset.
 
@@ -206,11 +350,13 @@ import {
   decodeSensorBeaconPayload,
   parseSensorQrJson,
   parseSensorConfigurationJson,
+  configurationFromApiProfile,
 } from '@tempivo/sensor-beacon';
 
 const qr = parseSensorQrJson('{"sn":"282C024F0012","pin":"111111"}');
 const reading = decodeSensorBeaconPayload(normalizeManufacturerBytes(advertisementBytes));
 const cfg = parseSensorConfigurationJson(/* config JSON above */);
+const fromApi = configurationFromApiProfile(apiProfile); // GET …/config-profiles/{slug}
 ```
 
 Invalid QR or config throws `TempivoSensorError` (`invalidQr`, `invalidPin`, `invalidConfig`).
@@ -224,7 +370,7 @@ AAR after `npm run build:android` (from `packages/tempivo-sensor-beacon`):
 | `android/libs/tempivo-sensor-beacon.aar` | Expo / React Native autolinking (`android/build.gradle`) |
 | `dist/tempivo-sensor-beacon.aar` | Same file; handy for plain Android `files(...)` deps |
 
-Sources: `android-aar/library`. Request `BLUETOOTH_SCAN` and `BLUETOOTH_CONNECT` (API 31+) or location on older APIs.
+Sources: `android-aar/library`. Request `BLUETOOTH_SCAN`, `BLUETOOTH_CONNECT`, and on some OEMs **`ACCESS_FINE_LOCATION`** even on API 31+ (location on older APIs).
 
 **Scan:** temperature and other live values are in scan-response frame **`0x04`** (`telemetry.readings`). Frame **`0x03`** alone fills firmware / battery / cellular but leaves `readings` empty until an active scan delivers `0x04` (usually within a second or two). Keep scanning; do not stop on the first event.
 
@@ -281,6 +427,10 @@ Native GATT maps to: `invalidPin`, `invalidQr`, `invalidConfig`, `notConnected`,
 npm run test:unit
 ```
 
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
 ## License
 
 MIT

package/android/build.gradle

@@ -4,14 +4,14 @@ plugins {
 }
 
 group = 'com.tempivo.sensor.beacon'
-version = '0.3.3'
+version = '0.4.3'
 
 android {
   namespace "expo.modules.tempivosensorbeacon"
   defaultConfig {
     minSdk 26
     versionCode 1
-    versionName "0.3.3"
+    versionName "0.4.3"
   }
   compileOptions {
     sourceCompatibility JavaVersion.VERSION_17

package/android/src/main/AndroidManifest.xml

@@ -5,6 +5,7 @@
     android:name="android.permission.BLUETOOTH_SCAN"
     android:usesPermissionFlags="neverForLocation" />
   <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
-  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />
+  <!-- Some OEMs (e.g. Samsung) still filter BLE scan results without location on API 31+. -->
+  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   <uses-feature android:name="android.hardware.bluetooth_le" android:required="false" />
 </manifest>

package/android/src/main/java/expo/modules/tempivosensorbeacon/SensorBeaconNative.java

@@ -54,8 +54,23 @@ final class SensorBeaconNative {
 
   Map<String, Object> connect(Context context, String qrJson) {
     try {
+      stopScan();
       TempivoSensorQr qr = TempivoSensorQrParser.INSTANCE.parse(qrJson);
-      requireSession(context).connectBlocking(qr);
+      String deviceId = qr.getDeviceId();
+      String mac = qr.getBluetoothMac();
+      if (scanner != null) {
+        TempivoSensorBeaconScanner.SeenDevice seen = scanner.lookup(qr.getSerial());
+        if (seen != null) {
+          if (deviceId == null || deviceId.isEmpty()) {
+            deviceId = seen.getDeviceId();
+          }
+          mac = seen.getBluetoothMac();
+        }
+      }
+      if (deviceId == null || deviceId.isEmpty()) {
+        deviceId = qr.getSerial();
+      }
+      requireSession(context).connectBlocking(qr, deviceId, mac);
       return qrMap(qr);
     } catch (Throwable error) {
       throw wrap(error);
@@ -93,7 +108,6 @@ final class SensorBeaconNative {
       TempivoSensorSession.TriggerResult result = requireSessionConnected().triggerTransmissionBlocking();
       Map<String, Object> payload = new HashMap<>();
       payload.put("ok", result.getOk());
-      payload.put("supported", result.getSupported());
       return payload;
     } catch (Throwable error) {
       throw wrap(error);
@@ -181,9 +195,7 @@ final class SensorBeaconNative {
     payload.put("serial", qr.getSerial());
     payload.put("pin", qr.getPin());
     payload.put("model", qr.getModel());
-    payload.put(
-        "sessionType",
-        qr.getSessionType() == TempivoSensorSession.SessionType.LEGACY ? "legacy" : "modern");
+    payload.put("sessionType", "modern");
     payload.put("bluetoothMac", qr.getBluetoothMac());
     return payload;
   }
@@ -201,6 +213,7 @@ final class SensorBeaconNative {
     payload.put("bluetoothMacAddress", device.getBluetoothMacAddress());
     payload.put("serialNumber", device.getSerialNumber());
     payload.put("rssi", device.getRssi());
+    payload.put("model", device.getModel());
     payload.put("summary", device.getSummary());
     TempivoSensorBeaconTelemetry telemetry = device.getTelemetry();
     payload.put("telemetry", telemetry == null ? null : telemetryMap(telemetry));

package/android/src/main/java/expo/modules/tempivosensorbeacon/TempivoSensorBeaconModule.kt

@@ -8,6 +8,7 @@ import expo.modules.kotlin.Promise
 import expo.modules.kotlin.exception.CodedException
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
+import kotlinx.coroutines.launch
 
 class TempivoSensorBeaconModule : Module() {
   private val native = SensorBeaconNative()
@@ -24,8 +25,11 @@ class TempivoSensorBeaconModule : Module() {
 
     AsyncFunction("startScan") {
       try {
+        val ctx = appContext
         native.startScan(requireContext()) { payload ->
-          sendEvent("onDeviceFound", payload)
+          ctx.mainQueue.launch {
+            sendEvent("onDeviceFound", payload)
+          }
         }
       } catch (error: Throwable) {
         throw error.toSensorException()
@@ -101,7 +105,12 @@ class TempivoSensorBeaconModule : Module() {
 
   private fun blePermissions(): Array<String> {
     return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
-      arrayOf(Manifest.permission.BLUETOOTH_SCAN, Manifest.permission.BLUETOOTH_CONNECT)
+      arrayOf(
+        Manifest.permission.BLUETOOTH_SCAN,
+        Manifest.permission.BLUETOOTH_CONNECT,
+        // Some Samsung/OEM builds still filter scan results without location granted.
+        Manifest.permission.ACCESS_FINE_LOCATION,
+      )
     } else {
       arrayOf(
         Manifest.permission.ACCESS_FINE_LOCATION,

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

@@ -0,0 +1,25 @@
+package com.tempivo.sensor.beacon
+
+/** PIN → reset code + encryption key (HC7 stickers: keep full string for leading zeros). */
+internal data class BleConnectCredentials(
+    val resetCode: Int,
+    val encryptionKey: String,
+)
+
+internal object BleConnectCredentialsResolver {
+    fun fromPin(pin: String): BleConnectCredentials {
+        val trimmed = pin.trim()
+        if (trimmed.isEmpty()) return BleConnectCredentials(-1, "")
+        if (!trimmed.matches(Regex("^\\d+$"))) {
+            return BleConnectCredentials(-1, trimmed)
+        }
+        val parsed = trimmed.toIntOrNull() ?: return BleConnectCredentials(-1, trimmed)
+        val encryptionKey =
+            if (trimmed.length > 4 || trimmed.startsWith("0")) {
+                trimmed
+            } else {
+                ""
+            }
+        return BleConnectCredentials(parsed, encryptionKey)
+    }
+}

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

@@ -0,0 +1,111 @@
+package com.tempivo.sensor.beacon
+
+import pl.efento.mobile.bluetooth.measurement.Measurement
+import java.util.Locale
+import kotlin.math.abs
+import kotlin.math.floor
+
+/** Human-readable measurement type for scan readings (field name kept as typeHex). */
+internal object SdkMeasurementFormat {
+    fun typeHex(m: Measurement<*>): String {
+        val id = typeId(m)
+        if (id != null) return labelForTypeId(id)
+        return m.type.toString().substringAfterLast('.').lowercase(Locale.US)
+    }
+
+    fun labelForTypeId(id: Int): String =
+        when (id) {
+            0x01 -> "temperature"
+            0x02, 0x1B -> "humidity"
+            0x03 -> "pressure"
+            0x04 -> "differential pressure"
+            0x05 -> "ok/alarm"
+            0x06 -> "iaq"
+            0x07 -> "flooding"
+            0x08 -> "pulse count"
+            0x09 -> "electricity meter"
+            0x0A -> "water meter"
+            0x0B -> "soil moisture"
+            0x0C -> "co"
+            0x0D -> "no₂"
+            0x0E -> "h₂s"
+            0x0F -> "ambient light"
+            0x10 -> "pm1.0"
+            0x11 -> "pm2.5"
+            0x12 -> "pm10"
+            0x13 -> "noise"
+            0x14 -> "nh₃"
+            0x15 -> "ch₄"
+            0x16 -> "high pressure"
+            0x17 -> "distance"
+            0x1A -> "co₂"
+            0x1C -> "static iaq"
+            0x1D -> "co₂ equivalent"
+            0x1E -> "breath voc"
+            0x20 -> "percentage"
+            0x21 -> "voltage"
+            0x22 -> "current"
+            else -> "type_${String.format(Locale.US, "%02x", id)}"
+        }
+
+    fun text(m: Measurement<*>): String {
+        val mtype = typeId(m)
+        val v = numericValue(m) ?: return m.value.toString()
+        if (mtype == null) return formatNum(v)
+        if (mtype == 0x06) {
+            val z = v.toInt()
+            val iaq = z % (1 shl 9)
+            val cal = (z shr 9) and 0x03
+            val calS = arrayOf("not_stab", "cal_req", "cal_ongoing", "cal_done")[cal.coerceAtMost(3)]
+            return "$iaq ($calS)"
+        }
+        val unit =
+            when (mtype) {
+                0x01 -> "°C"
+                0x02, 0x1B -> "%"
+                0x03 -> "hPa"
+                0x1A -> "ppm"
+                0x21 -> "mV"
+                0x22 -> "mA"
+                else -> ""
+            }
+        val num =
+            if (abs(v - floor(v)) < 1e-6) {
+                String.format(Locale.US, "%.0f", v)
+            } else {
+                when (mtype) {
+                    0x01, 0x03, 0x0F, 0x13 -> String.format(Locale.US, "%.1f", v)
+                    0x02, 0x1B -> String.format(Locale.US, "%.0f", v)
+                    else -> String.format(Locale.US, "%g", v)
+                }
+            }
+        return if (unit.isEmpty()) num else "$num $unit"
+    }
+
+    private fun typeId(m: Measurement<*>): Int? {
+        val typeName = m.type.toString()
+        Regex("0x([0-9A-Fa-f]+)").find(typeName)?.groupValues?.get(1)?.toIntOrNull(16)?.let { return it }
+        return when (typeName.substringAfterLast('.').uppercase(Locale.US)) {
+            "TEMPERATURE" -> 0x01
+            "HUMIDITY" -> 0x02
+            "PRESSURE" -> 0x03
+            else -> null
+        }
+    }
+
+    private fun numericValue(m: Measurement<*>): Double? =
+        when (val v = m.value) {
+            is Double -> v
+            is Float -> v.toDouble()
+            is Int -> v.toDouble()
+            is Long -> v.toDouble()
+            else -> null
+        }
+
+    private fun formatNum(v: Double): String =
+        if (abs(v - floor(v)) < 0.0001) {
+            v.toInt().toString()
+        } else {
+            v.toString()
+        }
+}