Send messages through a new SID, rather than image messages

This commit is contained in:
James Babcock committed 2026-09-13 21:42:29 -07:00
1 parent dcb071621d
commit 33bfdcf1d1
9 files changed
+227 -85

No files matched your search

@@ -32,10 +32,8 @@ import java.util.Map;
public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
private static final String TAG = "FaceclawComm";
// The EvenHub image container is a memory carrier only. Its 576x288 geometry
// gives the firmware separate 165888-byte display and reconstruction
// allocations: CFW reuses the former for its 640x480 packed-4bpp shadow and
// leaves the latter wholly available for compressed incoming messages.
// Local metadata for custom-command bookkeeping, not an EvenHub container.
// Submitted frames supply pixel geometry; the stock layout only captures input.
private static final BleProtocol.ImageTileOptions DASHBOARD_TILE =
new BleProtocol.ImageTileOptions("img00", 10, 0, 0, 576, 288);
@@ -782,8 +780,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
"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.
// Logical custom-message bytes; excludes length tag and packet framing.
final int wireBytes = message.message.length;
message.onSent = () -> {
benchmarkMessagesSent++;
@@ -1657,6 +1654,23 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
if (!BleProtocol.NOTIFY_CHAR_UUID.equals(uuid)) {
return;
}
if (data.length >= 7 && (data[6] & 255) == CfwTransport.SID) {
CfwTransport.Ack ack = CfwTransport.parseAck(data);
if (ack == null) return;
synchronized (lock) {
lastIncomingAtMs = SystemClock.elapsedRealtime();
for (OutboundMessage message : inFlightMessages) {
String ingress = message.isLeftArmMessage ? leftAddress : rightAddress;
if (address.equalsIgnoreCase(ingress) && message.acceptCfwAck(ack)) {
lastAckAtMs = lastIncomingAtMs;
resolveAckLocked(message, data);
break;
}
}
}
interruptibleSleep.interrupt();
return;
}
Log.d(TAG, "onNotification: address=" + address + " characteristicUuid=" + characteristicUuid + " data.length=" + data.length);
BleProtocol.ParsedFrame frame = BleProtocol.parseFrame(data);
int decodedWearState = BleProtocol.parseWearState(frame);
@@ -2455,7 +2469,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
}
private boolean canPrewriteCandidate(OutboundMessage message) {
if (message == null || !message.isLeftArmMessage) {
if (message == null || message.sid == CfwTransport.SID || !message.isLeftArmMessage) {
return false;
}
if (!"image".equals(message.kind)) {
@@ -2550,6 +2564,9 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
frames = Collections.singletonList(prewrittenFrames.get(prewrittenFrames.size() - 1));
prewrittenMessage = null;
prewrittenFrames = Collections.emptyList();
} else if (message.sid == CfwTransport.SID) {
frames = CfwTransport.frame(message.message, message.magic, CfwTransport.BOTH,
bleManager.getNegotiatedMtu(writeAddress));
} else {
frames = BleProtocol.framePb(
message.message,
@@ -2748,10 +2765,10 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
}
private void enqueueCreateLayoutLocked() {
// New session/container: re-assert the firmware-debug-flags overlay once
// New session: re-assert the firmware-debug-flags overlay once
// the layout is ready (the mode-7 send is gated on this having reset).
firmwareDebugFlagsLastSent = -1;
OutboundMessage message = messageBuilder.createLayout(DASHBOARD_TILE);
OutboundMessage message = messageBuilder.createLayout();
message.onAck = () -> {
startupProbePending = false;
clearMessagesOfKindLocked("startup-text-probe");
@@ -2796,10 +2813,9 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
}
/**
* Send the CFW mode-7 diagnostic-flag control op to the dashboard container:
* Send the CFW mode-7 diagnostic-flag control op through the private stream:
* [7][2] to show the on-glasses debug-flag overlay, [7][1] to hide it. Uses the
* arbitrary-payload image path (no bmp/dedup/frame-timing interaction) and does
* nothing on stock firmware (which ignores unknown image modes).
* arbitrary-payload custom path (no bmp/dedup/frame-timing interaction).
*/
private void enqueueFirmwareDebugFlagsLocked() {
boolean show = firmwareDebugFlagsEnabled;
@@ -2900,7 +2916,6 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
}
BleImageOptimizer.TileImagePlan plan = new BleImageOptimizer.TileImagePlan(
0, DASHBOARD_TILE, packed, width, height, nextMapSessionId(), tex.payload);
plan.fragments = BleImageOptimizer.planImageFragments(plan.payload, ConnectionOptions.IMAGE_FRAGMENT_SIZE);
FrameTimings.getInstance().spanEnd(frameId, "texture-plan");
String texLog = "texture update " + (tex.fullFrame ? "full" : ("rects=" + tex.rectCount))
+ " glyphs=" + tex.drawnGlyphs + " runs=" + tex.runCount
@@ -2963,7 +2978,6 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
BleImageOptimizer.TileImagePlan plan = incrementalPayload != null
? new BleImageOptimizer.TileImagePlan(0, DASHBOARD_TILE, packed, width, height, nextMapSessionId(), incrementalPayload)
: new BleImageOptimizer.TileImagePlan(0, DASHBOARD_TILE, packed, width, height, nextMapSessionId());
plan.fragments = BleImageOptimizer.planImageFragments(plan.payload, ConnectionOptions.IMAGE_FRAGMENT_SIZE);
FrameTimings.getInstance().spanEnd(frameId, "compress-and-plan");
if (incrementalLog != null) {
FrameTimings.getInstance().log(frameId, incrementalLog);
@@ -2971,15 +2985,26 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
finishEnqueueDesiredImageLocked(plan, fingerprint, paintMs, frameId);
}
/** Shared tail of enqueueDesiredImageLocked: enqueue fragments, advance the delta base, log. */
/** Queue complete private commands, advance the delta base, and retain frame/ACK bookkeeping. */
private void finishEnqueueDesiredImageLocked(
BleImageOptimizer.TileImagePlan plan, String fingerprint, int paintMs, int frameId) {
int updateId = nextImageUpdateId++;
int messageCount = plan.fragments.size();
List<byte[]> commands = new ArrayList<>();
if (plan.payload.length <= CfwTransport.MAX_MESSAGE) {
commands.add(plan.payload);
} else {
// A noisy full frame can exceed the stream record limit. Repaint it
// with independently decodable bands, never fragments of zlib data.
commands.addAll(BleImageOptimizer.encodeFullFrameBands(
plan.packed, plan.width, plan.height, nextImageFrameId));
for (int i = 0; i < commands.size(); i++) {
nextImageFrameId = nextImageFrameId >= 0xfffe ? 1 : nextImageFrameId + 1;
}
}
int messageCount = commands.size();
imageUpdateStats.put(updateId, new BleImageOptimizer.ImageUpdateStats(paintMs, 1, frameId));
for (int i = 0; i < plan.fragments.size(); i++) {
BleProtocol.ImageFragment fragment = plan.fragments.get(i);
enqueueImageFragmentLocked(plan, fragment, fingerprint, updateId, i + 1, messageCount, true);
for (int i = 0; i < commands.size(); i++) {
enqueueCustomImageLocked(plan, commands.get(i), fingerprint, updateId, i + 1, messageCount);
}
// This frame is now the base for the next delta (it will be the firmware
// shadow once applied), even though it hasn't been acked yet — that is what
@@ -3019,16 +3044,16 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
logLine("queue " + message.label);
}
private void enqueueImageFragmentLocked(
private void enqueueCustomImageLocked(
BleImageOptimizer.TileImagePlan plan,
BleProtocol.ImageFragment fragment,
byte[] payload,
String fingerprint,
int updateId,
int messageNumber,
int messageCount,
boolean requestAck
int messageCount
) {
OutboundMessage message = messageBuilder.imageFragment(fragment, plan, requestAck, connectionOptions.sendImagesToLeft);
OutboundMessage message = messageBuilder.customMessage("image", payload,
"image " + plan.tile.name + "#" + messageNumber, plan.tileIndex, connectionOptions.sendImagesToLeft);
message.setImageUpdatePosition(updateId, messageNumber, messageCount);
message.onAck = () -> {
imageRetryAfterMs = 0;
@@ -42,6 +42,7 @@ public class FaceclawBleManager {
private final ConcurrentHashMap<String, Integer> servicesStatuses = new ConcurrentHashMap<>();
private final ConcurrentHashMap<String, CountDownLatch> mtuLatches = new ConcurrentHashMap<>();
private final ConcurrentHashMap<String, Integer> negotiatedMtus = new ConcurrentHashMap<>();
private final ConcurrentHashMap<String, Integer> mtuStatuses = new ConcurrentHashMap<>();
private final ConcurrentHashMap<String, CountDownLatch> descriptorLatches = new ConcurrentHashMap<>();
@@ -165,6 +166,7 @@ public class FaceclawBleManager {
connectLatches.remove(address);
connectResults.remove(address);
gattClients.remove(address, gatt);
negotiatedMtus.remove(address);
gatt.disconnect();
gatt.close();
return false;
@@ -200,6 +202,11 @@ public class FaceclawBleManager {
}
}
public int getNegotiatedMtu(String address) {
Integer mtu = negotiatedMtus.get(address);
return mtu == null ? 23 : mtu;
}
public boolean requestMtu(String address, int mtu, int timeoutMs) {
synchronized (gattLock(address)) {
CountDownLatch latch = new CountDownLatch(1);
@@ -390,6 +397,7 @@ public class FaceclawBleManager {
Object gattLock = gattLock(address);
synchronized (gattLock) {
BluetoothGatt gatt = gattClients.remove(address);
negotiatedMtus.remove(address);
if (gatt == null) {
return;
}
@@ -463,6 +471,7 @@ public class FaceclawBleManager {
Object gattLock = gattLock(address);
synchronized (gattLock) {
gattClients.remove(address, gatt);
negotiatedMtus.remove(address);
gatt.close();
}
dispatchConnectionState(address, false);
@@ -482,6 +491,7 @@ public class FaceclawBleManager {
@Override
public void onMtuChanged(BluetoothGatt gatt, int mtu, int status) {
String address = gatt.getDevice().getAddress();
if (status == BluetoothGatt.GATT_SUCCESS) negotiatedMtus.put(address, mtu);
mtuStatuses.put(address, status);
CountDownLatch latch = mtuLatches.remove(address);
if (latch != null) {
@@ -286,6 +286,22 @@ public final class BleImageOptimizer {
return out;
}
/** A full repaint in independently decodable commands below the uint16 record limit. */
static List<byte[]> encodeFullFrameBands(byte[] packed, int width, int height, int firstFid) {
if (width <= 0 || width > 640 || (width & 3) != 0 || height <= 0 || height > 480
|| (height & 1) != 0 || packed.length != width * height / 2) {
throw new IllegalArgumentException("unsupported custom framebuffer dimensions");
}
List<byte[]> commands = new ArrayList<>();
int fid = firstFid;
for (int top = 0; top < height; top += 64) {
commands.add(encodeMode3Rect(packed, width / 2, 0, top, width,
Math.min(64, height - top), fid));
fid = fid >= 0xfffe ? 1 : fid + 1;
}
return commands;
}
/**
* A CFW mode-8 multi-segment payload (`[8][count]` then per-rect
* `[len16][mode-3 submsg]`) carrying several tight rectangle deltas instead of
@@ -185,13 +185,11 @@ public class BleProtocol {
}
public static byte[] buildCreateMixedImagePage(int magic, ImageTileOptions[] tiles) {
/** Retain the text container for forwarded inputs, without an image container. */
public static byte[] buildCreateInputPage(int magic) {
List<byte[]> innerParts = new ArrayList<>();
innerParts.add(encodeVarintField(1, 1 + tiles.length));
innerParts.add(encodeVarintField(1, 1));
innerParts.add(encodeMessageField(3, encodeTextObject("dashboard", 1, 0, 0, 576, 288, " ", true)));
for (ImageTileOptions tile : tiles) {
innerParts.add(encodeMessageField(4, encodeImageObject(tile)));
}
innerParts.add(encodeVarintField(5, 10000));
byte[] inner = concat(innerParts);
return wrapEvenHub(0, magic, 3, inner);
@@ -0,0 +1,73 @@
package com.faceclaw.app;
import java.util.ArrayList;
import java.util.List;
/** Faceclaw/7 private length-prefixed stream, independent of EvenHub image framing. */
public final class CfwTransport {
public static final int SID = 0xf0;
public static final int BOTH = 3;
public static final int MAX_MESSAGE = 65535;
private CfwTransport() {}
/** One logical command per stream for now. Packets are bounded by actual ATT MTU. */
public static List<byte[]> frame(byte[] message, int streamId, int lenses, int mtu) {
if (message == null || message.length > MAX_MESSAGE || streamId < 0 || streamId > 255
|| lenses < 1 || lenses > BOTH || mtu < 23 || mtu > 517) {
throw new IllegalArgumentException("invalid CFW stream parameters");
}
int capacity = Math.min(252, mtu - 14);
byte[] stream = new byte[message.length + 2];
stream[0] = (byte) message.length;
stream[1] = (byte) (message.length >>> 8);
System.arraycopy(message, 0, stream, 2, message.length);
List<byte[]> packets = new ArrayList<>();
for (int offset = 0, index = 0; offset < stream.length; offset += capacity, index++) {
int count = Math.min(capacity, stream.length - offset);
byte[] packet = new byte[count + 11];
packet[0] = (byte) 0xaa;
packet[1] = 0x21;
packet[2] = (byte) (streamId + index);
packet[3] = (byte) (count + 3);
packet[4] = packet[5] = 1;
packet[6] = (byte) SID;
packet[8] = (byte) (lenses | (offset == 0 ? 0x80 : 0)
| (offset + count == stream.length ? 0x40 : 0));
System.arraycopy(stream, offset, packet, 9, count);
int crc = crc(packet, 8, count + 1);
packet[packet.length - 2] = (byte) crc;
packet[packet.length - 1] = (byte) (crc >>> 8);
packets.add(packet);
}
return packets;
}
public static int crc(byte[] data) { return crc(data, 0, data.length); }
private static int crc(byte[] data, int offset, int count) {
int crc = 0xffff;
for (int i = offset; i < offset + count; i++) {
crc ^= (data[i] & 255) << 8;
for (int bit = 0; bit < 8; bit++)
crc = ((crc << 1) ^ ((crc & 0x8000) != 0 ? 0x1021 : 0)) & 65535;
}
return crc;
}
private static int u16(byte[] data, int offset) {
return (data[offset] & 255) | ((data[offset + 1] & 255) << 8);
}
public static Ack parseAck(byte[] packet) {
if (packet == null || packet.length != 19 || (packet[0] & 255) != 0xaa
|| packet[1] != 0x12 || packet[3] != 11 || packet[4] != 1 || packet[5] != 1
|| (packet[6] & 255) != SID || packet[7] != 0 || packet[8] != 1
|| (packet[12] != 1 && packet[12] != 2)
|| crc(packet, 8, 9) != u16(packet, 17)) return null;
return new Ack(packet[9] & 255, u16(packet, 10), packet[12], u16(packet, 13), u16(packet, 15));
}
public static final class Ack {
public final int streamId, messageId, lens, size, checksum;
Ack(int streamId, int messageId, int lens, int size, int checksum) {
this.streamId = streamId; this.messageId = messageId; this.lens = lens;
this.size = size; this.checksum = checksum;
}
}
}
@@ -72,35 +72,18 @@ public class MessageBuilder {
String label,
boolean leftArm
) {
BleProtocol.ImageFragment fragment =
new BleProtocol.ImageFragment(0, payload, payload.length);
int magic = magicPool.allocate();
return new OutboundMessage(
kind,
label,
BleProtocol.SID_EVENHUB,
BleProtocol.FLAG_REQUEST,
magic,
BleProtocol.buildImageRawData(tile, sessionId, payload.length, fragment, magic),
ACK_TIMEOUT_MS,
-1,
leftArm
);
// Keep these arguments for source compatibility with existing callers;
// the private command no longer carries a tile, session, or image header.
return customMessage(kind, payload, label, -1, leftArm);
}
public OutboundMessage imageFragment(BleProtocol.ImageFragment fragment, BleImageOptimizer.TileImagePlan plan, boolean requestAck, boolean leftArm) {
int magic = requestAck ? magicPool.allocate() : 0;
return new OutboundMessage(
"image",
"image " + plan.tile.name + "#" + fragment.index,
BleProtocol.SID_EVENHUB,
BleProtocol.FLAG_REQUEST,
magic,
BleProtocol.buildImageRawData(plan.tile, plan.sessionId, plan.payload.length, fragment, magic),
ACK_TIMEOUT_MS,
plan.tileIndex,
leftArm
);
public OutboundMessage customMessage(String kind, byte[] payload, String label,
int tileIndex, boolean leftArm) {
if (payload == null || payload.length > CfwTransport.MAX_MESSAGE)
throw new IllegalArgumentException("CFW message exceeds uint16 length");
int streamId = magicPool.allocate();
return new OutboundMessage(kind, label, CfwTransport.SID, 0, streamId, payload,
ACK_TIMEOUT_MS, tileIndex, leftArm);
}
public OutboundMessage cfwCleanup(
@@ -179,7 +162,7 @@ public class MessageBuilder {
);
}
public OutboundMessage createLayout(BleProtocol.ImageTileOptions... tiles) {
public OutboundMessage createLayout() {
int magic = magicPool.allocate();
return new OutboundMessage(
"create-layout",
@@ -187,7 +170,7 @@ public class MessageBuilder {
BleProtocol.SID_EVENHUB,
BleProtocol.FLAG_REQUEST,
magic,
BleProtocol.buildCreateMixedImagePage(magic, tiles),
BleProtocol.buildCreateInputPage(magic),
ACK_TIMEOUT_MS,
-1,
false
@@ -12,6 +12,9 @@ public final class OutboundMessage {
final int tileIndex;
final boolean isLeftArmMessage;
int cfwAckLenses;
final int cfwChecksum;
int imageUpdateId;
int imageMessageNumber;
int imageMessageCount;
@@ -30,11 +33,21 @@ public final class OutboundMessage {
this.flag = flag;
this.magic = magic;
this.message = message == null ? new byte[0] : Arrays.copyOf(message, message.length);
this.cfwChecksum = sid == CfwTransport.SID ? CfwTransport.crc(this.message) : 0;
this.ackTimeoutMs = ackTimeoutMs;
this.tileIndex = tileIndex;
this.isLeftArmMessage = isLeftArmMessage;
}
/** Record only a matching processing ACK; completion requires both lenses. */
boolean acceptCfwAck(CfwTransport.Ack ack) {
if (ack == null || sid != CfwTransport.SID || magic != ack.streamId
|| ack.messageId != 0 || message.length != ack.size || cfwChecksum != ack.checksum
|| (ack.lens != 1 && ack.lens != 2)) return false;
cfwAckLenses |= ack.lens;
return cfwAckLenses == CfwTransport.BOTH;
}
void setImageUpdatePosition(int updateId, int messageNumber, int messageCount) {
this.imageUpdateId = updateId;
this.imageMessageNumber = messageNumber;