Add a BLE bandwidth estimation tool to the Developer/Debug tests menu

This commit is contained in:
James Babcock committed 2026-08-24 17:45:01 -07:00
1 parent 208b14e928
commit 1d81ed7881
4 files changed
+505 -6

No files matched your search

@@ -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<OutboundMessage> 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;
+204
View File
@@ -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<typeof setTimeout> | null = null;
private pollTimer: ReturnType<typeof setInterval> | 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<void> {
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;
}
}
}
+7
View File
@@ -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,
);
+68
View File
@@ -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;
}
}