From 1d81ed7881f968a6c0b16742d38afc61c9be5809 Mon Sep 17 00:00:00 2001 From: James Babcock Date: Mon, 24 Aug 2026 17:45:01 -0700 Subject: [PATCH] Add a BLE bandwidth estimation tool to the Developer/Debug tests menu --- .../faceclaw/app/FaceclawBleCommunicator.java | 232 +++++++++++++++++- app/apps/developer/bandwidth-benchmark.ts | 204 +++++++++++++++ app/apps/developer/developer-app.ts | 7 + app/native/bandwidth-benchmark.ts | 68 +++++ 4 files changed, 505 insertions(+), 6 deletions(-) create mode 100644 app/apps/developer/bandwidth-benchmark.ts create mode 100644 app/native/bandwidth-benchmark.ts diff --git a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleCommunicator.java b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleCommunicator.java index 98074d90..b325dbeb 100644 --- a/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleCommunicator.java +++ b/App_Resources/Android/src/main/java/com/faceclaw/app/FaceclawBleCommunicator.java @@ -152,6 +152,35 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { private volatile FaceclawAudioPacketListener audioPacketListener; private PowerManager.WakeLock g2ScreenWakeLock; + // BLE bandwidth benchmark (Developer app). Streams no-op image payloads + // (CFW mode 7 with an unused sub-op: parsed, acked, and discarded — stock + // firmware likewise ignores unknown image modes) for a fixed duration with + // a selectable message size and pipeline window, then reports throughput. + // While active, desired-frame sends are held back and heartbeats are + // satisfied by the benchmark's own acks, so the stream is the only image + // traffic. All state below is guarded by `lock`; results are read with + // getBandwidthBenchmarkStatus() and survive until the next run starts. + private boolean benchmarkActive; + private boolean benchmarkAborted; + private byte[] benchmarkPayload = new byte[0]; + private int benchmarkMessageSize; + private int benchmarkWindowSize; + private int benchmarkDurationMs; + private long benchmarkStartAtMs; // first benchmark write; 0 until then + private long benchmarkDeadlineAtMs; // start + duration; MAX_VALUE until first write + private long benchmarkLastAckAtMs; + private long benchmarkEndAtMs; // 0 while running; set when the run drains + private int benchmarkMessagesSent; + private int benchmarkMessagesAcked; + private int benchmarkTimeouts; + private long benchmarkPayloadBytesAcked; + private long benchmarkWireBytesAcked; + // A timed-out benchmark message aborts the run, but its already-in-flight + // peers still time out one by one; keep the window comfortably below + // MAX_CONSECUTIVE_ACK_TIMEOUTS so a dead run can't escalate into a + // transport-failure reconnect all by itself. + private static final int BENCHMARK_MAX_WINDOW = 6; + private final BroadcastReceiver phoneLockReceiver = new BroadcastReceiver() { @Override public void onReceive(Context context, Intent intent) { emitPhoneLockStateIfChanged(true); @@ -523,6 +552,185 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { interruptibleSleep.interrupt(); } + /** + * Start the BLE bandwidth benchmark: stream messageSize-byte no-op image + * payloads for durationMs, keeping up to windowSize messages awaiting ack + * at once, then leave the results for getBandwidthBenchmarkStatus(). + * Returns false when a run is already active or the image path is not + * ready. The duration clock starts at the first benchmark write, so + * traffic already queued ahead of the run doesn't count against it. + */ + public boolean startBandwidthBenchmark(int messageSize, int windowSize, int durationMs) { + synchronized (lock) { + if (benchmarkActive || !running || !sessionReady || !fixedLayoutCreated + || shutdownRequested || chargingMode) { + logLine("skip bandwidth benchmark; already running or image path not ready"); + return false; + } + byte[] payload = new byte[Math.max(2, Math.min(messageSize, ConnectionOptions.IMAGE_FRAGMENT_SIZE))]; + payload[0] = 7; // CFW diagnostic-control mode... + payload[1] = (byte) 0x7f; // ...with an unused sub-op: acked, no effect + benchmarkPayload = payload; + benchmarkMessageSize = payload.length; + benchmarkWindowSize = Math.max(1, Math.min(windowSize, BENCHMARK_MAX_WINDOW)); + benchmarkDurationMs = Math.max(1_000, durationMs); + benchmarkStartAtMs = 0; + benchmarkDeadlineAtMs = Long.MAX_VALUE; + benchmarkLastAckAtMs = 0; + benchmarkEndAtMs = 0; + benchmarkMessagesSent = 0; + benchmarkMessagesAcked = 0; + benchmarkTimeouts = 0; + benchmarkPayloadBytesAcked = 0; + benchmarkWireBytesAcked = 0; + benchmarkAborted = false; + benchmarkActive = true; + logLine("bandwidth benchmark start: size=" + benchmarkMessageSize + + "B window=" + benchmarkWindowSize + " duration=" + benchmarkDurationMs + "ms"); + } + interruptibleSleep.interrupt(); + return true; + } + + /** + * Cancel an in-progress benchmark (benchmark page closed). Queued no-op + * messages are dropped; in-flight ones drain through their normal acks. + */ + public void cancelBandwidthBenchmark() { + synchronized (lock) { + if (!benchmarkActive) { + return; + } + clearMessagesOfKindLocked("bandwidth"); + finishBenchmarkLocked(true, "cancelled"); + } + interruptibleSleep.interrupt(); + } + + /** Status/results of the current or most recent benchmark run, as JSON. */ + public String getBandwidthBenchmarkStatus() { + synchronized (lock) { + String state = benchmarkActive + ? (benchmarkStartAtMs == 0 ? "starting" : "running") + : (benchmarkEndAtMs != 0 ? "done" : "idle"); + long end = benchmarkActive ? SystemClock.elapsedRealtime() : benchmarkEndAtMs; + long elapsed = benchmarkStartAtMs == 0 ? 0 : Math.max(0, end - benchmarkStartAtMs); + try { + org.json.JSONObject status = new org.json.JSONObject(); + status.put("state", state); + status.put("messageSize", benchmarkMessageSize); + status.put("windowSize", benchmarkWindowSize); + status.put("elapsedMs", elapsed); + status.put("messagesSent", benchmarkMessagesSent); + status.put("messagesAcked", benchmarkMessagesAcked); + status.put("timeouts", benchmarkTimeouts); + status.put("payloadBytesAcked", benchmarkPayloadBytesAcked); + status.put("wireBytesAcked", benchmarkWireBytesAcked); + status.put("aborted", benchmarkAborted); + return status.toString(); + } catch (org.json.JSONException e) { + return "{\"state\":\"idle\"}"; + } + } + } + + /** Pending + in-flight benchmark no-op messages. */ + private int benchmarkOutstandingLocked() { + int count = 0; + for (OutboundMessage message : pendingMessages) { + if ("bandwidth".equals(message.kind)) count++; + } + for (OutboundMessage message : inFlightMessages) { + if ("bandwidth".equals(message.kind)) count++; + } + return count; + } + + /** + * Keep the benchmark stream fed: top the pending queue up so the send + * window never starves, stop enqueueing once the run expires (or a message + * times out), and finish the run when the last outstanding message drains. + */ + private void maintainBenchmarkLocked(long now) { + if (!sessionReady || !fixedLayoutCreated || shutdownRequested) { + finishBenchmarkLocked(true, "session no longer ready"); + return; + } + if (benchmarkAborted || now >= benchmarkDeadlineAtMs) { + // The run is over: drop queued-but-unsent no-ops (sending them + // would stretch the run past its deadline) and finish once the + // in-flight tail has acked or timed out. + Iterator pendingIterator = pendingMessages.iterator(); + while (pendingIterator.hasNext()) { + OutboundMessage queued = pendingIterator.next(); + if ("bandwidth".equals(queued.kind)) { + pendingIterator.remove(); + magicPool.release(queued.sid, queued.magic, queued.label, "benchmark over"); + } + } + if (benchmarkOutstandingLocked() == 0) { + finishBenchmarkLocked(false, "complete"); + } + return; + } + // One more than the window so a fresh message is always ready to write + // the moment an ack frees a slot. + for (int outstanding = benchmarkOutstandingLocked(); outstanding <= benchmarkWindowSize; outstanding++) { + enqueueBenchmarkMessageLocked(); + } + } + + private void finishBenchmarkLocked(boolean aborted, String reason) { + if (!benchmarkActive) { + return; + } + benchmarkActive = false; + benchmarkAborted |= aborted; + // Prefer the last ack as the end time so drain lag after the deadline + // doesn't dilute the throughput figure. + benchmarkEndAtMs = benchmarkLastAckAtMs != 0 ? benchmarkLastAckAtMs : SystemClock.elapsedRealtime(); + logLine("bandwidth benchmark " + (benchmarkAborted ? "aborted" : "finished") + " (" + reason + "): " + + benchmarkMessagesAcked + "/" + benchmarkMessagesSent + " acked, " + + benchmarkPayloadBytesAcked + "B payload, " + benchmarkTimeouts + " timeouts"); + } + + private void enqueueBenchmarkMessageLocked() { + OutboundMessage message = messageBuilder.imagePayload( + "bandwidth", + DASHBOARD_TILE, + nextMapSessionId(), + benchmarkPayload, + "bandwidth no-op " + benchmarkPayload.length + "B", + connectionOptions.sendImagesToLeft); + final int payloadBytes = benchmarkPayload.length; + // Protobuf-wrapped message bytes; the `aa 21` envelope adds a few more + // per MTU-sized BLE frame, which this figure does not include. + final int wireBytes = message.message.length; + message.onSent = () -> { + benchmarkMessagesSent++; + if (benchmarkStartAtMs == 0) { + benchmarkStartAtMs = SystemClock.elapsedRealtime(); + benchmarkDeadlineAtMs = benchmarkStartAtMs + benchmarkDurationMs; + } + }; + message.onAck = () -> { + long ackedAtMs = SystemClock.elapsedRealtime(); + benchmarkMessagesAcked++; + benchmarkPayloadBytesAcked += payloadBytes; + benchmarkWireBytesAcked += wireBytes; + benchmarkLastAckAtMs = ackedAtMs; + // No-op payloads ride the image path, so the firmware resets its + // heartbeat timer on them just like real image messages. + lastHeartbeatAckedAtMs = ackedAtMs; + }; + message.onTimeout = () -> { + benchmarkTimeouts++; + benchmarkAborted = true; + logLine("bandwidth benchmark ack timeout"); + }; + pendingMessages.addLast(message); + } + public void addImuListener(FaceclawImuListener listener) { if (listener != null) { imuListeners.add(listener); @@ -1768,9 +1976,15 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { enqueueCompassControlLocked(false, compassEnabled); } + if (benchmarkActive) { + maintainBenchmarkLocked(now); + } + // Up to WINDOW_SIZE messages may be in flight at once (full - // pipelining); a slot frees when an ack arrives. - boolean windowHasRoom = inFlightMessages.size() < Math.max(1, connectionOptions.WINDOW_SIZE); + // pipelining); a slot frees when an ack arrives. An active + // bandwidth benchmark measures its own selected window instead. + boolean windowHasRoom = inFlightMessages.size() + < Math.max(1, benchmarkActive ? benchmarkWindowSize : connectionOptions.WINDOW_SIZE); // A frame ready to send right now: don't inject a fresh // heartbeat in front of it (the image's own ack resets the // firmware heartbeat timer, so the heartbeat is redundant). @@ -1781,11 +1995,15 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { // window unprotected and a heartbeat that came due there // cost the frame a full ack round trip (measured 124ms on // frame#232 of the 2026-08-20 02:27 capture). + // A benchmark run counts as image traffic here for the same + // reason: its acks reset the firmware heartbeat timer, so a + // fresh heartbeat in front of it is redundant. boolean imageWaiting = !shutdownRequested && fixedLayoutCreated && !hasPendingOrInflightKindLocked("heartbeat") - && now >= imageRetryAfterMs - && (hasPendingImageLocked() - || !getDesiredFingerprint().equals(lastEnqueuedFingerprint)); + && (benchmarkActive + || (now >= imageRetryAfterMs + && (hasPendingImageLocked() + || !getDesiredFingerprint().equals(lastEnqueuedFingerprint)))); noteImageStallLocked(now, windowHasRoom); if (messageToPrewrite == null && handleHeartbeat(imageWaiting)) { return ConnectionOptions.IDLE_SLEEP_MS; @@ -1794,7 +2012,8 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { if (messageToPrewrite == null && sessionReady && windowHasRoom && !pendingMessages.isEmpty()) { messageToWrite = pendingMessages.removeFirst(); Log.i(TAG, "sending pending message: " + messageToWrite.label); - } else if (messageToPrewrite == null && !shutdownRequested && fixedLayoutCreated + } else if (messageToPrewrite == null && !shutdownRequested && !benchmarkActive + && fixedLayoutCreated && windowHasRoom && !hasPendingImageLocked() && now >= imageRetryAfterMs && !getDesiredFingerprint().equals(lastEnqueuedFingerprint)) { @@ -3043,6 +3262,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable { Log.e(TAG, "Transport failure: "+reason); synchronized (lock) { maybeEmitEvenAppConflictLocked(reason); + finishBenchmarkLocked(true, "transport failure"); sessionReady = false; fixedLayoutCreated = false; startupProbePending = false; diff --git a/app/apps/developer/bandwidth-benchmark.ts b/app/apps/developer/bandwidth-benchmark.ts new file mode 100644 index 00000000..1f6c3bc7 --- /dev/null +++ b/app/apps/developer/bandwidth-benchmark.ts @@ -0,0 +1,204 @@ +import { getDefaultSmallFont } from "../../graphics/ui-fonts"; +import { GrayImage } from "../../graphics/image"; +import { Layer, type DashboardInputEvent, type LayerContext } from "../../ui/layers"; +import { drawSelectionHighlight } from "../../ui/menu"; +import { tightRowHeight } from "../../ui/metrics"; +import { + cancelBandwidthBenchmark, + getBandwidthBenchmarkStatus, + startBandwidthBenchmark, + type BandwidthBenchmarkStatus, +} from "../../native/bandwidth-benchmark"; + +const MESSAGE_SIZES = [250, 500, 1000, 2000, 3800]; +const WINDOW_SIZES = [1, 2, 3, 4, 6]; +const DURATION_MS = 15_000; +// After painting the "running" screen, wait for that frame to reach the +// glasses before the benchmark blocks normal image sends — otherwise the +// status frame would sit queued behind the whole 15-second run. +const ARM_DELAY_MS = 800; +const POLL_INTERVAL_MS = 500; +// Give up polling if the run somehow never reports done (duration + ack +// timeout drain + slack). +const POLL_DEADLINE_MS = DURATION_MS + 15_000; + +const HEADER_HEIGHT = 30; +const LIST_X = 20; +const VALUE_X = 150; + +type Phase = "config" | "arming" | "running" | "done"; + +/** + * BLE bandwidth benchmark: pick a message size and pipeline window, stream + * no-op image payloads for 15 seconds, and report throughput. The glasses + * screen is intentionally static while the run is active — the benchmark + * stream is the only image traffic, so the numbers are clean. + */ +export class BandwidthBenchmarkLayer implements Layer { + private phase: Phase = "config"; + private selectedRow = 0; // 0 = message size, 1 = window size, 2 = start + private sizeIndex = 2; + private windowIndex = 2; + private result: BandwidthBenchmarkStatus | null = null; + private error: string | null = null; + private armTimer: ReturnType | null = null; + private pollTimer: ReturnType | null = null; + private pollStartedAtMs = 0; + + constructor(private readonly requestRender: () => void) {} + + onRemoved(): void { + this.clearTimers(); + if (this.phase === "arming" || this.phase === "running") { + cancelBandwidthBenchmark(); + } + } + + private clearTimers(): void { + if (this.armTimer !== null) { + clearTimeout(this.armTimer); + this.armTimer = null; + } + if (this.pollTimer !== null) { + clearInterval(this.pollTimer); + this.pollTimer = null; + } + } + + private startRun(): void { + this.result = null; + this.error = null; + this.phase = "arming"; + this.requestRender(); + this.armTimer = setTimeout(() => { + this.armTimer = null; + const started = startBandwidthBenchmark( + MESSAGE_SIZES[this.sizeIndex]!, + WINDOW_SIZES[this.windowIndex]!, + DURATION_MS, + ); + if (!started) { + this.phase = "config"; + this.error = "Could not start (not connected?)"; + this.requestRender(); + return; + } + this.phase = "running"; + this.pollStartedAtMs = Date.now(); + // No renders while polling: a repaint would queue an image update that + // stays blocked behind the benchmark anyway. Render once on completion. + this.pollTimer = setInterval(() => this.poll(), POLL_INTERVAL_MS); + }, ARM_DELAY_MS); + } + + private poll(): void { + const status = getBandwidthBenchmarkStatus(); + if (status && (status.state === "starting" || status.state === "running")) { + if (Date.now() - this.pollStartedAtMs < POLL_DEADLINE_MS) return; + cancelBandwidthBenchmark(); + return; // next poll picks up the cancelled run's "done" + } + this.clearTimers(); + if (status && status.state === "done") { + this.result = status; + this.phase = "done"; + } else { + this.phase = "config"; + this.error = "Benchmark lost (disconnected?)"; + } + this.requestRender(); + } + + paint(ctx: LayerContext): GrayImage { + const font = getDefaultSmallFont(); + const { width, height } = ctx.stack.getBaseSize(); + const image = new GrayImage(width, height, 0); + + image.drawText(font, 20, 8, "BLE bandwidth", 220); + + if (this.phase === "arming" || this.phase === "running") { + image.drawText(font, LIST_X, HEADER_HEIGHT + 8, "Running: streaming no-op packets for 15 s...", 200); + image.drawText( + font, + LIST_X, + HEADER_HEIGHT + 30, + `${MESSAGE_SIZES[this.sizeIndex]} B messages, window ${WINDOW_SIZES[this.windowIndex]}`, + 150, + ); + image.drawText(font, LIST_X, HEADER_HEIGHT + 52, "Display updates pause until the run finishes.", 110); + return image; + } + + const rowH = tightRowHeight(font) + 4; + const rows: Array<[string, string]> = [ + ["Message size", `${MESSAGE_SIZES[this.sizeIndex]} B`], + ["Window size", `${WINDOW_SIZES[this.windowIndex]}`], + [this.phase === "done" ? "Run again" : "Start", ""], + ]; + for (let index = 0; index < rows.length; index++) { + const [label, value] = rows[index]!; + const y = HEADER_HEIGHT + index * rowH; + const selected = index === this.selectedRow; + if (selected) { + drawSelectionHighlight(image, LIST_X - 6, y - 1, width - 2 * LIST_X + 12, rowH - 1, ctx.stack.isFocused(), 4); + } + image.drawText(font, LIST_X, y + 2, label, selected ? 255 : 200); + if (value) { + image.drawText(font, VALUE_X, y + 2, value, selected ? 235 : 160); + } + } + + let y = HEADER_HEIGHT + rows.length * rowH + 10; + if (this.error) { + image.drawText(font, LIST_X, y, this.error, 180); + } else if (this.result) { + const r = this.result; + const seconds = r.elapsedMs / 1000; + const payloadRate = seconds > 0 ? r.payloadBytesAcked / seconds : 0; + const wireRate = seconds > 0 ? r.wireBytesAcked / seconds : 0; + const lines = [ + `Throughput: ${(payloadRate / 1024).toFixed(2)} KB/s payload (${(wireRate / 1024).toFixed(2)} KB/s wire)`, + `Messages: ${r.messagesAcked}/${r.messagesSent} acked, ${r.timeouts} timeouts`, + `Elapsed: ${seconds.toFixed(1)} s` + (r.aborted ? " (aborted early)" : ""), + ]; + for (const line of lines) { + image.drawText(font, LIST_X, y, line, 190); + y += 20; + } + } + + return image; + } + + async handleInput(event: DashboardInputEvent, ctx: LayerContext): Promise { + if (this.phase === "arming" || this.phase === "running") { + // A static screen during the run: only allow bailing out. + if (event.type === "double-click") { + ctx.stack.pop(); + } + return; + } + switch (event.type) { + case "scroll-up": + this.selectedRow = Math.max(0, this.selectedRow - 1); + return; + case "scroll-down": + this.selectedRow = Math.min(2, this.selectedRow + 1); + return; + case "click": + if (this.selectedRow === 0) { + this.sizeIndex = (this.sizeIndex + 1) % MESSAGE_SIZES.length; + } else if (this.selectedRow === 1) { + this.windowIndex = (this.windowIndex + 1) % WINDOW_SIZES.length; + } else { + this.startRun(); + } + return; + case "double-click": + ctx.stack.pop(); + return; + default: + return; + } + } +} diff --git a/app/apps/developer/developer-app.ts b/app/apps/developer/developer-app.ts index aeac1b9c..61e40ccf 100644 --- a/app/apps/developer/developer-app.ts +++ b/app/apps/developer/developer-app.ts @@ -2,6 +2,7 @@ import { MenuLayer, drawSubmenuIndicator, type MenuItem } from "../../ui/menu"; import { ScreenTestLayer } from "./screen-test"; import { BuzzerDemoLayer } from "./buzzer-demo"; import { AccelerometerDemoLayer } from "./accelerometer-demo"; +import { BandwidthBenchmarkLayer } from "./bandwidth-benchmark"; import { ResourceUsageLayer } from "./resource-usage"; import { LoadAppFromQrLayer, LoadAppFromUrlLayer } from "./load-app"; import { type AppContext } from "../app-definition"; @@ -67,6 +68,12 @@ function debugTestsMenu(): MenuLayer { ctx.stack.push(new AccelerometerDemoLayer(DEVELOPER_WINDOW_ID, ctx.actions.requestRender)); }, }, + { + label: "BLE bandwidth", + onSelect: (ctx) => { + ctx.stack.push(new BandwidthBenchmarkLayer(ctx.actions.requestRender)); + }, + }, ], MENU_LAYOUT, ); diff --git a/app/native/bandwidth-benchmark.ts b/app/native/bandwidth-benchmark.ts new file mode 100644 index 00000000..fbd99dfb --- /dev/null +++ b/app/native/bandwidth-benchmark.ts @@ -0,0 +1,68 @@ +declare const com: any; + +/** + * BLE bandwidth benchmark controls (Developer app). The Java communicator + * streams no-op image payloads for a fixed duration with a selectable message + * size and pipeline window, then reports throughput. Progress and results are + * polled with getBandwidthBenchmarkStatus. + * + * Talks to the active communicator via the FaceclawBleCommunicator.getActive() + * static, so it works from any isolate without threading the bridge through. + */ + +export type BandwidthBenchmarkStatus = { + state: "idle" | "starting" | "running" | "done"; + messageSize: number; + windowSize: number; + elapsedMs: number; + messagesSent: number; + messagesAcked: number; + timeouts: number; + payloadBytesAcked: number; + wireBytesAcked: number; + aborted: boolean; +}; + +function activeCommunicator(): any { + if (!global.isAndroid) return null; + try { + return com.faceclaw.app.FaceclawBleCommunicator.getActive(); + } catch { + return null; + } +} + +/** Start a run. False if not connected or a run is already active. */ +export function startBandwidthBenchmark(messageSize: number, windowSize: number, durationMs: number): boolean { + const active = activeCommunicator(); + if (!active) return false; + try { + return Boolean( + active.startBandwidthBenchmark(Math.round(messageSize), Math.round(windowSize), Math.round(durationMs)), + ); + } catch (error) { + console.warn(`startBandwidthBenchmark failed: ${error}`); + return false; + } +} + +/** Cancel an in-progress run. Safe to call when idle. */ +export function cancelBandwidthBenchmark(): void { + try { + activeCommunicator()?.cancelBandwidthBenchmark(); + } catch (error) { + console.warn(`cancelBandwidthBenchmark failed: ${error}`); + } +} + +/** Status of the current or most recent run; null when not connected. */ +export function getBandwidthBenchmarkStatus(): BandwidthBenchmarkStatus | null { + const active = activeCommunicator(); + if (!active) return null; + try { + return JSON.parse(String(active.getBandwidthBenchmarkStatus())) as BandwidthBenchmarkStatus; + } catch (error) { + console.warn(`getBandwidthBenchmarkStatus failed: ${error}`); + return null; + } +}