Compass has higher sample rate, and distinguishes map north from true north

This commit is contained in:
James Babcock committed 2026-09-01 14:37:09 -07:00
1 parent eb8a863222
commit a72e29a04f
13 files changed
+429 -55

No files matched your search

@@ -43,6 +43,8 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
private static final long FACECLAW_WAKE_LEASE_RENEW_MS = 45_000;
private static final long FACECLAW_WAKE_CONTROL_WAIT_MS = 1_500;
private static final long CFW_CLEANUP_WAIT_MS = 4_000;
private static final int COMPASS_REPORT_INTERVAL_MS = 250;
private static final int COMPASS_MIN_CHANGE_DEGREES = 1;
private final Context appContext;
private final PowerManager powerManager;
@@ -2339,10 +2341,22 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
logLine("queue firmware debug flags " + (show ? "show" : "hide"));
}
/** Send CFW image-handler mode 10: [10][1] start, [10][0] stop. */
/**
* Send CFW image-handler mode 10. Enable uses the configurable form
* [10][2][interval-ms LE16][minimum-change-degrees LE16]; disable remains [10][0].
*/
private void enqueueCompassControlLocked(boolean priority, boolean enable) {
int sentState = enable ? 1 : 0;
byte[] payload = new byte[] { (byte) 10, (byte) sentState };
byte[] payload = enable
? new byte[] {
(byte) 10,
(byte) 2,
(byte) (COMPASS_REPORT_INTERVAL_MS & 0xff),
(byte) ((COMPASS_REPORT_INTERVAL_MS >> 8) & 0xff),
(byte) (COMPASS_MIN_CHANGE_DEGREES & 0xff),
(byte) ((COMPASS_MIN_CHANGE_DEGREES >> 8) & 0xff),
}
: new byte[] { (byte) 10, (byte) 0 };
OutboundMessage message = messageBuilder.imagePayload(
"compass-control",
DASHBOARD_TILE,
+6
View File
@@ -2,6 +2,12 @@
## 0.6.4 - Future
* Context menus are centered and include window title
* Developer speed metrics include bytes/frame
Compass app:
* Increase sample rate and minimum-change for the compass app
* Compass now handles the distincitn between true north and magnetic north
* EvenHub compass readings now include calibrated magnetic, declination and true headings
## 0.6.3 - 2026-09-01
* Update custom firmware base version from 2.2.6 to 2.2.9
+31 -17
View File
@@ -1,7 +1,11 @@
/**
* The compass calibration screen: a crosshair the wearer aims at a landmark
* of known heading, plus raw/offset/calibrated readouts. Swipe adjusts the
* offset by 1°, double-tap returns to the compass.
* of known heading, plus raw/offset/declination/calibrated readouts. Swipe
* adjusts the offset by 1°, double-tap returns to the compass.
*
* The landmark's heading must be in the frame the compass is showing: aiming
* at a true heading in true mode leaves the wearer-fit offset free of
* declination, which is what lets the calibration survive travel.
*/
import { GrayImage } from "../../graphics/image";
import { getDefaultMediumFont, getDefaultSmallFont } from "../../graphics/ui-fonts";
@@ -10,18 +14,16 @@ import { type InputEvent } from "../../ui/gestures";
import { type Layer, type LayerContext } from "../../ui/layers";
import { lineStep } from "../../ui/metrics";
import { screenCenterInViewportX } from "../../ui/shell/geometry";
import {
formatOffset,
getCompassOffset,
markCompassCalibrated,
normalizeHeading,
setCompassOffset,
} from "./calibration";
import { formatOffset, getCompassOffset, markCompassCalibrated, setCompassOffset } from "./calibration";
import { resolveHeading, type NorthReference } from "./heading";
const INSTRUCTIONS =
const INSTRUCTIONS_PREAMBLE =
"This compass uses the magnetometer in the right arm of the glasses; depending how it rests on your head, "
+ "it may be slightly off. To calibrate, look at a distant object or down a street where you know the true "
+ "compass heading, then adjust the calibration offset below";
+ "it may be slightly off. To calibrate, look at a distant object or down a street where you know the ";
const INSTRUCTIONS_BY_FRAME: Record<NorthReference, string> = {
true: "true compass heading (as shown on a map), then adjust the calibration offset below",
magnetic: "magnetic compass heading (as read by another compass), then adjust the calibration offset below",
};
/** Margins around the instruction paragraph. */
const TEXT_PADDING_X = 16;
@@ -40,7 +42,12 @@ export class CompassCalibrationLayer implements Layer {
const medium = getDefaultMediumFont();
const smallStep = lineStep(small);
const lines = wrapText(small, INSTRUCTIONS, width - TEXT_PADDING_X * 2);
const raw = this.getRawHeading();
const resolved = raw === null ? null : resolveHeading(raw);
// Before the first reading there is no frame to name yet; the true-mode
// wording is the default and the readout will correct it once data arrives.
const frame = resolved?.frame ?? "true";
const lines = wrapText(small, INSTRUCTIONS_PREAMBLE + INSTRUCTIONS_BY_FRAME[frame], width - TEXT_PADDING_X * 2);
for (let i = 0; i < lines.length; i++) {
image.drawText(small, TEXT_PADDING_X, TEXT_PADDING_TOP + i * smallStep, lines[i]!, 190);
}
@@ -49,13 +56,20 @@ export class CompassCalibrationLayer implements Layer {
// Readouts along the bottom: dim label over a bright value, in thirds.
const valueTop = height - medium.lineHeight;
const labelTop = valueTop - small.lineHeight;
const raw = this.getRawHeading();
const offset = getCompassOffset();
const columns: Array<[string, string]> = [
["Raw", raw === null ? "--°" : `${Math.round(raw)}°`],
["Offset", formatOffset(offset)],
["Calibrated", raw === null ? "--°" : `${Math.round(normalizeHeading(raw + offset))}°`],
["Offset", formatOffset(getCompassOffset())],
];
// Declination is only part of the sum in true mode, so only show it then;
// in magnetic mode it would be a number that changes nothing on screen.
if (frame === "true") {
const declination = resolved?.declinationDegrees ?? null;
columns.push(["Declination", declination === null ? "--°" : formatOffset(Math.round(declination))]);
}
columns.push([
frame === "true" ? "True" : "Magnetic",
resolved === null ? "--°" : `${Math.round(resolved.displayDegrees)}°`,
]);
const columnWidth = width / columns.length;
for (let i = 0; i < columns.length; i++) {
const [label, value] = columns[i]!;
+71 -4
View File
@@ -20,8 +20,11 @@ import {
type InProcessWindow,
} from "../../ui/shell/in-process-window";
import { shell } from "../../ui/shell/shell";
import { calibrateHeading, isCompassCalibrated, normalizeHeading } from "./calibration";
import { ensureLocationPermission, hasLocationPermission } from "../../g2/android-permissions";
import { isCompassCalibrated, normalizeHeading } from "./calibration";
import { CompassCalibrationLayer } from "./calibration-layer";
import { getDeclinationAvailability, onDeclinationChanged, refreshDeclination } from "./declination";
import { getNorthReference, resolveHeading, setNorthReference, type NorthReference } from "./heading";
export const COMPASS_WINDOW_ID = "compass";
export const COMPASS_SURFACE_ID = "window:compass";
@@ -98,13 +101,43 @@ class CompassLayer implements Layer {
private removed = false;
private timer: ReturnType<typeof setInterval> | null = null;
private unsubscribe: (() => void) | null = null;
private unsubscribeDeclination: (() => void) | null = null;
private requestingPermission = false;
constructor(private readonly requestRender: () => void) {}
start(): void {
this.unsubscribe = addCompassListener((event) => this.onCompassEvent(event));
this.unsubscribeDeclination = onDeclinationChanged(() => this.requestRender());
this.timer = setInterval(() => this.reconcile(), RECONCILE_INTERVAL_MS);
this.reconcile();
this.ensureDeclination();
}
/**
* True north needs the phone's location. Ask for it the way Weather does,
* on opening, but only while the wearer actually wants true north: a
* magnetic-mode compass has no business raising a permission prompt.
*/
private ensureDeclination(): void {
if (getNorthReference() !== "true") return;
if (hasLocationPermission()) {
refreshDeclination();
return;
}
if (this.requestingPermission) return;
this.requestingPermission = true;
void ensureLocationPermission().then((granted) => {
this.requestingPermission = false;
if (granted) refreshDeclination();
this.requestRender();
});
}
toggleNorthReference(): void {
setNorthReference(getNorthReference() === "true" ? "magnetic" : "true");
this.ensureDeclination();
this.requestRender();
}
stop(): void {
@@ -114,6 +147,8 @@ class CompassLayer implements Layer {
this.timer = null;
this.unsubscribe?.();
this.unsubscribe = null;
this.unsubscribeDeclination?.();
this.unsubscribeDeclination = null;
if (this.enabled) setCompassEnabled(false);
this.enabled = false;
}
@@ -134,6 +169,8 @@ class CompassLayer implements Layer {
this.enabled = visible;
setCompassEnabled(visible);
this.firmwareStatus = null;
// The stored fix may have aged out while the compass was hidden.
if (visible && hasLocationPermission()) refreshDeclination();
this.requestRender();
}
@@ -154,7 +191,8 @@ class CompassLayer implements Layer {
if (this.firmwareStatus !== null) return this.firmwareStatus;
if (!this.enabled) return "Compass paused";
if (this.rawHeading === null) return "Waiting for compass data…";
return isCompassCalibrated() ? "Magnetic heading" : "Uncalibrated - Tap to calibrate";
if (!isCompassCalibrated()) return "Uncalibrated - Tap to calibrate";
return frameStatusText();
}
paint(ctx: LayerContext): GrayImage {
@@ -162,7 +200,7 @@ class CompassLayer implements Layer {
const image = new GrayImage(width, height, 0);
const small = getDefaultSmallFont();
const large = getDefaultLargeFont();
const heading = this.rawHeading === null ? null : calibrateHeading(this.rawHeading);
const heading = this.rawHeading === null ? null : resolveHeading(this.rawHeading).displayDegrees;
const headingText = heading === null ? "--°" : `${Math.round(heading)}° ${cardinalDirection(heading)}`;
const statusLines = wrapText(small, this.statusText(), width - STACK_GAP * 2);
const smallStep = lineStep(small);
@@ -231,6 +269,14 @@ export function createCompassAppWindow(options: InProcessAppOptions): InProcessW
layer.openCalibration(ctx);
},
},
{
label: `North: ${northReferenceName(getNorthReference())}`,
description: "True north is what maps use. Magnetic north matches a handheld compass; it needs no location.",
onSelect: (ctx) => {
ctx.stack.pop();
layer.toggleNorthReference();
},
},
],
baseLayer: new YieldAtRootLayer(layer),
submitFrame: options.submitFrame,
@@ -246,6 +292,27 @@ export function createCompassAppWindow(options: InProcessAppOptions): InProcessW
return app;
}
export function northReferenceName(reference: NorthReference): string {
return reference === "true" ? "True" : "Magnetic";
}
/**
* Name the frame the readout is in. When the wearer wants true north but the
* phone can't supply declination, say that the reading is magnetic and why,
* rather than quietly showing a magnetic heading under a "true" label.
*/
function frameStatusText(): string {
if (getNorthReference() === "magnetic") return "Magnetic heading";
switch (getDeclinationAvailability()) {
case "available":
return "True heading";
case "no-permission":
return "Magnetic heading - location permission needed for true north";
case "no-fix":
return "Magnetic heading - waiting for location";
}
}
function cardinalDirection(heading: number): string {
const names = ["N", "NE", "E", "SE", "S", "SW", "W", "NW"];
return names[Math.round(normalizeHeading(heading) / 45) % names.length]!;
@@ -272,7 +339,7 @@ function projectRose(cx: number, cy: number, scale: number, radius: number, angl
};
}
/** Draw the tilted rose, with its brightest point aimed at magnetic north. */
/** Draw the tilted rose, with its brightest point aimed at north. */
function drawCompassRose(image: GrayImage, cx: number, cy: number, radius: number, heading: number | null): void {
// Without a reading there is nothing to aim, so show the rose in its resting
// orientation, dimmed, rather than an empty ring.
+97
View File
@@ -0,0 +1,97 @@
/**
* Local magnetic declination for the compass, so the app can show true north.
*
* Declination only varies over tens of kilometres, so the location it needs is
* whatever the phone can cheaply produce: the same one-shot coarse lookup the
* Weather app uses, refreshed no more than daily. The last fix is persisted so
* a fresh start has a usable declination before location comes back, and the
* model is re-evaluated at the current time when it does.
*/
import { hasLocationPermission } from "../../g2/android-permissions";
import { magneticDeclinationDegrees } from "../../native/geomagnetic";
import { getCurrentLocation } from "../../native/location";
import { getStringSetting, setStringSetting } from "../../native/settings-store";
const LATITUDE_KEY = "compass.declination.latitude";
const LONGITUDE_KEY = "compass.declination.longitude";
const LOCATED_AT_KEY = "compass.declination.locatedAtMs";
/** A stored fix older than this is refreshed when the compass next runs. */
const FIX_MAX_AGE_MS = 24 * 60 * 60 * 1000;
/** Back-off between failed location attempts, so a denied or dark phone isn't polled. */
const RETRY_INTERVAL_MS = 10 * 60 * 1000;
export type DeclinationAvailability = "available" | "no-permission" | "no-fix";
type StoredFix = { latitude: number; longitude: number; locatedAtMs: number };
let declination: number | null = null;
let fix: StoredFix | null = null;
let loaded = false;
let refreshing = false;
let lastAttemptMs = 0;
const listeners = new Set<() => void>();
function loadStoredFix(): void {
if (loaded) return;
loaded = true;
const latitude = parseFloat(getStringSetting(LATITUDE_KEY, ""));
const longitude = parseFloat(getStringSetting(LONGITUDE_KEY, ""));
const locatedAtMs = parseInt(getStringSetting(LOCATED_AT_KEY, ""), 10);
if (Number.isFinite(latitude) && Number.isFinite(longitude) && Number.isFinite(locatedAtMs)) {
fix = { latitude, longitude, locatedAtMs };
declination = magneticDeclinationDegrees(latitude, longitude);
}
}
/** Declination in degrees (east positive), or null when no location is known. */
export function getDeclinationDegrees(): number | null {
loadStoredFix();
return declination;
}
/** Why declination is or isn't available, for the compass status line. */
export function getDeclinationAvailability(): DeclinationAvailability {
if (getDeclinationDegrees() !== null) return "available";
return hasLocationPermission() ? "no-fix" : "no-permission";
}
export function onDeclinationChanged(listener: () => void): () => void {
listeners.add(listener);
return () => {
listeners.delete(listener);
};
}
/**
* Fetch a location and recompute declination if the stored fix is stale or
* missing. Safe to call on every compass start; it is a no-op while a lookup
* is in flight, while the fix is fresh, or shortly after a failed attempt.
* Never prompts for permission: callers that want to ask do that themselves.
*/
export function refreshDeclination(): void {
loadStoredFix();
if (refreshing || !hasLocationPermission()) return;
const now = Date.now();
if (fix !== null && now - fix.locatedAtMs < FIX_MAX_AGE_MS) return;
if (now - lastAttemptMs < RETRY_INTERVAL_MS) return;
lastAttemptMs = now;
refreshing = true;
getCurrentLocation()
.then((location) => {
const value = magneticDeclinationDegrees(location.latitude, location.longitude);
if (value === null) return;
fix = { latitude: location.latitude, longitude: location.longitude, locatedAtMs: now };
declination = value;
setStringSetting(LATITUDE_KEY, String(location.latitude));
setStringSetting(LONGITUDE_KEY, String(location.longitude));
setStringSetting(LOCATED_AT_KEY, String(now));
for (const listener of listeners) listener();
})
.catch((error) => {
console.warn(`Compass declination location lookup failed: ${error}`);
})
.finally(() => {
refreshing = false;
});
}
+54
View File
@@ -0,0 +1,54 @@
/**
* The compass heading model: raw magnetometer reading → wearer-calibrated
* magnetic heading → true heading, and which of the last two the wearer has
* asked to see.
*
* The wearer-fit offset and declination are kept as separate terms on purpose.
* The offset changes when the glasses are re-seated but not when the wearer
* travels; declination is the reverse. One combined hand-tuned number would go
* quietly wrong after a long trip.
*/
import { getStringSetting, setStringSetting } from "../../native/settings-store";
import { calibrateHeading, normalizeHeading } from "./calibration";
import { getDeclinationDegrees } from "./declination";
const NORTH_REFERENCE_KEY = "compass.northReference";
/** Which north the compass reads relative to. True is the default: it is what maps use. */
export type NorthReference = "true" | "magnetic";
export type ResolvedHeading = {
/** Raw reading corrected by the wearer-fit offset. */
magneticDegrees: number;
/** Local declination (east positive), or null when no location is known. */
declinationDegrees: number | null;
/** Magnetic heading plus declination, or null when declination is unknown. */
trueDegrees: number | null;
/** The heading to show, in whichever frame `frame` names. */
displayDegrees: number;
/** The frame actually shown: true if requested and available, else magnetic. */
frame: NorthReference;
};
export function getNorthReference(): NorthReference {
return getStringSetting(NORTH_REFERENCE_KEY, "true") === "magnetic" ? "magnetic" : "true";
}
export function setNorthReference(reference: NorthReference): void {
setStringSetting(NORTH_REFERENCE_KEY, reference);
}
export function resolveHeading(rawDegrees: number): ResolvedHeading {
const magneticDegrees = calibrateHeading(rawDegrees);
const declinationDegrees = getDeclinationDegrees();
const trueDegrees = declinationDegrees === null ? null : normalizeHeading(magneticDegrees + declinationDegrees);
const wantTrue = getNorthReference() === "true";
const frame: NorthReference = wantTrue && trueDegrees !== null ? "true" : "magnetic";
return {
magneticDegrees,
declinationDegrees,
trueDegrees,
displayDegrees: frame === "true" ? trueDegrees! : magneticDegrees,
frame,
};
}
+36 -5
View File
@@ -3,18 +3,46 @@
* running EvenHub apps, mirroring the IMU router. Only the foreground app
* receives headings, so a backgrounded app can't keep the sensor running.
*
* The compass is NOT pre-calibrated — the magnetometer is in the right arm,
* which rests on the head with a wearer-dependent curl (see compass-app memory);
* headings are relative, not true north.
* The raw reading is NOT pre-calibrated — the magnetometer is in the right
* arm, which rests on the head with a wearer-dependent curl (see compass-app
* memory). Each delivery also carries the Compass app's wearer-calibrated
* magnetic heading and, when the phone has a location, declination and the
* true heading, so apps needn't redo that work.
*/
import { addCompassListener, setCompassEnabled, COMPASS_CHANGED, type CompassEvent } from "../../native/compass";
import { isCompassCalibrated } from "../compass/calibration";
import { refreshDeclination } from "../compass/declination";
import { resolveHeading } from "../compass/heading";
/** Wire shape of the `compass` extension event (faceclaw-extensions `CompassReading`). */
export type EvenHubCompassReading = {
headingDegrees: number;
magneticHeadingDegrees: number;
wearerCalibrated: boolean;
declinationDegrees?: number;
trueHeadingDegrees?: number;
};
export type EvenHubCompassClient = {
readonly windowId: string;
isForeground(): boolean;
deliverCompass(headingDegrees: number): void;
deliverCompass(reading: EvenHubCompassReading): void;
};
export function buildCompassReading(rawDegrees: number): EvenHubCompassReading {
const resolved = resolveHeading(rawDegrees);
const reading: EvenHubCompassReading = {
headingDegrees: rawDegrees,
magneticHeadingDegrees: resolved.magneticDegrees,
wearerCalibrated: isCompassCalibrated(),
};
if (resolved.declinationDegrees !== null && resolved.trueDegrees !== null) {
reading.declinationDegrees = resolved.declinationDegrees;
reading.trueHeadingDegrees = resolved.trueDegrees;
}
return reading;
}
class EvenHubCompassRouter {
private readonly requesting = new Set<EvenHubCompassClient>();
private active: EvenHubCompassClient | null = null;
@@ -47,13 +75,16 @@ class EvenHubCompassRouter {
this.unsubscribe = addCompassListener((event: CompassEvent) => {
// Only heading updates carry a real heading; calibration events use -1.
if (event.command === COMPASS_CHANGED && event.headingDegrees >= 0) {
this.active?.deliverCompass(event.headingDegrees);
this.active?.deliverCompass(buildCompassReading(event.headingDegrees));
}
});
}
if (!this.enabled) {
setCompassEnabled(true);
this.enabled = true;
// Uses location only if the wearer already granted it; an app turning
// on the compass is not a reason to raise a system permission prompt.
refreshDeclination();
}
} else {
if (this.enabled) {
+3 -3
View File
@@ -56,7 +56,7 @@ import { type EvenHubManifest } from "./ehpk";
import { permissionsIncludeMicrophone, permissionsInclude } from "./permissions";
import { evenHubMicRouter, type EvenHubMicClient } from "./mic-router";
import { evenHubImuRouter, type EvenHubImuClient } from "./imu-router";
import { evenHubCompassRouter, type EvenHubCompassClient } from "./compass-router";
import { evenHubCompassRouter, type EvenHubCompassClient, type EvenHubCompassReading } from "./compass-router";
import { type ImuReading } from "../../native/imu";
import { toolRegistry, type ToolResult, type ToolSpec } from "../../assistant/tool-registry";
import { getCurrentLocation } from "../../native/location";
@@ -1010,8 +1010,8 @@ export class EvenHubSession implements EvenHubMicClient, EvenHubImuClient, EvenH
// ----- compass (EvenHubCompassClient) -----
deliverCompass(headingDegrees: number): void {
this.pushExtEvent("compass", { headingDegrees });
deliverCompass(reading: EvenHubCompassReading): void {
this.pushExtEvent("compass", reading);
}
private setCompass(enable: boolean): void {
+8 -8
View File
@@ -19,7 +19,7 @@ export type FirmwarePatchSet = {
export const CFW_PATCH_SET: FirmwarePatchSet = {
"base": "g2_2.2.9.22.bin",
"baseSha256": "a03fbea9f68a9de6bc271daabb9f3a41c59053d1086622c76a4e990f829cc561",
"outputSha256": "ceeede999529505ebc0a1369f57ab3c941273379a90b16669ccd39cc6bd99135",
"outputSha256": "e70cfcad3b244a27d370b32377d846b4b46776d3da6bd42640617139b5cde83f",
"patches": [
{
"offset": 1124178,
@@ -144,43 +144,43 @@ export const CFW_PATCH_SET: FirmwarePatchSet = {
{
"offset": 4476518,
"old": "",
"new": "02fb01f000e000bfb0b54ff2ac44c2f229040146206846f23f52c5f28802b2eb500f40f258304cf2e9124cf67e25c2f20000c0f24802caf2101518bf25609047002804bf691c2160b0bd00bf0846ffe7014640f258304cf20732c2f20000c0f24802104770b500284ed001684ef66862ccf2ff02914218bf70bd90f8081190f8095146f6756c8d42c0f2510c2ad205eb8501014491f80d2191f80e4191f80ae191f80b3191f80c1142ea0424012c4ff0010298bf14466e1c054680f80961b9b164294eea032028bf6421012888bf024644f62060824228bf02460cf5e2731046984706e0002180f80811bde870406047e047d5f8040138b142f64d42c0f244022146bde87040104770bd00bf70b542f2ed23c0f2460314460d4698474ff2a841c2f229010e6831466ff39601b1f1005f0ad131684ef66862ccf2ff02914218bf0026412d03d070bd0026412dfbd1002cf9d04cf6dd71c0f2450105468847002e01462846efd00129edd196f807120029e9d02168002948bf70bd4ff27d42c0f2590208469047284670bd00bf2de9f04f9db04ff2a84ac2f2290adaf800b058466ff39600b0f1005f40f07d81dbf800004ef66867ccf2ff07b84240f074819bf82802002800f05d81dbf82442002c00f0588140f6b400c2f20000d0f8008004a802f0caffb8f1000f00f01982032045f24075cff68070a4f1600108f160026ff0bf03c0f2020500bf0e6ed41826664e6ec03366668e6eab42a666ce6ee6660e6f26674e6f66678e6fa667ce6fe667d1f88060c4f88060d1f88460c4f88460d1f88860c4f88860d1f88c60c4f88c60d1f89060c4f89060d1f89460c4f89460d1f89860c4f89860d1f89c60c4f89c60d1f8a060c4f8a060d1f8a460c4f8a460d1f8a860c4f8a860d1f8ac60c4f8ac60d1f8b060c4f8b060d1f8b460c4f8b460d1f8b860c4f8b860d1f8bc60c4f8bc6051f8c06fc4f8c0604e68c4f8c4608e68c4f8c860ce68c4f8cc600e69c4f8d0604e69c4f8d4608e69c4f8d860ce69c4f8dc600e6ac4f8e0604e6ac4f8e4608e6ac4f8e860ce6ac4f8ec600e6bc4f8f0604e6bc4f8f4608e6bc4f8f860ce6bc4f8fc600e6cc4f800614e6cc4f804618e6cc4f80861ce6cc4f80c610e6dc4f810614e6dc4f814618e6dc4f81861ce6dc4f81c617ff462afdaf800603040b0f1005f40f0b2803068b84240f0ae8096f8ce00002840f0708196f8dc10002000298df8140000f0e88105a90a5c002a00f0bb810a185378002b00f079819378002b00f07781d378002b00f075811379002b00f073815379002b00f071819379002b00f06f81d379002b00f06d81137a002b00f06b81537a002b00f06981937a002b00f06781d37a002b00f06581137b002b00f06381537b002b00f06181937b002b00f05f81d37b002b00f05d81137c002b00f05b81537c002b00f05981937c002b00f05781d37c002b00f05581137d002b00f05381537d002b00f05181937d002b00f04f81d37d002b00f04d81137e002b00f04b81537e002b00f04981937e002b00f04781d37e002b00f04581137f002b00f04381537f002b00f04181937f002b00f03f81d27f002a00f03d81203060287ff47baf5ce19bf82a0270b1dbf82c0240b146f68051c2f207010968401a002800f3ea8000208bf82a0240f6d100c0f247001db0bde8f04f00474ff41b7004f04dfe002800f0bd804ff69451cff6ff71002200bf43183e3183f86c2283f86d2283f86e2283f86f2283f8702283f8712283f8722283f8732283f8742283f8752283f8762283f8772283f8782283f8792283f87a2283f87b2283f87c2283f87d2283f87e2283f87f2283f8802283f8812283f8822283f8832283f8842283f8852283f8862283f8872283f8882283f8892283f88a2283f88b2283f88c2283f88d2283f88e2283f88f2283f8902283f8912283f8922283f8932283f8942283f8952283f8962283f8972283f8982283f8992283f89a2283f89b2283f89c2283f89d2283f89e2283f89f2283f8a02283f8a12283f8a22283f8a32283f8a42283f8a52283f8a62283f8a72283f8a82283f8a9227ff480af012180f8ce104ff0ff310760a0f8e010a0f8e210a0f8e410a0f8e610a0f8e810a0f8ea10a0f8ec10a0f8ee10a0f8f010a0f8f210a0f8f410a0f8f610a0f8f810a0f8fa10a0f8fc10a0f8fe1010e000208bf82802cbf824028bf82a0201208bf8290240f6d100c0f24700804715e00020caf8000000208bf82802cbf824024ff416304cf60361069005a8c0f24701cdf81480884701208bf82a0204a802f0aafecbf8d4001db0bde8f08f01303ae0023038e0033036e0043034e0053032e0063030e007302ee008302ce009302ae00a3028e00b3026e00c3024e00d3022e00e3020e00f301ee010301ce011301ae0123018e0133016e0143014e0153012e0163010e017300ee018300ce019300ae01a3008e01b3006e01c3004e01d3002e01e3000e01f305f2821d84ff052020a541dd0014445225e284a7018d04f225d288a7014d052225c28ca7010d044225b280a710cd045225a284a7108d0522259288a7104d020225828ca7142f0168500208df87300012096f8dd10002900f0c280002105aa535c002b00f0a08057187b78002b5ed0bb78002b5dd0fb78002b5cd03b79002b5bd07b79002b5ad0bb79002b59d0fb79002b58d03b7a002b57d07b7a002b56d0bb7a002b55d0fb7a002b54d03b7b002b53d07b7b002b52d0bb7b002b51d0fb7b002b50d03b7c002b4fd07b7c002b4ed0bb7c002b4dd0fb7c002b4cd03b7d002b4bd07b7d002b4ad0bb7d002b49d0fb7d002b48d03b7e002b47d07b7e002b46d0bb7e002b45d0fb7e002b44d03b7f002b43d07b7f002b42d0bb7f002b41d0fb7f002b40d0203160297ff49aaf54e001313ae0023138e0033136e0043134e0053132e0063130e007312ee008312ce009312ae00a3128e00b3126e00c3124e00d3122e00e3120e00f311ee010311ce011311ae0123118e0133116e0143114e0153112e0163110e017310ee018310ce019310ae01a3108e01b3106e01c3104e01d3102e01e3100e01f315f2915d84ff05303535411d00a444b235e2953700cd049235d29937008d050235c29d37004d020235b29137140f0c28200218df87310013096f8de10002900f0be80002105aa535c002b00f0a08057187b78002b5ed0bb78002b5dd0fb78002b5cd03b79002b5bd07b79002b5ad0bb79002b59d0fb79002b58d03b7a002b57d07b7a002b56d0bb7a002b55d0fb7a002b54d03b7b002b53d07b7b002b52d0bb7b002b51d0fb7b002b50d03b7c002b4fd07b7c002b4ed0bb7c002b4dd0fb7c002b4cd03b7d002b4bd07b7d002b4ad0bb7d002b49d0fb7d002b48d03b7e002b47d07b7e002b46d0bb7e002b45d0fb7e002b44d03b7f002b43d07b7f002b42d0bb7f002b41d0fb7f002b40d0203160297ff49aaf50e001313ae0023138e0033136e004313Line truncated
"new": "02fb01f000e000bfb0b54ff2ac44c2f229040146206846f23f52c5f28802b2eb500f40f258304cf2e9124cf67e25c2f20000c0f24802caf2101518bf25609047002804bf691c2160b0bd00bf0846ffe7014640f258304cf20732c2f20000c0f24802104770b500284ed001684ef66862ccf2ff02914218bf70bd90f8081190f8095146f6756c8d42c0f2510c2ad205eb8501014491f80d2191f80e4191f80ae191f80b3191f80c1142ea0424012c4ff0010298bf14466e1c054680f80961b9b164294eea032028bf6421012888bf024644f62060824228bf02460cf5e2731046984706e0002180f80811bde870406047e047d5f8040138b142f64d42c0f244022146bde87040104770bd00bf70b542f2ed23c0f2460314460d4698474ff2a841c2f229010e6831466ff39601b1f1005f0ad131684ef66862ccf2ff02914218bf0026412d03d070bd0026412dfbd1002cf9d04cf6dd71c0f2450105468847002e01462846efd00129edd196f807120029e9d02168002948bf70bd4ff27d42c0f2590208469047284670bd00bf2de9f04f9db04ff2a84ac2f2290adaf800b058466ff39600b0f1005f40f07d81dbf800004ef66867ccf2ff07b84240f074819bf82802002800f05d81dbf82442002c00f0588140f6b400c2f20000d0f8008004a802f0caffb8f1000f00f01982032045f24075cff68070a4f1600108f160026ff0bf03c0f2020500bf0e6ed41826664e6ec03366668e6eab42a666ce6ee6660e6f26674e6f66678e6fa667ce6fe667d1f88060c4f88060d1f88460c4f88460d1f88860c4f88860d1f88c60c4f88c60d1f89060c4f89060d1f89460c4f89460d1f89860c4f89860d1f89c60c4f89c60d1f8a060c4f8a060d1f8a460c4f8a460d1f8a860c4f8a860d1f8ac60c4f8ac60d1f8b060c4f8b060d1f8b460c4f8b460d1f8b860c4f8b860d1f8bc60c4f8bc6051f8c06fc4f8c0604e68c4f8c4608e68c4f8c860ce68c4f8cc600e69c4f8d0604e69c4f8d4608e69c4f8d860ce69c4f8dc600e6ac4f8e0604e6ac4f8e4608e6ac4f8e860ce6ac4f8ec600e6bc4f8f0604e6bc4f8f4608e6bc4f8f860ce6bc4f8fc600e6cc4f800614e6cc4f804618e6cc4f80861ce6cc4f80c610e6dc4f810614e6dc4f814618e6dc4f81861ce6dc4f81c617ff462afdaf800603040b0f1005f40f0b2803068b84240f0ae8096f8ce00002840f0708196f8dc10002000298df8140000f0e88105a90a5c002a00f0bb810a185378002b00f079819378002b00f07781d378002b00f075811379002b00f073815379002b00f071819379002b00f06f81d379002b00f06d81137a002b00f06b81537a002b00f06981937a002b00f06781d37a002b00f06581137b002b00f06381537b002b00f06181937b002b00f05f81d37b002b00f05d81137c002b00f05b81537c002b00f05981937c002b00f05781d37c002b00f05581137d002b00f05381537d002b00f05181937d002b00f04f81d37d002b00f04d81137e002b00f04b81537e002b00f04981937e002b00f04781d37e002b00f04581137f002b00f04381537f002b00f04181937f002b00f03f81d27f002a00f03d81203060287ff47baf5ce19bf82a0270b1dbf82c0240b146f68051c2f207010968401a002800f3ea8000208bf82a0240f6d100c0f247001db0bde8f04f00474ff41b7004f04dfe002800f0bd804ff69451cff6ff71002200bf43183e3183f86c2283f86d2283f86e2283f86f2283f8702283f8712283f8722283f8732283f8742283f8752283f8762283f8772283f8782283f8792283f87a2283f87b2283f87c2283f87d2283f87e2283f87f2283f8802283f8812283f8822283f8832283f8842283f8852283f8862283f8872283f8882283f8892283f88a2283f88b2283f88c2283f88d2283f88e2283f88f2283f8902283f8912283f8922283f8932283f8942283f8952283f8962283f8972283f8982283f8992283f89a2283f89b2283f89c2283f89d2283f89e2283f89f2283f8a02283f8a12283f8a22283f8a32283f8a42283f8a52283f8a62283f8a72283f8a82283f8a9227ff480af012180f8ce104ff0ff310760a0f8e010a0f8e210a0f8e410a0f8e610a0f8e810a0f8ea10a0f8ec10a0f8ee10a0f8f010a0f8f210a0f8f410a0f8f610a0f8f810a0f8fa10a0f8fc10a0f8fe1010e000208bf82802cbf824028bf82a0201208bf8290240f6d100c0f24700804715e00020caf8000000208bf82802cbf824024ff416304cf60361069005a8c0f24701cdf81480884701208bf82a0204a802f0aafecbf8d4001db0bde8f08f01303ae0023038e0033036e0043034e0053032e0063030e007302ee008302ce009302ae00a3028e00b3026e00c3024e00d3022e00e3020e00f301ee010301ce011301ae0123018e0133016e0143014e0153012e0163010e017300ee018300ce019300ae01a3008e01b3006e01c3004e01d3002e01e3000e01f305f2821d84ff052020a541dd0014445225e284a7018d04f225d288a7014d052225c28ca7010d044225b280a710cd045225a284a7108d0522259288a7104d020225828ca7142f0168500208df87300012096f8dd10002900f0c280002105aa535c002b00f0a08057187b78002b5ed0bb78002b5dd0fb78002b5cd03b79002b5bd07b79002b5ad0bb79002b59d0fb79002b58d03b7a002b57d07b7a002b56d0bb7a002b55d0fb7a002b54d03b7b002b53d07b7b002b52d0bb7b002b51d0fb7b002b50d03b7c002b4fd07b7c002b4ed0bb7c002b4dd0fb7c002b4cd03b7d002b4bd07b7d002b4ad0bb7d002b49d0fb7d002b48d03b7e002b47d07b7e002b46d0bb7e002b45d0fb7e002b44d03b7f002b43d07b7f002b42d0bb7f002b41d0fb7f002b40d0203160297ff49aaf54e001313ae0023138e0033136e0043134e0053132e0063130e007312ee008312ce009312ae00a3128e00b3126e00c3124e00d3122e00e3120e00f311ee010311ce011311ae0123118e0133116e0143114e0153112e0163110e017310ee018310ce019310ae01a3108e01b3106e01c3104e01d3102e01e3100e01f315f2915d84ff05303535411d00a444b235e2953700cd049235d29937008d050235c29d37004d020235b29137140f0c28200218df87310013096f8de10002900f0be80002105aa535c002b00f0a08057187b78002b5ed0bb78002b5dd0fb78002b5cd03b79002b5bd07b79002b5ad0bb79002b59d0fb79002b58d03b7a002b57d07b7a002b56d0bb7a002b55d0fb7a002b54d03b7b002b53d07b7b002b52d0bb7b002b51d0fb7b002b50d03b7c002b4fd07b7c002b4ed0bb7c002b4dd0fb7c002b4cd03b7d002b4bd07b7d002b4ad0bb7d002b49d0fb7d002b48d03b7e002b47d07b7e002b46d0bb7e002b45d0fb7e002b44d03b7f002b43d07b7f002b42d0bb7f002b41d0fb7f002b40d0203160297ff49aaf50e001313ae0023138e0033136e004313Line truncated
"desc": "append injected blobs to main-app payload"
},
{
"offset": 779114,
"old": "846a3800",
"new": "24043900",
"new": "84043900",
"desc": "main-app subheader payload size (ps)"
},
{
"offset": 152,
"old": "046b3800",
"new": "a4043900",
"new": "04053900",
"desc": "main-app TOC entry size (ps + 128)"
},
{
"offset": 779234,
"old": "846a3804",
"new": "24043904",
"new": "84043904",
"desc": "main-app preamble length (low 24 bits)"
},
{
"offset": 779238,
"old": "85c355a2",
"new": "a7a15eca",
"new": "4f65faaf",
"desc": "[5] ota/s200_firmware_ota.bin preamble crc32"
},
{
"offset": 156,
"old": "ed292ee4",
"new": "94a735cb",
"new": "bbf1341a",
"desc": "[5] ota/s200_firmware_ota.bin component crc32c (TOC)"
},
{
"offset": 779118,
"old": "ed292ee4",
"new": "94a735cb",
"new": "bbf1341a",
"desc": "[5] ota/s200_firmware_ota.bin component crc32c (subheader)"
}
]
+27
View File
@@ -0,0 +1,27 @@
/**
* Magnetic declination from Android's built-in World Magnetic Model. Declination
* is the angle from magnetic north to true north (east positive), so
* `true = magnetic + declination`. No network access is involved; the model is
* baked into the platform and is accurate to well under a degree, which is far
* inside the magnetometer's own noise.
*/
declare const android: any;
declare const global: any;
/** Declination in degrees at a place and time, or null off-Android. */
export function magneticDeclinationDegrees(
latitude: number,
longitude: number,
timestampMs: number = Date.now(),
altitudeMeters = 0,
): number | null {
if (!global.isAndroid) return null;
try {
const field = new android.hardware.GeomagneticField(latitude, longitude, altitudeMeters, timestampMs);
const declination = Number(field.getDeclination());
return Number.isFinite(declination) ? declination : null;
} catch (error) {
console.warn(`GeomagneticField failed: ${error}`);
return null;
}
}
+16 -4
View File
@@ -79,7 +79,7 @@ brief:
| `getConfiguredApiKeys(): Promise<ApiKeyService[]>` | Which keys the user configured (names only). |
| `requestApiKeyAccess(services): Promise<Partial<Record<ApiKeyService, string>>>` | Prompt for and return key values. |
| `playBuzzer(steps): Promise<void>` | Play a piezo tone sequence. |
| `addCompassListener(fn): () => void` | Activate the magnetometer; receive heading samples. Uncalibrated (see note). |
| `addCompassListener(fn): () => void` | Activate the magnetometer; receive heading samples (see note). |
| `createLayout(layout): Promise<boolean>` | Build the initial page (extended layout: full 576×452, no count limit, `preserve`). |
| `replaceLayout(layout): Promise<boolean>` | Replace the page; `preserve` containers inherit content by name. |
| `setAssistantTools(tools): void` | Contribute voice-assistant tools (namespaced by package name). |
@@ -88,9 +88,21 @@ brief:
### Compass
`addCompassListener` is **not pre-calibrated**: the magnetometer is inside the
right arm, which rests on the head with a slight curl that differs between
wearers and wears. Treat the heading as relative — let the user zero it.
Each `CompassReading` carries several headings, all degrees clockwise in
[0, 360):
- `headingDegrees` — the raw glasses reading. **Not pre-calibrated**: the
magnetometer is inside the right arm, which rests on the head with a slight
curl that differs between wearers and wears, so this is relative.
- `magneticHeadingDegrees` — raw reading corrected by the wearer's calibration
offset from the host's Compass app. `wearerCalibrated` says whether they have
calibrated; until then it equals `headingDegrees`.
- `declinationDegrees` / `trueHeadingDegrees` — local declination from the
phone's location, and the magnetic heading with it applied. Absent when the
host has no location (no permission, or no fix yet).
Prefer `trueHeadingDegrees` when present, then `magneticHeadingDegrees`. If
`wearerCalibrated` is false, treat them as relative or let the user zero them.
### Extended layout
+32 -6
View File
@@ -62,10 +62,34 @@ export type WindowLifecycleEventType = "visible" | "hidden" | "focused" | "blurr
export interface WindowLifecycleEvent {
type: WindowLifecycleEventType;
}
/** A magnetometer heading sample from {@link FaceclawExtensions.addCompassListener}. */
/**
* A magnetometer heading sample from {@link FaceclawExtensions.addCompassListener}.
* All headings are degrees clockwise in [0, 360).
*/
export interface CompassReading {
/** Magnetic heading in degrees [0, 360). */
/**
* Raw magnetic heading as reported by the glasses, with no correction for
* how they sit on the wearer's head. Kept for apps that zero it themselves.
*/
headingDegrees: number;
/**
* Magnetic heading corrected by the wearer's calibration offset from the
* host's Compass app. Equal to `headingDegrees` until they calibrate.
*/
magneticHeadingDegrees: number;
/**
* Whether the wearer has been through the host's compass calibration, i.e.
* whether `magneticHeadingDegrees` and `trueHeadingDegrees` can be trusted
* as absolute rather than relative.
*/
wearerCalibrated: boolean;
/**
* Local magnetic declination (east positive), from the phone's location and
* the World Magnetic Model. Absent when the host has no location.
*/
declinationDegrees?: number;
/** `magneticHeadingDegrees` plus declination. Absent when declination is. */
trueHeadingDegrees?: number;
}
export interface FaceclawContainerCommon {
containerID: number;
@@ -172,10 +196,12 @@ export interface FaceclawExtensions {
* Returns an unsubscribe function; the sensor stays on while at least one
* listener is registered and the app is the foreground window.
*
* NOT pre-calibrated: the magnetometer sits inside the right arm, which rests
* against the wearer's head with a slight curl that differs between wearers
* (and between wears). Treat `headingDegrees` as relative — let the user zero
* it against a known direction rather than trusting it as true/magnetic north.
* The magnetometer sits inside the right arm, which rests against the
* wearer's head with a slight curl that differs between wearers (and between
* wears), so `headingDegrees` is relative. The host's Compass app lets the
* wearer calibrate that away and adds local declination: prefer
* `trueHeadingDegrees` when present, then `magneticHeadingDegrees`, and check
* `wearerCalibrated` before trusting either as absolute.
*/
addCompassListener(listener: (reading: CompassReading) => void): () => void;
/**
+32 -6
View File
@@ -67,10 +67,34 @@ export interface WindowLifecycleEvent {
type: WindowLifecycleEventType;
}
/** A magnetometer heading sample from {@link FaceclawExtensions.addCompassListener}. */
/**
* A magnetometer heading sample from {@link FaceclawExtensions.addCompassListener}.
* All headings are degrees clockwise in [0, 360).
*/
export interface CompassReading {
/** Magnetic heading in degrees [0, 360). */
/**
* Raw magnetic heading as reported by the glasses, with no correction for
* how they sit on the wearer's head. Kept for apps that zero it themselves.
*/
headingDegrees: number;
/**
* Magnetic heading corrected by the wearer's calibration offset from the
* host's Compass app. Equal to `headingDegrees` until they calibrate.
*/
magneticHeadingDegrees: number;
/**
* Whether the wearer has been through the host's compass calibration, i.e.
* whether `magneticHeadingDegrees` and `trueHeadingDegrees` can be trusted
* as absolute rather than relative.
*/
wearerCalibrated: boolean;
/**
* Local magnetic declination (east positive), from the phone's location and
* the World Magnetic Model. Absent when the host has no location.
*/
declinationDegrees?: number;
/** `magneticHeadingDegrees` plus declination. Absent when declination is. */
trueHeadingDegrees?: number;
}
// ---- Extended layout (a superset of the stock EvenHub page containers) ----
@@ -207,10 +231,12 @@ export interface FaceclawExtensions {
* Returns an unsubscribe function; the sensor stays on while at least one
* listener is registered and the app is the foreground window.
*
* NOT pre-calibrated: the magnetometer sits inside the right arm, which rests
* against the wearer's head with a slight curl that differs between wearers
* (and between wears). Treat `headingDegrees` as relative — let the user zero
* it against a known direction rather than trusting it as true/magnetic north.
* The magnetometer sits inside the right arm, which rests against the
* wearer's head with a slight curl that differs between wearers (and between
* wears), so `headingDegrees` is relative. The host's Compass app lets the
* wearer calibrate that away and adds local declination: prefer
* `trueHeadingDegrees` when present, then `magneticHeadingDegrees`, and check
* `wearerCalibrated` before trusting either as absolute.
*/
addCompassListener(listener: (reading: CompassReading) => void): () => void;