forked from Blendman974/faceclaw
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
197 lines
6.9 KiB
TypeScript
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;
|
|
}
|