/** * Turns a stream of Even advertisements into the things a pairing list shows: * G2 pairs (a left and a right temple that advertise the same serial) and R1 * rings, each ranked by how close it probably is. * * Ported from SybilSight's `PairingScanPresentation` / `PairingFlowState` * (nearest-device margin, previously-paired match, closest-first ordering) * and extended with the left↔right pair grouping that Faceclaw needs because * it connects to each arm by address rather than through a vendor SDK. * * This module is pure (no NativeScript imports) so it can run under node tests. */ import { estimateProximity, GLASSES_CALIBRATION, proximitySummary, RING_CALIBRATION, sortedByProximity, zoneGlyph, type ProximityEstimate, type ProximityZone, } from "./ble-proximity"; import { classifyAdvertisement, type EvenAdvertisement, type RawAdvertisement } from "./even-advertisement"; import { glassesImagePath, R1_IMAGE_PATH } from "./glasses-artwork"; import { colorwayDisplayName, colorwaySwatchHex, evaluatePairSerials, GlassesHardwareIdentity, pairSerialWarning, type GlassesColorway, } from "./glasses-hardware-identity"; export type PairCompleteness = "complete" | "left-only" | "right-only"; /** A G2 pair as seen over the air: up to one advertisement per side, joined on serial. */ export type GlassesPairCandidate = { /** Stable id: the serial when known, otherwise the lone arm's address. */ id: string; serial: string | null; identity: GlassesHardwareIdentity | null; left: EvenAdvertisement | null; right: EvenAdvertisement | null; completeness: PairCompleteness; /** Strongest smoothed signal across the arms that have one. */ rssi: number | null; txPower: number | null; proximity: ProximityEstimate | null; lastSeenMs: number; }; export type RingCandidate = { id: string; advertisement: EvenAdvertisement; rssi: number | null; proximity: ProximityEstimate | null; lastSeenMs: number; }; /** * Android delivers a callback per advertisement (several per second per arm), * far more often than CoreBluetooth's coalesced reports, so the raw RSSI * jitters visibly. A light exponential average keeps the list calm without * hiding a real move. Ordering still uses the smoothed value; the margin for * the "Closest" badge is applied on top. */ const RSSI_SMOOTHING = 0.35; /** * The device whose signal is strong enough to call "the one you are holding" * needs a clear margin over the runner-up: RSSI wanders by a few dB between * advertisements, so a badge awarded on a 1 dB lead would hop between rows * every scan pass and mean nothing. */ export const NEAREST_SIGNAL_MARGIN_DBM = 8; /** Advertisements older than this are dropped — the pair went back in its case or walked off. */ export const DEFAULT_STALE_AFTER_MS = 12_000; export class DiscoveryAggregator { private readonly byAddress = new Map(); private readonly rejectedNames = new Set(); /** Feed one raw advertisement. Returns the classified record, or null when ignored. */ ingest(raw: RawAdvertisement): EvenAdvertisement | null { const classified = classifyAdvertisement(raw); if (!classified) { if (raw.name) this.rejectedNames.add(raw.name); return null; } const previous = this.byAddress.get(classified.address); let smoothedRssi: number | null = classified.rssi; if (classified.rssi != null && previous?.smoothedRssi != null) { smoothedRssi = previous.smoothedRssi + RSSI_SMOOTHING * (classified.rssi - previous.smoothedRssi); } else if (classified.rssi == null && previous) { // A bonded-device entry carries no signal; keep what the scan told us. smoothedRssi = previous.smoothedRssi; } const merged: EvenAdvertisement & { smoothedRssi: number | null } = { ...classified, // A bonded listing never has a serial; do not let it erase a scanned one. serial: classified.serial ?? previous?.serial ?? null, embeddedMac: classified.embeddedMac ?? previous?.embeddedMac ?? null, manufacturerData: classified.manufacturerData || previous?.manufacturerData || "", bonded: classified.bonded || (previous?.bonded ?? false), rssi: classified.rssi ?? previous?.rssi ?? null, txPower: classified.txPower ?? previous?.txPower ?? null, seenAtMs: Math.max(classified.seenAtMs, previous?.seenAtMs ?? 0), smoothedRssi, }; this.byAddress.set(merged.address, merged); return merged; } /** Forget advertisements not refreshed within `maxAgeMs`. Bonded entries are kept. */ prune(nowMs: number, maxAgeMs: number = DEFAULT_STALE_AFTER_MS): void { for (const [address, record] of this.byAddress) { if (record.bonded) continue; if (nowMs - record.seenAtMs > maxAgeMs) this.byAddress.delete(address); } } clear(): void { this.byAddress.clear(); this.rejectedNames.clear(); } get size(): number { return this.byAddress.size; } /** Names of advertisements that looked like nothing we pair with — for the diagnostics log. */ get rejectedNameList(): string[] { return Array.from(this.rejectedNames).sort(); } advertisements(): EvenAdvertisement[] { return Array.from(this.byAddress.values()); } /** Every G2 pair seen, joined on serial, closest first. */ pairs(): GlassesPairCandidate[] { const groups = new Map(); for (const record of this.byAddress.values()) { if (record.role === "ring") continue; const key = record.serial ? `serial:${record.serial}` : `arm:${record.address}`; const group = groups.get(key) ?? { left: null, right: null }; const slot = record.role === "left" ? "left" : "right"; const incumbent = group[slot]; // Two arms of one side claiming the same serial is a replaced temple or a // stale row; keep the one heard most recently. if (!incumbent || incumbent.seenAtMs <= record.seenAtMs) group[slot] = record; groups.set(key, group); } const pairs: GlassesPairCandidate[] = []; for (const group of groups.values()) { const left = group.left; const right = group.right; const any = (left ?? right)!; const serial = any.serial; const samples = [left, right].filter((arm): arm is NonNullable => !!arm && arm.smoothedRssi != null); const strongest = samples.length ? samples.reduce((a, b) => (a.smoothedRssi! >= b.smoothedRssi! ? a : b)) : null; const rssi = strongest ? Math.round(strongest.smoothedRssi!) : null; const txPower = strongest?.txPower ?? left?.txPower ?? right?.txPower ?? null; pairs.push({ id: serial ?? `arm:${any.address}`, serial, identity: GlassesHardwareIdentity.decode(serial), left: left ? stripSmoothing(left) : null, right: right ? stripSmoothing(right) : null, completeness: left && right ? "complete" : left ? "left-only" : "right-only", rssi, txPower, proximity: estimateProximity(rssi, txPower, GLASSES_CALIBRATION), lastSeenMs: Math.max(left?.seenAtMs ?? 0, right?.seenAtMs ?? 0), }); } return sortedByProximity(pairs, (pair) => pair.proximity, (pair) => pair.id); } /** Every R1 ring seen, closest first. */ rings(): RingCandidate[] { const rings: RingCandidate[] = []; for (const record of this.byAddress.values()) { if (record.role !== "ring") continue; const rssi = record.smoothedRssi != null ? Math.round(record.smoothedRssi) : null; rings.push({ id: record.address, advertisement: stripSmoothing(record), rssi, proximity: estimateProximity(rssi, record.txPower, RING_CALIBRATION), lastSeenMs: record.seenAtMs, }); } return sortedByProximity(rings, (ring) => ring.proximity, (ring) => ring.id); } } function stripSmoothing(record: EvenAdvertisement & { smoothedRssi: number | null }): EvenAdvertisement { const { smoothedRssi: _ignored, ...rest } = record; return rest; } /** * The candidate whose signal is strong enough to call "the one you are * holding". `null` when nothing leads clearly, which is the honest answer for * two pairs sitting on the same table. */ export function nearestCandidateId(candidates: ReadonlyArray<{ id: string; rssi: number | null }>): string | null { const ranked = candidates .filter((candidate): candidate is { id: string; rssi: number } => candidate.rssi != null) .slice() // Stable order for equal signal so repeated polls nominate the same row. .sort((lhs, rhs) => (lhs.rssi === rhs.rssi ? (lhs.id < rhs.id ? -1 : 1) : rhs.rssi - lhs.rssi)); const best = ranked[0]; if (!best) return null; if (ranked.length === 1) return best.id; return best.rssi - ranked[1]!.rssi >= NEAREST_SIGNAL_MARGIN_DBM ? best.id : null; } /** * The saved pair identity is stored as the serial, but historical values may * carry the `_L_1` arm suffix, so compare on the decoded serial when both * sides decode and fall back to a containment check when they do not. */ export function isPreviouslyPaired(name: string | null | undefined, pairedSerial: string | null | undefined): boolean { if (!name || !pairedSerial) return false; const saved = pairedSerial.trim(); if (!saved) return false; const left = GlassesHardwareIdentity.decode(name); const right = GlassesHardwareIdentity.decode(saved); if (left && right) return left.serial === right.serial; const a = name.toLowerCase(); const b = saved.toLowerCase(); return a.includes(b) || b.includes(a); } // --------------------------------------------------------------------------- // Row presentation // --------------------------------------------------------------------------- export type PairingRowPresentation = { id: string; kind: "glasses" | "ring"; /** "Even G2 B" / "Even R1" / fallback product name. */ modelTitle: string; /** The serial (glasses) or local name (ring). */ deviceName: string; /** "Frame B · Brown", or null when the serial does not carry a variant we recognise. */ variantSummary: string | null; colorway: GlassesColorway | null; /** Hex colour for the swatch. Null suppresses it rather than guessing a finish. */ swatchHex: string | null; /** Product photo path for ``. Variant art when bundled, else the generic shot. */ imagePath: string; /** True only when the variant-specific photo is available (the swatch is redundant then). */ hasVariantImage: boolean; isNearest: boolean; isPreviouslyPaired: boolean; /** "Yours" / "Closest" / "". */ badge: string; proximitySummary: string; proximityGlyph: string; zone: ProximityZone | null; /** "Left + right arms found", "Only the left arm has been seen", … */ armsSummary: string; /** A problem the wearer should read before tapping, or "" when none. */ warning: string; /** Both arms present (or a ring), so tapping can save addresses. */ canSelect: boolean; leftAddress: string; rightAddress: string; ringAddress: string; }; export type RowContext = { /** Serial of the pair this phone paired with before, if any. */ pairedSerial?: string | null; /** From `nearestCandidateId` over the same list. */ nearestId?: string | null; /** Ring address saved before, if any. */ pairedRingAddress?: string | null; }; export function glassesRow(pair: GlassesPairCandidate, context: RowContext = {}): PairingRowPresentation { const identity = pair.identity; const imagePath = glassesImagePath(identity); const isPreviouslyPairedRow = isPreviouslyPaired(pair.serial, context.pairedSerial); const isNearest = !!context.nearestId && context.nearestId === pair.id; const warnings: string[] = []; const leftNote = pair.left?.note; const rightNote = pair.right?.note; if (leftNote) warnings.push(`Left arm: ${leftNote}.`); if (rightNote) warnings.push(`Right arm: ${rightNote}.`); if (pair.left?.embeddedMacMismatch) { warnings.push(`Left arm's advertised address ${pair.left.embeddedMac} differs from its radio address ${pair.left.address}.`); } if (pair.right?.embeddedMacMismatch) { warnings.push(`Right arm's advertised address ${pair.right.embeddedMac} differs from its radio address ${pair.right.address}.`); } const verdict = evaluatePairSerials(pair.left?.serial, pair.right?.serial); const mismatch = pairSerialWarning(verdict); if (mismatch) warnings.push(mismatch); let armsSummary: string; switch (pair.completeness) { case "complete": armsSummary = verdict.kind === "matched" ? "Left + right arms found · serials match" : "Left + right arms found"; break; case "left-only": armsSummary = "Only the left arm has been seen — waiting for the right"; break; case "right-only": armsSummary = "Only the right arm has been seen — waiting for the left"; break; } if (!pair.serial) armsSummary += " · serial unknown, cannot match arms"; return { id: pair.id, kind: "glasses", modelTitle: identity?.productName ?? "Even Realities G2", deviceName: pair.serial ?? (pair.left ?? pair.right)!.name, variantSummary: identity?.variantSummary ?? null, colorway: identity?.colorway ?? null, swatchHex: identity?.colorway ? colorwaySwatchHex(identity.colorway) : null, imagePath, hasVariantImage: !!identity?.imageAssetName, isNearest, isPreviouslyPaired: isPreviouslyPairedRow, badge: isPreviouslyPairedRow ? "Yours" : isNearest ? "Closest" : "", proximitySummary: pair.proximity ? proximitySummary(pair.proximity) : "Signal unknown", proximityGlyph: pair.proximity ? zoneGlyph(pair.proximity.zone) : "○○○○", zone: pair.proximity?.zone ?? null, armsSummary, warning: warnings.join(" "), canSelect: pair.completeness === "complete" && verdict.kind !== "mismatched", leftAddress: pair.left?.address ?? "", rightAddress: pair.right?.address ?? "", ringAddress: "", }; } export function ringRow(ring: RingCandidate, context: RowContext = {}): PairingRowPresentation { const ad = ring.advertisement; const isPaired = !!context.pairedRingAddress && context.pairedRingAddress.toUpperCase() === ad.address; const isNearest = !!context.nearestId && context.nearestId === ring.id; const warnings: string[] = []; if (ad.note) warnings.push(`${ad.note}.`); if (ad.embeddedMacMismatch) { warnings.push(`The ring's advertised address ${ad.embeddedMac} differs from its radio address ${ad.address}.`); } return { id: ring.id, kind: "ring", modelTitle: "Even R1", deviceName: ad.ringSerialSuffix ? `${ad.name} · serial …${ad.ringSerialSuffix}` : ad.name, variantSummary: null, colorway: null, swatchHex: null, imagePath: R1_IMAGE_PATH, hasVariantImage: true, isNearest, isPreviouslyPaired: isPaired, badge: isPaired ? "Yours" : isNearest ? "Closest" : "", proximitySummary: ring.proximity ? proximitySummary(ring.proximity) : "Signal unknown", proximityGlyph: ring.proximity ? zoneGlyph(ring.proximity.zone) : "○○○○", zone: ring.proximity?.zone ?? null, armsSummary: ad.bonded ? "Paired with this phone" : "Advertising", warning: warnings.join(" "), canSelect: true, leftAddress: "", rightAddress: "", ringAddress: ad.address, }; } /** Convenience: a colourway's display text, for rows that show the swatch alone. */ export function colorwayLabel(colorway: GlassesColorway | null): string { return colorway ? colorwayDisplayName(colorway) : ""; }