Files
faceclaw/app/native/ambient-light.ts
T

158 lines
5.3 KiB
TypeScript

/**
* Ambient light sensor access through the custom firmware (CFW image-handler
* mode 16; see g2flash/patches/als_sensor.c).
*
* The stock firmware only reads its OPT3001 light sensor while auto-brightness
* is on, and then steps the panel brightness itself (visible flicker). The CFW
* adds two things:
*
* - QUERY: one report from the driver's current state.
* - PASSIVE polling: the firmware opens and polls the sensor at our interval,
* the stock adjuster never touches the panel, and a report arrives when the
* reading moved by at least `minDelta` or `heartbeatMs` elapsed. The phone
* then applies brightness itself (setBrightness with autoAdjust=false), e.g.
* only while the display is blank or during a UI transition.
*
* Reports are 24-byte ['A','L',version,...] records on settings field 105.
*/
import { toUint8Array } from "../util/array-util";
declare const com: any;
declare const global: any;
export const ALS_REPORT_VERSION = 1;
export type AmbientLightReason = "query" | "started" | "poll" | "stopped";
export type AmbientLightReport = {
reason: AmbientLightReason;
/** The sensor driver is open (readings are live). */
opened: boolean;
/** CFW passive polling is installed (stock auto-brightness is not stepping). */
passive: boolean;
/** The user's stock auto-brightness setting is on. */
autoBrightness: boolean;
/** The last passive read succeeded (only meaningful while passive). */
readOk: boolean;
/** Stock driver status: 1 start-read, 2 adjusting, 3 polling. */
status: number;
/** Ambient light in the stock driver's units (roughly tenths of a lux). */
alsValue: number;
/** Max of the last five readings (what the stock curve is applied to). */
peak: number;
/** Brightness level (0..100) the stock curve would choose for `peak`. */
stockTarget: number;
/** Current brightness setting (0..100). */
brightness: number;
/** Row of the stock brightness curve (0..5) for `peak`. */
gear: number;
/** Stock learned scale factor, Q10 (1024 = 1.0). */
scaleQ10: number;
/** Firmware millisecond tick when the report was built. */
tickMs: number;
};
const REASONS: AmbientLightReason[] = ["query", "started", "poll", "stopped"];
function rd16(b: Uint8Array, i: number): number {
return b[i] | (b[i + 1] << 8);
}
function rd32(b: Uint8Array, i: number): number {
return (b[i] | (b[i + 1] << 8) | (b[i + 2] << 16) | (b[i + 3] << 24)) >>> 0;
}
/** Decode a field-105 record body, or null when it isn't one. */
export function decodeAmbientLightReport(body: Uint8Array): AmbientLightReport | null {
if (body.length < 24 || body[0] !== 0x41 || body[1] !== 0x4c || body[2] !== ALS_REPORT_VERSION) {
return null;
}
const flags = body[4];
return {
reason: REASONS[body[3]] ?? "poll",
opened: (flags & 0x01) !== 0,
passive: (flags & 0x02) !== 0,
autoBrightness: (flags & 0x04) !== 0,
readOk: (flags & 0x08) !== 0,
status: body[5],
alsValue: rd32(body, 6),
peak: rd32(body, 10),
stockTarget: rd16(body, 14),
brightness: body[16],
gear: body[17],
scaleQ10: rd16(body, 18),
tickMs: rd32(body, 20),
};
}
export type AmbientLightPollingOptions = {
/** Poll period in ms; the firmware clamps to 100..5000. Default 500. */
intervalMs?: number;
/** Report when the reading moved by at least this much. Default 1. */
minDelta?: number;
/** Also report after this many ms without one (0 = never). Default 5000. */
heartbeatMs?: number;
/**
* Stop automatically when the Faceclaw framebuffer lease is released or
* lapses (the phone went away). Default true.
*/
bindToLease?: boolean;
};
function activeCommunicator(): any {
if (!global.isAndroid) return null;
try {
return com.faceclaw.app.FaceclawBleCommunicator.getActive();
} catch {
return null;
}
}
/** Ask the firmware for one ambient-light report (delivered to listeners). */
export function queryAmbientLight(): void {
try {
activeCommunicator()?.queryAmbientLight();
} catch (error) {
console.warn(`queryAmbientLight failed: ${error}`);
}
}
/**
* Start or stop CFW passive light-sensor polling. Starting is idempotent and
* re-opens the sensor if the stock firmware closed it, so it is safe to resend
* on every session start.
*/
export function setAmbientLightPolling(enabled: boolean, options: AmbientLightPollingOptions = {}): void {
try {
activeCommunicator()?.setAmbientLightPolling(
enabled,
options.intervalMs ?? 500,
options.minDelta ?? 1,
options.heartbeatMs ?? 5000,
options.bindToLease ?? true,
);
} catch (error) {
console.warn(`setAmbientLightPolling failed: ${error}`);
}
}
/** Subscribe to decoded ambient-light reports. Delivered on the main thread. */
export function addAmbientLightListener(listener: (report: AmbientLightReport) => void): () => void {
const active = activeCommunicator();
if (!active) return () => {};
const proxy = new com.faceclaw.app.FaceclawAmbientLightListener({
onAmbientLight: (body: any) => {
const report = decodeAmbientLightReport(toUint8Array(body));
if (report) listener(report);
},
});
active.addAmbientLightListener(proxy);
return () => {
try {
activeCommunicator()?.removeAmbientLightListener(proxy);
} catch {
// The communicator may have been replaced during a disconnect.
}
};
}