Files
faceclaw/app/g2/ble-proximity.ts
T
James BabcockandClaude Fable 5 17182532f4 Address review findings for the proximity-pairing PR
Correctness:
- Pair-glasses flows no longer strand the app in the manual-disconnected
  state: the pre-scan disconnect is followed by resumeAutoReconnect(), and
  the config page's scan hand-off drops the live link too.
- The mixed-arms serial warning is reachable now: pairs() groups by the
  canonical serial key, and a lone left + lone right with different serials
  get the mismatch warning on both rows (it previously required two
  different serials inside one serial-keyed group, which cannot happen).
- A selected pair that degrades to one arm (prune while the page is open)
  is deselected, and Save never pads a missing arm from stored addresses.
- DiscoveryAggregator.ingest no longer lets a bonded re-emit or split
  advertisement overwrite the note/name/flag learned from a full
  advertisement, and reclassifies split reports using remembered fields so
  a nameless half doesn't drop the arm.
- estimateProximity ignores the advertised TX Power Level (radiated power,
  not measured-power-at-1m); the calibration table is the only reference.
- Saving a ring without a glasses pair updates the stored identity's ring
  name/address instead of leaving the previous ring on record.
- Ring detection requires the stock "EVEN R1" name prefix in both the TS
  classifier and the Java pre-filter; a bare "R1" substring matched
  unrelated devices, and ring rows are always selectable.
- One-shot scans keep every sample (buildAddressSet merges them through
  DiscoveryAggregator), and flash-flow address resolution takes left/right
  from one serial-joined complete pair instead of latest-per-role.

Lifecycle:
- The pairing scan and its refresh timer pause on app suspend and resume
  with the app, and the model's app-event hooks are detached when the page
  is left for good.

Cleanup:
- One MAC normalizer (even-advertisement.normalizeMacAddress, re-exported
  by device-addresses), used for the ring "Yours" comparison too.
- One serial-equality definition (serialKey/serialsMatch); the containment
  fallback in isPreviouslyPaired is gone.
- Shared formatErrorMessage replaces five per-view-model copies; shared
  hex-util replaces the duplicate TS hex codecs; one Java bytesToHex in
  FaceclawFirmwareUtil replaces three hand-rolled encoders.
- glassesRow/ringRow share a presentation-base helper; dead row address
  fields, the constant glassesSectionVisibility, the identical-branch
  status ternary, and zoneRank/ZONE_ORDER are removed.
- .gitignore now actually covers .test-build/ as tests/README claims.

UI:
- Dark-mode styles for the pairing page: readable instructions, dark-gray
  cards with consistent light text; light mode keeps its current look.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZqzwmRQ3HQxasBz5rYyZV
2026-08-23 15:28:59 -07:00

197 lines
6.9 KiB
TypeScript

/**
* How far away an advertising device probably is, from its signal strength.
*
* Ported from SybilSight's `BLEProximity.swift` (itself from ProLink's
* `PeripheralInfo.basicEstimatedDistance`), with the calibration table
* narrowed to the two products this app pairs.
*
* ## The model
*
* The log-distance path loss model:
*
* RSSI = txPower - 10 · n · log₁₀(d) ⇒ d = 10 ^ ((txPower - RSSI) / (10 · n))
*
* `txPower` is the expected signal at one metre and `n` the path loss
* exponent — 2.0 in free space, higher indoors where walls and bodies absorb.
* The reference power always comes from the per-product calibration table. An
* advertised BLE "TX Power Level" is deliberately NOT used: that field is the
* radiated power at the antenna (typically 0…+4 dBm), not an iBeacon-style
* measured power at one metre, and reading it as the latter inflates every
* distance by orders of magnitude.
*
* ## What this is for, and what it is not
*
* It exists so a pairing list can be ordered by "which of these is in my
* hand", and so a row can say roughly how far away its device is. That is a
* ranking problem, and RSSI ordering is far more trustworthy than RSSI
* magnitude — the ordering survives calibration error that would put the
* absolute numbers metres out.
*
* It is **not** a measurement. A hand over the temple, a pocket, or a body
* between phone and glasses moves the estimate by metres. Every user-facing
* number is therefore rounded hard, prefixed with "~" when confidence is low,
* and paired with a coarse zone rather than being presented as a distance the
* wearer could act on precisely.
*
* This module is pure (no NativeScript imports) so it can run under node tests.
*/
import { clamp } from "../util/numeric-util";
/** Expected RSSI at one metre, and the path loss exponent, per product. */
export type ProximityCalibration = {
readonly txPowerAtOneMeter: number;
readonly pathLossExponent: number;
};
/**
* Even Realities G2. Two temple radios on a head, usually held or worn
* indoors, so the exponent sits above free space. Verified only as a ranking
* input — see the module note.
*/
export const GLASSES_CALIBRATION: ProximityCalibration = { txPowerAtOneMeter: -62, pathLossExponent: 2.2 };
/**
* Even Realities R1. A ring antenna is smaller and more easily shadowed by a
* hand, so it reads weaker at the same distance than the glasses do.
*/
export const RING_CALIBRATION: ProximityCalibration = { txPowerAtOneMeter: -68, pathLossExponent: 2.3 };
/**
* Estimates below this are indistinguishable from "touching the phone", and
* above it from "somewhere else entirely". Clamping keeps a noisy sample from
* rendering as 0.001 m.
*/
export const MINIMUM_METERS = 0.1;
export const MAXIMUM_METERS = 100;
/**
* Coarse buckets. The wearer is being asked "is this the pair in your hand?",
* and a bucket answers that better than a number they might over-trust.
*/
export type ProximityZone = "immediate" | "near" | "far" | "distant";
export function zoneFromMeters(meters: number): ProximityZone {
if (meters < 0.5) return "immediate";
if (meters < 3) return "near";
if (meters < 10) return "far";
return "distant";
}
export function zoneLabel(zone: ProximityZone): string {
switch (zone) {
case "immediate":
return "In your hand";
case "near":
return "Nearby";
case "far":
return "Across the room";
case "distant":
return "Far away";
}
}
/** A glyph for the zone; SF Symbols have no Android equivalent, so plain text. */
export function zoneGlyph(zone: ProximityZone): string {
switch (zone) {
case "immediate":
return "●●●●";
case "near":
return "●●●○";
case "far":
return "●●○○";
case "distant":
return "●○○○";
}
}
/** A distance estimate and how much to trust it. */
export type ProximityEstimate = {
readonly meters: number;
/** 0…1. Drops with weak signal. */
readonly confidence: number;
readonly zone: ProximityZone;
};
/** "0.4 m", "~3 m". The tilde marks an estimate the reader should not lean on. */
export function formatDistance(estimate: ProximityEstimate): string {
const prefix = estimate.confidence < 0.6 ? "~" : "";
const meters = estimate.meters;
if (meters < 1) {
return `${prefix}${Math.round(meters * 100)} cm`;
}
if (meters < 10) {
return `${prefix}${meters.toFixed(1)} m`;
}
if (meters < MAXIMUM_METERS) {
return `${prefix}${Math.round(meters)} m`;
}
return `${prefix}>${MAXIMUM_METERS} m`;
}
/** "In your hand · 0.3 m" — zone first, because the zone is the trustworthy half. */
export function proximitySummary(estimate: ProximityEstimate): string {
return `${zoneLabel(estimate.zone)} · ${formatDistance(estimate)}`;
}
/**
* Estimate distance from a signal sample. Null when there is no RSSI to work
* from, so callers can say "signal unknown" rather than render a fabricated
* distance. 127 is the Bluetooth "RSSI unavailable" sentinel.
*/
export function estimateProximity(rssi: number | null | undefined, calibration: ProximityCalibration): ProximityEstimate | null {
if (rssi == null || !Number.isFinite(rssi) || rssi === 127) return null;
const ratio = (calibration.txPowerAtOneMeter - rssi) / (10 * calibration.pathLossExponent);
const meters = clamp(Math.pow(10, ratio), MINIMUM_METERS, MAXIMUM_METERS);
return {
meters,
confidence: proximityConfidence(rssi),
zone: zoneFromMeters(meters),
};
}
/**
* Confidence falls with signal strength, because a weak sample is a noisy one.
* The 0.85 ceiling reflects that the TX power is always an assumption from the
* calibration table, never a measurement.
*/
export function proximityConfidence(rssi: number): number {
let confidence = 0.85;
if (rssi < -85) confidence *= 0.4;
else if (rssi < -75) confidence *= 0.7;
else if (rssi < -65) confidence *= 0.85;
return confidence;
}
/**
* Order a list closest-first.
*
* Items whose signal never arrived sort last rather than being dropped: a pair
* that cannot be ranked is still a pair the wearer may need to choose, and
* hiding it would be worse than showing it at the bottom. Ties break on the
* stable id so the list does not reshuffle between scan passes — a list that
* reorders under the finger is how the wrong device gets tapped, which is the
* whole failure this ordering exists to prevent.
*/
export function sortedByProximity<T>(
items: readonly T[],
estimate: (item: T) => ProximityEstimate | null,
id: (item: T) => string,
): T[] {
return items.slice().sort((lhs, rhs) => {
const left = estimate(lhs);
const right = estimate(rhs);
if (left && right) {
if (left.meters !== right.meters) return left.meters < right.meters ? -1 : 1;
return compareIds(id(lhs), id(rhs));
}
if (left && !right) return -1;
if (!left && right) return 1;
return compareIds(id(lhs), id(rhs));
});
}
function compareIds(a: string, b: string): number {
return a < b ? -1 : a > b ? 1 : 0;
}