@tempivo/sensor-beacon 0.1.1 → 0.3.0

package/README.md

@@ -1,129 +1,273 @@
 # @tempivo/sensor-beacon
 
-Tempivo partner SDK for **BLE advertising** from Tempivo sensors (manufacturer id **0x026C**). **No GATT connection.**
+BLE for Tempivo sensors. One package for Expo, React Native, Android, iOS, and Node.
 
-One npm package:
+## Expo and React Native
 
-| Path | Use |
-|------|-----|
-| `dist/` | Node / TypeScript decoder |
-| `android/` + `dist/tempivo-sensor-beacon.aar` | Android scan + decode |
-| `ios/` | iOS Swift Package (scan + decode) |
+Needs a development build (or bare React Native). Expo Go is not supported.
 
 ```bash
-npm install @tempivo/sensor-beacon
+npx expo install @tempivo/sensor-beacon
+```
+
+app.json:
+
+```json
+{
+  "expo": {
+    "plugins": ["@tempivo/sensor-beacon"]
+  }
+}
 ```
 
-## Node / TypeScript
+Then rebuild native:
+
+```bash
+npx expo prebuild
+npx expo run:ios
+# or
+npx expo run:android
+```
 
-Node.js 18+. Import from the package root:
+Android minSdk is 26. The plugin sets that on prebuild.
+
+Bare React Native (no Expo app yet):
+
+```bash
+npx install-expo-modules@latest
+npm install @tempivo/sensor-beacon
+```
+
+Add `NSBluetoothAlwaysUsageDescription` on iOS if you do not use Expo prebuild.
 
 ```ts
 import {
-  TEMPVO_SENSOR_MANUFACTURER_ID,
-  normalizeManufacturerBytes,
-  decodeSensorBeaconPayload,
+  parseSensorQrJson,
+  startScan,
+  stopScan,
+  addDeviceFoundListener,
+  connect,
+  setConfigurationJson,
+  getConfiguration,
+  triggerTransmission,
+  getCalibration,
+  disconnect,
 } from '@tempivo/sensor-beacon';
 
-const reading = decodeSensorBeaconPayload(normalizeManufacturerBytes(rawBytes));
+const sub = await addDeviceFoundListener((device) => {
+  console.log(device.serialNumber, device.rssi, device.summary);
+});
+
+await startScan();
+
+const qr = parseSensorQrJson(stickerQrText);
+await connect(qr);
+await setConfigurationJson({
+  schedule: { always: true },
+  temperatureAlerts: [
+    {
+      type: 'range',
+      channel: 'probe',
+      lowC: -30,
+      highC: -10,
+      hysteresisC: 0.5,
+    },
+  ],
+});
+await triggerTransmission();
+const applied = await getConfiguration();
+const cal = await getCalibration();
+await disconnect();
+stopScan();
+sub.remove();
 ```
 
-Many stacks return manufacturer bytes **without** the 2-byte company id (`6C 02`). Use `normalizeManufacturerBytes` when needed.
+`startScan` and `connect` request Bluetooth permission. Sticker PIN is required on `connect`. Wrong PIN is `invalidPin`.
+
+If a bundler misses native BLE, import `@tempivo/sensor-beacon/react-native`.
+
+## Config JSON
+
+Same as Cellular API config profiles (`temperatureAlerts` + `schedule`). You can build it yourself. Profiles are only for REST reuse.
+
+```json
+{
+  "schedule": { "always": true },
+  "temperatureAlerts": [
+    {
+      "type": "range",
+      "channel": "probe",
+      "lowC": -30,
+      "highC": -10,
+      "hysteresisC": 0.5,
+      "transmitOnBreach": true,
+      "transmitOnReturn": true
+    }
+  ]
+}
+```
+
+| Field | Meaning |
+|------|---------|
+| `temperatureAlerts` | Alert list. Empty array is valid. |
+| `schedule` | `{ "always": true }` is 24/7. |
+
+Ignored over BLE: `slug`, `name`, `measurementIntervalMinutes`, `transmissionIntervalSeconds`. Do not pass `alarmRules`.
+
+**Each `temperatureAlerts[]` item**
+
+| Field | Meaning |
+|------|---------|
+| `type` | `range` (band), `min` (below), or `max` (above). |
+| `channel` | `ambient` or `probe`. |
+| `lowC` / `highC` | Inclusive band for `type: "range"`. |
+| `minC` | Threshold for `type: "min"`. |
+| `maxC` | Threshold for `type: "max"`. |
+| `hysteresisC` | Degrees of hysteresis. Omitted: **1**. |
+| `transmitOnBreach` | Uplink when the alert trips. Omitted: **true**. |
+| `transmitOnReturn` | Extra uplink when temp returns inside a `range`. Omitted: **true**. Range only. |
+
+**`schedule` weekday window** (instead of `always`)
+
+| Field | Meaning |
+|------|---------|
+| `weekdays` | **0 = Monday** … **6 = Sunday**. |
+| `from` / `to` | 24h `HH:MM`. |
+| `utcOffsetMinutes` | Offset from UTC for `from` / `to`. |
+
+`GET /api/v1/devices/config-profiles/{slug}` returns `{ "profile": { … } }`. Pass that body or `profile` to `setConfigurationJson`.
 
-### Frame cache (`0x03` + `0x04`)
+## QR object
 
-FW6 devices split meta (advertisement) and measurements (scan response):
+Sticker QR is JSON. Parse with `parseSensorQrJson`.
+
+```json
+{ "sn": "282C024F0012", "pin": "111111", "model": "HC7" }
+```
+
+| Field | Type | Meaning |
+|------|------|---------|
+| `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 | Sticker model. Omitted QR `model` becomes **HC7**. `HC5` selects legacy GATT. |
+| `sessionType` | `modern` \| `legacy` | GATT path. HC7 / firmware 7+ is `modern`. HC5 / firmware 6.x is `legacy`. |
+| `bluetoothMac` | string | BLE MAC with colons, derived from `serial`. |
+
+## Scan result
+
+Filter manufacturer data on company id **0x026C**. Active scanning is on so scan-response packets arrive.
+
+| Field | Meaning |
+|------|---------|
+| `deviceId` | Platform BLE id. Often randomized. Not the sticker serial. |
+| `bluetoothMacAddress` | MAC from the advertisement, with colons. |
+| `serialNumber` | 12 hex chars from advertisement frame `0x03`. Same as QR `sn`. |
+| `rssi` | Signal strength in dBm. |
+| `summary` | Short display line. |
+| `telemetry` | Decoded frames `0x03` + `0x04`, or null until enough bytes arrive. |
+
+**`telemetry`**
+
+| Field | Meaning |
+|------|---------|
+| `firmware` | `major.minor.patch`, e.g. `7.3.4`. |
+| `batteryOk` | Battery status flag. |
+| `encryptionEnabled` | Advertisement payload encryption flag. |
+| `cellularStatus` | `ble_only`, `cell_ok`, `no_server`, or `net_issue`. |
+| `readingTimestampUnix` | Sample time as unix seconds, or null. |
+| `readingTimestampIso` | Same instant as UTC ISO-8601, or null. |
+| `measurementIntervalSeconds` | Sample interval, in seconds. |
+| `readings` | Decoded scan-response slots. |
+| `readingsCount` | Number of measurement slots. |
+| `summary` | Same short line as on the device object. |
+| `measurementCounter` | Counter from frame `0x03`, or null. |
+
+**Each `readings[]` slot**
+
+| Field | Meaning |
+|------|---------|
+| `typeHex` | Slot type, e.g. `0x01` temperature, `0x02` humidity. |
+| `raw24` | Undecoded 24-bit payload. |
+| `text` | Display value with unit, e.g. `21.8 °C`. |
+
+`triggerTransmission()` returns `{ ok, supported }`. `supported: false` is not an error.
+
+`getCalibration()` returns `{ laboratoryCalibrationDate, laboratoryCalibrationTimestamp }`. Date is `YYYY-MM-DD`, or null if unset.
+
+## Node / TypeScript helpers
+
+Decode advertisements and parse QR / config without native BLE.
 
 ```ts
 import {
-  createSensorBeaconFrameCache,
-  ingestManufacturerPayload,
-  buildSensorBeaconReading,
-  macKeyFromAddress,
+  normalizeManufacturerBytes,
+  decodeSensorBeaconPayload,
+  parseSensorQrJson,
+  parseSensorConfigurationJson,
 } from '@tempivo/sensor-beacon';
 
-const cache = createSensorBeaconFrameCache();
-const macKey = macKeyFromAddress('28:2C:02:4F:00:12');
-ingestManufacturerPayload(advPayload, macKey, cache);
-ingestManufacturerPayload(scanPayload, macKey, cache);
-const reading = buildSensorBeaconReading(cache.last03.get(macKey), cache.last04.get(macKey));
+const qr = parseSensorQrJson('{"sn":"282C024F0012","pin":"111111","model":"HC7"}');
+const reading = decodeSensorBeaconPayload(normalizeManufacturerBytes(advertisementBytes));
+const cfg = parseSensorConfigurationJson(/* config JSON above */);
 ```
 
-### TypeScript API
-
-| Export | Purpose |
-|--------|---------|
-| `TEMPVO_SENSOR_MANUFACTURER_ID` | BLE company id `0x026c` |
-| `normalizeManufacturerBytes` | Strip company id prefix when present |
-| `decodeSensorBeaconPayload` | One-shot decode |
-| `ingestManufacturerPayload` | Update frame cache |
-| `buildSensorBeaconReading` | Merge cached frames |
-| `SensorBeaconReading` | Parsed device + measurements |
+Invalid QR or config throws `TempivoSensorError` (`invalidQr`, `invalidPin`, `invalidConfig`).
 
-Measurement types **0x01–0x22** decode to human-readable `text` on each slot.
+## Android (Kotlin)
 
-## Android
-
-Published artifact: `dist/tempivo-sensor-beacon.aar` (built before npm publish).
+AAR: `dist/tempivo-sensor-beacon.aar` after `npm run build:android`. Sources: `android-aar/library`. Request `BLUETOOTH_SCAN` and `BLUETOOTH_CONNECT` (API 31+) or location on older APIs.
 
 ```kotlin
-// app/build.gradle.kts
-dependencies {
-    implementation(
-        files(
-            "${rootProject.projectDir}/../node_modules/@tempivo/sensor-beacon/dist/tempivo-sensor-beacon.aar",
-        ),
-    )
+val qr = TempivoSensorQrParser.parse(stickerQrText)
+val session = TempivoSensorSession(context)
+
+session.connect(qr)
+try {
+    session.setConfigurationJson(profileJson)
+    val trigger = session.triggerTransmission()
+    val applied = session.getConfiguration()
+    val cal = session.getCalibration()
+} finally {
+    session.disconnect()
 }
 ```
 
-Adjust the path to your `node_modules` layout.
-
 ```kotlin
-import com.tempivo.sensor.beacon.TempivoSensorBeaconScanner
-
 val scanner = TempivoSensorBeaconScanner(context)
 scanner.startScan { device ->
-    // device.serialNumber, device.rssi, device.telemetry, device.summary
+    Log.d("scan", "${device.serialNumber} rssi=${device.rssi} ${device.summary}")
 }
 ```
 
-Declare and request `BLUETOOTH_SCAN` (API 31+) or location permissions for legacy APIs.
-
-## iOS
+## iOS (Swift)
 
-1. **File → Add Package Dependencies… → Add Local…**
-2. Path: `node_modules/@tempivo/sensor-beacon/ios`
-3. Add product **TempivoSensorBeacon**
-4. Set **`NSBluetoothAlwaysUsageDescription`** in Info.plist
+Needs a physical device for GATT. Simulator can scan advertisements only. Set **`NSBluetoothAlwaysUsageDescription`** in Info.plist.
 
 ```swift
-import TempivoSensorBeacon
-
-final class ScanHost: NSObject, TempivoSensorBeaconScannerDelegate {
-    private let scanner = TempivoSensorBeaconScanner()
-
-    override init() {
-        super.init()
-        scanner.delegate = self
-    }
-
-    func start() { scanner.startScanning() }
+let qr = try TempivoSensorQrParser.parse(stickerQrText)
+let session = TempivoSensorSession()
+try session.connect(qr: qr)
+defer { session.disconnect() }
+try session.setConfigurationJson(profileJson)
+_ = try session.triggerTransmission()
+let applied = try session.getConfiguration()
+let cal = try session.getCalibration()
+```
 
-    func sensorBeaconScanner(_ scanner: TempivoSensorBeaconScanner, didDiscover discovery: SensorBeaconDiscovery) {
-        print(discovery.serialNumber ?? discovery.deviceId, discovery.reading?.summary ?? "")
-    }
+```swift
+func sensorBeaconScanner(_ scanner: TempivoSensorBeaconScanner, didDiscover discovery: SensorBeaconDiscovery) {
+    print(discovery.serialNumber ?? "", discovery.rssi, discovery.reading?.summary ?? "")
 }
 ```
 
-Requires iOS 15+. Use a physical device for BLE.
+## Errors
+
+Native GATT maps to: `invalidPin`, `invalidQr`, `invalidConfig`, `notConnected`, `unsupportedCommand`, `connectFailed`, `runtimeUnavailable`, `unknown`.
 
-## Build locally
+## Tests
 
 ```bash
-npm run build:ts          # dist/ only
-npm run build:android     # requires Android SDK
-npm run build:all         # both
+npm run test:unit
 ```
 
 ## License

package/android/build.gradle

@@ -1,4 +1,40 @@
 plugins {
-    id "com.android.library" version "8.7.3" apply false
-    id "org.jetbrains.kotlin.android" version "2.2.21" apply false
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'com.tempivo.sensor.beacon'
+version = '0.3.0'
+
+android {
+  namespace "expo.modules.tempivosensorbeacon"
+  defaultConfig {
+    minSdk 26
+    versionCode 1
+    versionName "0.3.0"
+  }
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+  kotlinOptions {
+    jvmTarget = "17"
+    // Native BLE runtime is Kotlin 2.3. Expo 57 compiles with Kotlin 2.1.
+    freeCompilerArgs += ["-Xskip-metadata-version-check"]
+  }
+}
+
+def aarFile = file("libs/tempivo-sensor-beacon.aar")
+if (!aarFile.exists()) {
+  throw new GradleException("Missing android/libs/tempivo-sensor-beacon.aar. From the package root run: npm run build:android")
+}
+
+dependencies {
+  compileOnly files(aarFile)
+  compileOnly "pl.efento.mobile:bluetooth:2.3.0"
+  runtimeOnly files(aarFile)
+  runtimeOnly "pl.efento.mobile:bluetooth:2.3.0"
+  runtimeOnly "androidx.core:core-ktx:1.17.0"
+  runtimeOnly "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2"
+  runtimeOnly "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2"
 }

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,10 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
+  <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
+  <uses-permission
+    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" />
+  <uses-feature android:name="android.hardware.bluetooth_le" android:required="false" />
+</manifest>

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

@@ -0,0 +1,233 @@
+package expo.modules.tempivosensorbeacon;
+
+import android.content.Context;
+import com.tempivo.sensor.beacon.TempivoSensorBeaconDevice;
+import com.tempivo.sensor.beacon.TempivoSensorBeaconScanner;
+import com.tempivo.sensor.beacon.TempivoSensorBeaconTelemetry;
+import com.tempivo.sensor.beacon.TempivoSensorCalibration;
+import com.tempivo.sensor.beacon.TempivoSensorException;
+import com.tempivo.sensor.beacon.TempivoSensorQr;
+import com.tempivo.sensor.beacon.TempivoSensorQrParser;
+import com.tempivo.sensor.beacon.TempivoSensorSession;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Java facade so the Expo Kotlin module can compile with Kotlin 2.1 against a Kotlin 2.3 AAR.
+ */
+final class SensorBeaconNative {
+  interface DeviceCallback {
+    void onDevice(Map<String, Object> payload);
+  }
+
+  static final class NativeError extends RuntimeException {
+    final String code;
+
+    NativeError(String code, String message, Throwable cause) {
+      super(message, cause);
+      this.code = code;
+    }
+  }
+
+  private TempivoSensorBeaconScanner scanner;
+  private TempivoSensorSession session;
+
+  void startScan(Context context, DeviceCallback callback) {
+    try {
+      requireScanner(context).startScan(device -> callback.onDevice(deviceMap(device)));
+    } catch (Throwable error) {
+      throw wrap(error);
+    }
+  }
+
+  void stopScan() {
+    if (scanner != null) {
+      scanner.stopScan();
+    }
+  }
+
+  boolean isScanning() {
+    return scanner != null && scanner.isScanning();
+  }
+
+  Map<String, Object> connect(Context context, String qrJson) {
+    try {
+      TempivoSensorQr qr = TempivoSensorQrParser.INSTANCE.parse(qrJson);
+      requireSession(context).connectBlocking(qr);
+      return qrMap(qr);
+    } catch (Throwable error) {
+      throw wrap(error);
+    }
+  }
+
+  void disconnect() {
+    try {
+      if (session != null) {
+        session.disconnectBlocking();
+      }
+    } catch (Throwable error) {
+      throw wrap(error);
+    }
+  }
+
+  String getConfigurationJson() {
+    try {
+      return requireSessionConnected().getConfigurationJsonBlocking();
+    } catch (Throwable error) {
+      throw wrap(error);
+    }
+  }
+
+  void setConfigurationJson(String json) {
+    try {
+      requireSessionConnected().setConfigurationJsonBlocking(json);
+    } catch (Throwable error) {
+      throw wrap(error);
+    }
+  }
+
+  Map<String, Object> triggerTransmission() {
+    try {
+      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);
+    }
+  }
+
+  Map<String, Object> getCalibration() {
+    try {
+      return calibrationMap(requireSessionConnected().getCalibrationBlocking());
+    } catch (Throwable error) {
+      throw wrap(error);
+    }
+  }
+
+  private TempivoSensorBeaconScanner requireScanner(Context context) {
+    if (scanner == null) {
+      scanner = new TempivoSensorBeaconScanner(context);
+    }
+    return scanner;
+  }
+
+  private TempivoSensorSession requireSession(Context context) {
+    if (session == null) {
+      session = new TempivoSensorSession(context);
+    }
+    return session;
+  }
+
+  private TempivoSensorSession requireSessionConnected() {
+    if (session == null) {
+      throw new NativeError("notConnected", "Not connected.", null);
+    }
+    return session;
+  }
+
+  private static NativeError wrap(Throwable error) {
+    if (error instanceof NativeError) {
+      return (NativeError) error;
+    }
+    TempivoSensorException sensor = findSensor(error);
+    if (sensor != null) {
+      return new NativeError(toJs(sensor.getCode()), sensor.getMessage(), error);
+    }
+    if (error instanceof TempivoSensorBeaconScanner.ScanNotPermittedException) {
+      return new NativeError("runtimeUnavailable", error.getMessage(), error);
+    }
+    String message = error.getMessage();
+    return new NativeError("unknown", message != null ? message : "Sensor request failed.", error);
+  }
+
+  private static TempivoSensorException findSensor(Throwable error) {
+    Throwable current = error;
+    while (current != null) {
+      if (current instanceof TempivoSensorException) {
+        return (TempivoSensorException) current;
+      }
+      current = current.getCause();
+    }
+    return null;
+  }
+
+  private static String toJs(TempivoSensorException.Code code) {
+    switch (code) {
+      case INVALID_PIN:
+        return "invalidPin";
+      case INVALID_QR:
+        return "invalidQr";
+      case INVALID_CONFIG:
+        return "invalidConfig";
+      case NOT_CONNECTED:
+        return "notConnected";
+      case UNSUPPORTED_COMMAND:
+        return "unsupportedCommand";
+      case RUNTIME_UNAVAILABLE:
+        return "runtimeUnavailable";
+      case CONNECT_FAILED:
+        return "connectFailed";
+      default:
+        return "unknown";
+    }
+  }
+
+  private static Map<String, Object> qrMap(TempivoSensorQr qr) {
+    Map<String, Object> payload = new HashMap<>();
+    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("bluetoothMac", qr.getBluetoothMac());
+    return payload;
+  }
+
+  private static Map<String, Object> calibrationMap(TempivoSensorCalibration cal) {
+    Map<String, Object> payload = new HashMap<>();
+    payload.put("laboratoryCalibrationDate", cal.getLaboratoryCalibrationDate());
+    payload.put("laboratoryCalibrationTimestamp", cal.getLaboratoryCalibrationTimestamp());
+    return payload;
+  }
+
+  private static Map<String, Object> deviceMap(TempivoSensorBeaconDevice device) {
+    Map<String, Object> payload = new HashMap<>();
+    payload.put("deviceId", device.getDeviceId());
+    payload.put("bluetoothMacAddress", device.getBluetoothMacAddress());
+    payload.put("serialNumber", device.getSerialNumber());
+    payload.put("rssi", device.getRssi());
+    payload.put("summary", device.getSummary());
+    TempivoSensorBeaconTelemetry telemetry = device.getTelemetry();
+    payload.put("telemetry", telemetry == null ? null : telemetryMap(telemetry));
+    return payload;
+  }
+
+  private static Map<String, Object> telemetryMap(TempivoSensorBeaconTelemetry telemetry) {
+    Map<String, Object> payload = new HashMap<>();
+    payload.put("firmware", telemetry.getFirmware());
+    payload.put("batteryOk", telemetry.getBatteryOk());
+    payload.put("encryptionEnabled", telemetry.getEncryptionEnabled());
+    payload.put("cellularStatus", telemetry.getCellularStatus());
+    payload.put("measurementCounter", telemetry.getMeasurementCounter());
+    payload.put("readingTimestampUnix", telemetry.getReadingTimestampUnix());
+    payload.put("readingTimestampIso", telemetry.getReadingTimestampIso());
+    payload.put("measurementIntervalSeconds", telemetry.getMeasurementIntervalSeconds());
+    payload.put("readingsCount", telemetry.getReadingsCount());
+    payload.put("summary", telemetry.getSummary());
+    List<Map<String, Object>> readings = new ArrayList<>();
+    telemetry.getReadings().forEach(reading -> {
+      Map<String, Object> row = new HashMap<>();
+      row.put("typeHex", reading.getTypeHex());
+      row.put("raw24", reading.getRaw24());
+      row.put("text", reading.getText());
+      readings.add(row);
+    });
+    payload.put("readings", readings);
+    return payload;
+  }
+}