@tempivo/sensor-beacon 0.1.0 → 0.1.1

package/ios/Sources/TempivoSensorBeacon/TempivoSensorBeaconDecoder.swift

@@ -0,0 +1,413 @@
+import Foundation
+
+/// Decodes Tempivo sensor BLE manufacturer data (advertisement frame `0x03` + scan response `0x04`).
+public enum TempivoSensorBeaconDecoder {
+
+    public static let advFrame03Len = 22
+
+    private static let measureTypes: [UInt8: (name: String, resolution: Double, metaFactor: Int, continuous: Bool)] = [
+        0x01: ("Temperature", 0.1, 1, true),
+        0x02: ("Humidity", 1.0, 1, true),
+        0x03: ("Atmospheric pressure", 0.1, 1, true),
+        0x04: ("Differential pressure", 1.0, 1, true),
+        0x05: ("OK/Alarm", 1.0, 1, false),
+        0x06: ("IAQ", 1.0, 3, true),
+        0x07: ("Flooding", 1.0, 1, false),
+        0x08: ("Pulse count", 1.0, 1, true),
+        0x09: ("Electricity meter", 1.0, 1, true),
+        0x0A: ("Water meter", 1.0, 1, true),
+        0x0B: ("Soil moisture", 1.0, 1, true),
+        0x0C: ("CO", 1.0, 1, true),
+        0x0D: ("NO₂", 1.0, 1, true),
+        0x0E: ("H₂S", 0.01, 1, true),
+        0x0F: ("Ambient light", 0.1, 1, true),
+        0x10: ("PM1.0", 1.0, 1, true),
+        0x11: ("PM2.5", 1.0, 1, true),
+        0x12: ("PM10", 1.0, 1, true),
+        0x13: ("Noise", 0.1, 1, true),
+        0x14: ("NH₃", 1.0, 1, true),
+        0x15: ("CH₄", 1.0, 1, true),
+        0x16: ("High pressure", 1.0, 1, true),
+        0x17: ("Distance", 1.0, 1, true),
+        0x1A: ("CO₂", 1.0, 3, true),
+        0x1B: ("Humidity", 0.1, 1, true),
+        0x1C: ("Static IAQ", 1.0, 3, true),
+        0x1D: ("CO₂ equivalent", 1.0, 3, true),
+        0x1E: ("Breath VOC", 1.0, 3, true),
+        0x20: ("Percentage", 0.01, 1, true),
+        0x21: ("Voltage", 0.1, 1, true),
+        0x22: ("Current", 0.01, 1, true),
+    ]
+
+    /// Strips the 2-byte company id when present so the payload starts with frame tag `0x03` / `0x04`.
+    public static func normalizeManufacturerBytes(_ data: Data) -> Data {
+        let bytes = [UInt8](data)
+        guard bytes.count >= 2 else { return data }
+        let company = UInt16(bytes[0]) | (UInt16(bytes[1]) << 8)
+        guard company == TEMPVO_SENSOR_MANUFACTURER_ID else { return data }
+        return Data(bytes.dropFirst(2))
+    }
+
+    public static func serialKeyFromAdv03(_ frame: [UInt8]) -> String? {
+        guard frame.count >= 7, frame[0] == 0x03 else { return nil }
+        return frame[1...6].map { String(format: "%02X", $0) }.joined()
+    }
+
+    public static func macKey(_ macWithColons: String) -> String {
+        macWithColons.replacingOccurrences(of: ":", with: "").uppercased()
+    }
+
+    public static func macWithColons(fromKey key: String) -> String {
+        let k = key.uppercased()
+        guard k.count == 12 else { return key }
+        var parts: [String] = []
+        var idx = k.startIndex
+        while idx < k.endIndex {
+            let next = k.index(idx, offsetBy: 2, limitedBy: k.endIndex) ?? k.endIndex
+            parts.append(String(k[idx..<next]))
+            idx = next
+        }
+        return parts.joined(separator: ":")
+    }
+
+    public static func lookupKeys(primaryMacKey: String, extraSerialKey: String? = nil) -> [String] {
+        var keys = [primaryMacKey.uppercased()]
+        if let extra = extraSerialKey?.uppercased(), !extra.isEmpty, !keys.contains(extra) {
+            keys.append(extra)
+        }
+        return keys
+    }
+
+    /// Decodes a single manufacturer payload (normalized or iOS-style with company id prefix).
+    public static func decodeSensorBeaconPayload(_ data: Data) -> SensorBeaconReading? {
+        let payload = normalizeManufacturerBytes(data)
+        let adv03 = extractFrame(tag: 0x03, from: payload, fixedLen: advFrame03Len)
+        let adv04 = extractFrame(tag: 0x04, from: payload, fixedLen: nil)
+        return buildSensorBeaconReading(adv03: adv03, adv04: adv04)
+    }
+
+    /// Stores `0x03` / `0x04` frames in `cache`. Payload may include or omit the company id prefix.
+    @discardableResult
+    public static func ingestManufacturerPayload(
+        _ data: Data,
+        primaryMacKey: String,
+        cache: inout SensorBeaconFrameCache
+    ) -> Bool {
+        ingestManufacturerPayload(data, primaryMacKey: primaryMacKey, last03: &cache.last03, last04: &cache.last04)
+    }
+
+    /// iOS `CBAdvertisementDataManufacturerDataKey` includes company id `6C 02` little-endian first.
+    @discardableResult
+    public static func ingestManufacturerData(
+        _ manufacturerData: Data,
+        primaryMacKey: String,
+        cache: inout SensorBeaconFrameCache
+    ) -> Bool {
+        ingestManufacturerData(
+            manufacturerData,
+            primaryMacKey: primaryMacKey,
+            last03: &cache.last03,
+            last04: &cache.last04
+        )
+    }
+
+    public static func buildSensorBeaconReading(
+        cacheKeys: [String],
+        cache: SensorBeaconFrameCache,
+        serialNumber: String? = nil,
+        bluetoothMacAddress: String? = nil
+    ) -> SensorBeaconReading? {
+        let keys = cacheKeys.map { $0.uppercased() }
+        let d03 = keys.compactMap { cache.last03[$0] }.first.map { [UInt8]($0) }
+        let d04 = keys.compactMap { cache.last04[$0] }.first.map { [UInt8]($0) }
+        guard var reading = buildSensorBeaconReading(adv03: d03, adv04: d04) else { return nil }
+        if reading.serialNumber == nil { reading = reading.withIdentity(serialNumber: serialNumber, bluetoothMacAddress: bluetoothMacAddress) }
+        return reading
+    }
+
+    public static func macFromManufacturerData(_ data: Data) -> String? {
+        let bytes = [UInt8](normalizeManufacturerBytes(data))
+        guard bytes.count >= 7, bytes[0] == 0x03 else { return nil }
+        return bytes[1...6].map { String(format: "%02X", $0) }.joined(separator: ":")
+    }
+
+    // MARK: - Internal frame cache ingest
+
+    @discardableResult
+    private static func ingestManufacturerPayload(
+        _ data: Data,
+        primaryMacKey: String,
+        last03: inout [String: Data],
+        last04: inout [String: Data]
+    ) -> Bool {
+        let payload = [UInt8](normalizeManufacturerBytes(data))
+        return ingestNormalizedPayload(payload, primaryMacKey: primaryMacKey, last03: &last03, last04: &last04)
+    }
+
+    @discardableResult
+    private static func ingestManufacturerData(
+        _ manufacturerData: Data,
+        primaryMacKey: String,
+        last03: inout [String: Data],
+        last04: inout [String: Data]
+    ) -> Bool {
+        let bytes = [UInt8](manufacturerData)
+        guard bytes.count >= 3 else { return false }
+        let company = UInt16(bytes[0]) | (UInt16(bytes[1]) << 8)
+        guard company == TEMPVO_SENSOR_MANUFACTURER_ID else { return false }
+        return ingestNormalizedPayload(Array(bytes.dropFirst(2)), primaryMacKey: primaryMacKey, last03: &last03, last04: &last04)
+    }
+
+    @discardableResult
+    private static func ingestNormalizedPayload(
+        _ payload: [UInt8],
+        primaryMacKey: String,
+        last03: inout [String: Data],
+        last04: inout [String: Data]
+    ) -> Bool {
+        var changed = false
+        let frames = splitSensorFrames(payload)
+        for fr in frames {
+            guard let tag = fr.first else { continue }
+            if tag == 0x03, fr.count >= advFrame03Len {
+                let frame = Array(fr.prefix(advFrame03Len))
+                let keys = lookupKeys(primaryMacKey: primaryMacKey, extraSerialKey: serialKeyFromAdv03(frame))
+                for key in keys {
+                    let data = Data(frame)
+                    if last03[key] != data {
+                        last03[key] = data
+                        changed = true
+                    }
+                }
+            } else if tag == 0x04 {
+                let keys = lookupKeys(primaryMacKey: primaryMacKey)
+                let data = Data(fr)
+                for key in keys {
+                    if last04[key] != data {
+                        last04[key] = data
+                        changed = true
+                    }
+                }
+            }
+        }
+        return changed
+    }
+
+    private static func extractFrame(tag: UInt8, from payload: Data, fixedLen: Int?) -> [UInt8]? {
+        let bytes = [UInt8](payload)
+        for fr in splitSensorFrames(bytes) {
+            guard fr.first == tag else { continue }
+            if let fixedLen, fr.count >= fixedLen {
+                return Array(fr.prefix(fixedLen))
+            }
+            return fr
+        }
+        return nil
+    }
+
+    private static func splitSensorFrames(_ payload: [UInt8]) -> [[UInt8]] {
+        var out: [[UInt8]] = []
+        var i = 0
+        let n = payload.count
+        while i < n {
+            if payload[i] == 0x03 && i + advFrame03Len <= n {
+                out.append(Array(payload[i..<(i + advFrame03Len)]))
+                i += advFrame03Len
+            } else if payload[i] == 0x04 {
+                var j = i + 1
+                while j + 4 <= n {
+                    if j + 4 > n - 2 { break }
+                    let mtype = payload[j]
+                    if mtype == 0 || mtype > 0x26 { break }
+                    j += 4
+                }
+                if n - j >= 2 {
+                    out.append(Array(payload[i..<(j + 2)]))
+                    i = j + 2
+                } else {
+                    out.append(Array(payload[i..<n]))
+                    break
+                }
+            } else {
+                i += 1
+            }
+        }
+        return out
+    }
+
+    private static func zigzagDecode24(_ raw: UInt32) -> Int {
+        let n = Int(raw)
+        return (n >> 1) ^ (-(n & 1))
+    }
+
+    private static func decodeSlot(mtype: UInt8, raw24: UInt32) -> String {
+        guard let spec = measureTypes[mtype] else {
+            return String(format: "0x%02X: 0x%06X", mtype, raw24)
+        }
+        if !spec.continuous {
+            return "(status)"
+        }
+        let z = zigzagDecode24(raw24)
+        if spec.metaFactor == 1 {
+            let val = Double(z) * spec.resolution
+            let unit: String
+            switch mtype {
+            case 0x01: unit = "°C"
+            case 0x02, 0x1B: unit = "%"
+            case 0x03: unit = "hPa"
+            case 0x1A: unit = "ppm"
+            case 0x21: unit = "mV"
+            case 0x22: unit = "mA"
+            default: unit = ""
+            }
+            let num: String
+            if abs(val - floor(val)) < 0.0001 {
+                num = String(format: "%.0f", val)
+            } else {
+                switch mtype {
+                case 0x01, 0x03, 0x0F, 0x13: num = String(format: "%.1f", val)
+                case 0x02, 0x1B: num = String(format: "%.0f", val)
+                default: num = String(format: "%g", val)
+                }
+            }
+            return unit.isEmpty ? num : "\(num) \(unit)"
+        }
+        if mtype == 0x06 {
+            let iaq = z % (1 << 9)
+            let cal = (z >> 9) & 0x03
+            let calS = ["not_stab", "cal_req", "cal_ongoing", "cal_done"][min(cal, 3)]
+            return "\(iaq) (\(calS))"
+        }
+        if mtype == 0x1A || mtype == 0x1C || mtype == 0x1D || mtype == 0x1E {
+            let v = Double(z / spec.metaFactor) * spec.resolution
+            return String(format: "%g", v)
+        }
+        return String(z)
+    }
+
+    static func buildSensorBeaconReading(adv03: [UInt8]?, adv04: [UInt8]?) -> SensorBeaconReading? {
+        var firmware: String?
+        var batteryOk: Bool?
+        var encryptionEnabled: Bool?
+        var cellularStatus: String?
+        var measurementCounter: Int?
+        var readingTimestampUnix: Int?
+        var readingTimestampIso: String?
+        var periodBaseSeconds: Int?
+        var periodFactor: Int?
+        var serialNumber: String?
+        var bluetoothMacAddress: String?
+        var summaryParts: [String] = []
+        var readings: [SensorBeaconMeasurement] = []
+
+        if let a3 = adv03, a3.count >= advFrame03Len, a3[0] == 0x03 {
+            serialNumber = serialKeyFromAdv03(a3)
+            if let serialNumber {
+                bluetoothMacAddress = macWithColons(fromKey: serialNumber)
+            }
+
+            let fwRaw = (UInt16(a3[7]) << 8) | UInt16(a3[8])
+            let major = (fwRaw >> 11) & 0x1F
+            let minor = (fwRaw >> 5) & 0x3F
+            let lts = fwRaw & 0x1F
+            firmware = "\(major).\(minor).\(lts)"
+
+            let st = a3[9]
+            batteryOk = (st & 1) != 0
+            encryptionEnabled = ((st >> 3) & 1) != 0
+            let cell = (st >> 6) & 3
+            let cellLabels = ["ble_only", "cell_ok", "no_server", "net_issue"]
+            cellularStatus = cellLabels[Int(cell)]
+
+            if a3.count >= 14 {
+                let ts = UInt32(a3[10]) << 24 | UInt32(a3[11]) << 16 | UInt32(a3[12]) << 8 | UInt32(a3[13])
+                measurementCounter = Int(ts)
+                readingTimestampUnix = Int(ts)
+                if ts > 1_000_000_000, ts < 4_000_000_000 {
+                    let d = Date(timeIntervalSince1970: TimeInterval(ts))
+                    let f = ISO8601DateFormatter()
+                    f.formatOptions = [.withInternetDateTime]
+                    readingTimestampIso = f.string(from: d)
+                }
+            }
+            if a3.count >= 18 {
+                let pbase = UInt16(a3[14]) << 8 | UInt16(a3[15])
+                let pfact = UInt16(a3[16]) << 8 | UInt16(a3[17])
+                periodBaseSeconds = Int(pbase)
+                periodFactor = Int(pfact)
+            }
+        }
+
+        if let a4 = adv04, a4.count >= 5, a4[0] == 0x04 {
+            var i = 1
+            while i + 4 <= a4.count - 2 {
+                let mtype = a4[i]
+                if mtype == 0 { break }
+                let raw24 = UInt32(a4[i + 1]) << 16 | UInt32(a4[i + 2]) << 8 | UInt32(a4[i + 3])
+                let text = decodeSlot(mtype: mtype, raw24: raw24)
+                summaryParts.append(text)
+                readings.append(
+                    SensorBeaconMeasurement(
+                        typeHex: String(format: "0x%02X", mtype),
+                        raw24: Int(raw24 & 0xFFFFFF),
+                        text: text
+                    )
+                )
+                i += 4
+            }
+        }
+
+        let summary: String
+        if summaryParts.isEmpty {
+            if adv03 != nil {
+                summary = readingTimestampIso ?? "Adv OK. Wait for scan response (measurements)"
+            } else {
+                summary = ""
+            }
+        } else {
+            summary = summaryParts.prefix(4).joined(separator: " · ")
+        }
+
+        if summary.isEmpty && adv03 == nil && adv04 == nil { return nil }
+
+        let summaryOut = summary.isEmpty ? (readingTimestampIso ?? "") : summary
+
+        return SensorBeaconReading(
+            serialNumber: serialNumber,
+            bluetoothMacAddress: bluetoothMacAddress,
+            firmware: firmware,
+            batteryOk: batteryOk,
+            encryptionEnabled: encryptionEnabled,
+            cellularStatus: cellularStatus,
+            measurementCounter: measurementCounter,
+            readingTimestampUnix: readingTimestampUnix,
+            readingTimestampIso: readingTimestampIso,
+            periodBaseSeconds: periodBaseSeconds,
+            periodFactor: periodFactor,
+            readings: readings,
+            readingsCount: summaryParts.count,
+            summary: summaryOut
+        )
+    }
+}
+
+private extension SensorBeaconReading {
+    func withIdentity(serialNumber: String?, bluetoothMacAddress: String?) -> SensorBeaconReading {
+        SensorBeaconReading(
+            serialNumber: serialNumber ?? self.serialNumber,
+            bluetoothMacAddress: bluetoothMacAddress ?? self.bluetoothMacAddress,
+            firmware: firmware,
+            batteryOk: batteryOk,
+            encryptionEnabled: encryptionEnabled,
+            cellularStatus: cellularStatus,
+            measurementCounter: measurementCounter,
+            readingTimestampUnix: readingTimestampUnix,
+            readingTimestampIso: readingTimestampIso,
+            periodBaseSeconds: periodBaseSeconds,
+            periodFactor: periodFactor,
+            readings: readings,
+            readingsCount: readingsCount,
+            summary: summary
+        )
+    }
+}

package/ios/Sources/TempivoSensorBeacon/TempivoSensorBeaconScanner.swift

@@ -0,0 +1,159 @@
+import CoreBluetooth
+import Foundation
+
+public protocol TempivoSensorBeaconScannerDelegate: AnyObject {
+    func sensorBeaconScanner(_ scanner: TempivoSensorBeaconScanner, didDiscover discovery: SensorBeaconDiscovery)
+    func sensorBeaconScanner(_ scanner: TempivoSensorBeaconScanner, didUpdateState state: CBManagerState)
+}
+
+public extension TempivoSensorBeaconScannerDelegate {
+    func sensorBeaconScanner(_ scanner: TempivoSensorBeaconScanner, didUpdateState state: CBManagerState) {}
+}
+
+/// Active BLE scan for Tempivo sensor beacons (manufacturer `0x026C`). Advertising only. No GATT or connect.
+public final class TempivoSensorBeaconScanner: NSObject {
+
+    public weak var delegate: TempivoSensorBeaconScannerDelegate?
+
+    private var central: CBCentralManager!
+    private var frameCache = SensorBeaconFrameCache()
+    private var isScanning = false
+    private var pendingStart = false
+
+    public override init() {
+        super.init()
+        central = CBCentralManager(delegate: self, queue: .main)
+    }
+
+    public var bluetoothState: CBManagerState {
+        central.state
+    }
+
+    public var scanning: Bool {
+        isScanning
+    }
+
+    /// Clears cached `0x03` / `0x04` frames. Does not stop an active scan.
+    public func clearCache() {
+        frameCache.clear()
+    }
+
+    /// Starts an active scan (duplicate advertisements allowed). Requires Bluetooth powered on.
+    public func startScanning() {
+        pendingStart = true
+        if central.state == .poweredOn {
+            beginScanningIfNeeded()
+        }
+    }
+
+    /// Stops scanning and clears pending start.
+    public func stopScanning() {
+        pendingStart = false
+        guard isScanning else { return }
+        central.stopScan()
+        isScanning = false
+    }
+
+    private func beginScanningIfNeeded() {
+        guard pendingStart, central.state == .poweredOn, !isScanning else { return }
+        frameCache.clear()
+        central.scanForPeripherals(
+            withServices: nil,
+            options: [CBCentralManagerScanOptionAllowDuplicatesKey: true]
+        )
+        isScanning = true
+    }
+
+    private func isTempivoManufacturerData(_ advertisementData: [String: Any]) -> Bool {
+        guard let mdata = advertisementData[CBAdvertisementDataManufacturerDataKey] as? Data, mdata.count >= 2 else {
+            return false
+        }
+        let b = [UInt8](mdata.prefix(2))
+        let company = UInt16(b[0]) | (UInt16(b[1]) << 8)
+        return company == TEMPVO_SENSOR_MANUFACTURER_ID
+    }
+
+    private func cacheKeys(
+        serial: String?,
+        macWithColons: String?,
+        deviceId: String
+    ) -> [String] {
+        var set = Set<String>()
+        let sn = serial?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !sn.isEmpty {
+            for k in TempivoSensorBeaconDecoder.lookupKeys(primaryMacKey: sn) { set.insert(k) }
+        }
+        let mac = macWithColons?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !mac.isEmpty {
+            let mk = TempivoSensorBeaconDecoder.macKey(mac)
+            for k in TempivoSensorBeaconDecoder.lookupKeys(primaryMacKey: mk) { set.insert(k) }
+        }
+        let id = deviceId.trimmingCharacters(in: .whitespacesAndNewlines)
+        if !id.isEmpty { set.insert(id.uppercased()) }
+        return Array(set)
+    }
+
+    private func handleDiscovery(
+        peripheral: CBPeripheral,
+        advertisementData: [String: Any],
+        rssi: NSNumber
+    ) {
+        guard isTempivoManufacturerData(advertisementData) else { return }
+
+        let deviceId = peripheral.identifier.uuidString
+
+        var serialNumber: String?
+        var bluetoothMacAddress: String?
+
+        if let mdata = advertisementData[CBAdvertisementDataManufacturerDataKey] as? Data {
+            if let mac = TempivoSensorBeaconDecoder.macFromManufacturerData(mdata) {
+                bluetoothMacAddress = mac
+                serialNumber = TempivoSensorBeaconDecoder.macKey(mac)
+            }
+            let primaryKey = serialNumber ?? deviceId
+            _ = TempivoSensorBeaconDecoder.ingestManufacturerData(
+                mdata,
+                primaryMacKey: primaryKey,
+                cache: &frameCache
+            )
+        }
+
+        let keys = cacheKeys(serial: serialNumber, macWithColons: bluetoothMacAddress, deviceId: deviceId)
+        let reading = TempivoSensorBeaconDecoder.buildSensorBeaconReading(
+            cacheKeys: keys,
+            cache: frameCache,
+            serialNumber: serialNumber,
+            bluetoothMacAddress: bluetoothMacAddress
+        )
+
+        let discovery = SensorBeaconDiscovery(
+            deviceId: deviceId,
+            rssi: rssi.intValue,
+            serialNumber: serialNumber,
+            bluetoothMacAddress: bluetoothMacAddress,
+            reading: reading
+        )
+        delegate?.sensorBeaconScanner(self, didDiscover: discovery)
+    }
+}
+
+extension TempivoSensorBeaconScanner: CBCentralManagerDelegate {
+    public func centralManagerDidUpdateState(_ central: CBCentralManager) {
+        delegate?.sensorBeaconScanner(self, didUpdateState: central.state)
+        if central.state == .poweredOn {
+            beginScanningIfNeeded()
+        } else if central.state != .unknown {
+            pendingStart = false
+            isScanning = false
+        }
+    }
+
+    public func centralManager(
+        _ central: CBCentralManager,
+        didDiscover peripheral: CBPeripheral,
+        advertisementData: [String: Any],
+        rssi RSSI: NSNumber
+    ) {
+        handleDiscovery(peripheral: peripheral, advertisementData: advertisementData, rssi: RSSI)
+    }
+}

package/ios/Sources/TempivoSensorBeacon/TempivoSensorBeaconTypes.swift

@@ -0,0 +1,106 @@
+import Foundation
+
+/// Tempivo sensor manufacturer company identifier in BLE advertisement data (little-endian on the wire).
+public let TEMPVO_SENSOR_MANUFACTURER_ID: UInt16 = 0x026C
+
+/// One decoded measurement slot from scan response frame `0x04`.
+public struct SensorBeaconMeasurement: Codable, Sendable, Equatable {
+    public let typeHex: String
+    public let raw24: Int
+    public let text: String
+
+    public init(typeHex: String, raw24: Int, text: String) {
+        self.typeHex = typeHex
+        self.raw24 = raw24
+        self.text = text
+    }
+}
+
+/// Decoded telemetry from merged advertisement frames `0x03` and `0x04`.
+public struct SensorBeaconReading: Codable, Sendable, Equatable {
+    public let serialNumber: String?
+    public let bluetoothMacAddress: String?
+    public let firmware: String?
+    public let batteryOk: Bool?
+    public let encryptionEnabled: Bool?
+    public let cellularStatus: String?
+    public let measurementCounter: Int?
+    public let readingTimestampUnix: Int?
+    public let readingTimestampIso: String?
+    public let periodBaseSeconds: Int?
+    public let periodFactor: Int?
+    public let readings: [SensorBeaconMeasurement]
+    public let readingsCount: Int
+    public let summary: String
+
+    public init(
+        serialNumber: String? = nil,
+        bluetoothMacAddress: String? = nil,
+        firmware: String? = nil,
+        batteryOk: Bool? = nil,
+        encryptionEnabled: Bool? = nil,
+        cellularStatus: String? = nil,
+        measurementCounter: Int? = nil,
+        readingTimestampUnix: Int? = nil,
+        readingTimestampIso: String? = nil,
+        periodBaseSeconds: Int? = nil,
+        periodFactor: Int? = nil,
+        readings: [SensorBeaconMeasurement] = [],
+        readingsCount: Int = 0,
+        summary: String = ""
+    ) {
+        self.serialNumber = serialNumber
+        self.bluetoothMacAddress = bluetoothMacAddress
+        self.firmware = firmware
+        self.batteryOk = batteryOk
+        self.encryptionEnabled = encryptionEnabled
+        self.cellularStatus = cellularStatus
+        self.measurementCounter = measurementCounter
+        self.readingTimestampUnix = readingTimestampUnix
+        self.readingTimestampIso = readingTimestampIso
+        self.periodBaseSeconds = periodBaseSeconds
+        self.periodFactor = periodFactor
+        self.readings = readings
+        self.readingsCount = readingsCount
+        self.summary = summary
+    }
+}
+
+/// Latest raw `0x03` / `0x04` frames keyed by 12-hex serial or MAC.
+public struct SensorBeaconFrameCache: Sendable {
+    public var last03: [String: Data]
+    public var last04: [String: Data]
+
+    public init(last03: [String: Data] = [:], last04: [String: Data] = [:]) {
+        self.last03 = last03
+        self.last04 = last04
+    }
+
+    public mutating func clear() {
+        last03.removeAll(keepingCapacity: false)
+        last04.removeAll(keepingCapacity: false)
+    }
+}
+
+/// A sensor discovered during an active BLE scan (advertising only, no connection).
+public struct SensorBeaconDiscovery: Sendable, Equatable {
+    public let deviceId: String
+    public let rssi: Int
+    public let serialNumber: String?
+    public let bluetoothMacAddress: String?
+    public let reading: SensorBeaconReading?
+
+    public init(
+        deviceId: String,
+        rssi: Int,
+        serialNumber: String?,
+        bluetoothMacAddress: String?,
+        reading: SensorBeaconReading?
+    ) {
+        self.deviceId = deviceId
+        self.rssi = rssi
+        self.serialNumber = serialNumber
+        self.bluetoothMacAddress = bluetoothMacAddress
+        self.reading = reading
+    }
+}