Do message compression at the transport level, rather than in individual messages

This commit is contained in:
James Babcock committed 2026-09-16 22:47:56 -07:00
1 parent 33bfdcf1d1
commit 720f6af8f8
8 files changed
+224 -132

No files matched your search

@@ -266,6 +266,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
private final TextureCacheState textureCache = new TextureCacheState();
private final ArrayDeque<OutboundMessage> pendingMessages = new ArrayDeque<>();
private final CfwTransport[] cfwTransports = { new CfwTransport(), new CfwTransport() };
private final ArrayDeque<OutboundMessage> inFlightMessages = new ArrayDeque<>();
private OutboundMessage prewrittenMessage;
private List<byte[]> prewrittenFrames = Collections.emptyList();
@@ -1661,12 +1662,19 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
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);
if (message.sid == CfwTransport.SID && address.equalsIgnoreCase(ingress) && message.magic == ack.streamId) {
message.acceptCfwAck(ack);
Log.i(TAG, "CFW " + (ack.nack ? "NACK" : "ACK") + " id=" + ack.streamId
+ " ordinal=" + ack.messageId + " lens=" + ack.lens + " txseq=" + (data[2] & 255)
+ " size=" + ack.size + " crc=" + ack.checksum
+ " expected=" + message.message.length + "/" + message.cfwChecksum
+ " ackedLenses=" + message.cfwAckLenses
+ " ageMs=" + (lastIncomingAtMs - message.sentAtMs));
message.ackPayload = Arrays.copyOf(data, data.length);
break;
}
}
drainCfwAcknowledgementsLocked();
}
interruptibleSleep.interrupt();
return;
@@ -1989,6 +1997,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
audioCaptureActive = false;
faceclawWakePendingNonce = -1;
cfwCleanupDelivered = false;
for (CfwTransport transport : cfwTransports) transport.reset();
lastCfwCleanupAckMagic = 0;
lastFaceclawWakeLeaseQueuedAtMs = 0;
lastFaceclawFramebufferLeaseQueuedAtMs = 0;
@@ -2274,6 +2283,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
maybeFinishNoChangeDesiredFrame();
synchronized (lock) {
drainCfwAcknowledgementsLocked();
if (cfwCleanupDelivered) {
/* Successful mode 11 must be the last Faceclaw write. Drop
* anything a late external producer attempted to enqueue
@@ -2301,11 +2311,36 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
}
if (!inFlightMessages.isEmpty()) {
OutboundMessage oldest = inFlightMessages.peekFirst();
List<OutboundMessage> replay = CfwMessageWindow.replayWindow(inFlightMessages, now);
if (!replay.isEmpty()) {
logLine("CFW recovery: replay " + replay.size()
+ " unresolved message(s) from id=" + replay.get(0).magic);
for (OutboundMessage candidate : replay) {
if (candidate.cfwRetries >= CfwMessageWindow.MAX_RETRIES) {
handleTransportFailure("CFW recovery retry limit");
return 0;
}
logLine("CFW replay id=" + candidate.magic + " label=" + candidate.label
+ " cause=" + (candidate.cfwRetryPending ? "NACK"
: candidate.cfwAckLenses == CfwTransport.BOTH ? "ordered tail" : "missing ACK")
+ " ackedLenses=" + candidate.cfwAckLenses
+ " ageMs=" + (now - candidate.sentAtMs));
inFlightMessages.remove(candidate);
magicPool.release(candidate.sid, candidate.magic, candidate.label, "CFW replay");
candidate.prepareCfwReplay(magicPool.allocate());
}
for (int i = replay.size() - 1; i >= 0; --i) pendingMessages.addFirst(replay.get(i));
return 0;
}
if (oldest != null && oldest.ackDeadlineAtMs <= now) {
Log.i(TAG, "message timed out: " + oldest.label);
inFlightMessages.removeFirst();
logLine("message timed out: " + oldest.label);
logLine("message timed out: " + oldest.label + " sid=" + oldest.sid
+ " id=" + oldest.magic + " ackedLenses=" + oldest.cfwAckLenses
+ " ageMs=" + (now - oldest.sentAtMs));
magicPool.release(oldest.sid, oldest.magic, oldest.label, "timeout");
if (oldest.sid == CfwTransport.SID)
cfwTransports[oldest.isLeftArmMessage ? 0 : 1].reset();
handleAckTimeoutLocked(oldest);
return 0;
}
@@ -2565,7 +2600,9 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
prewrittenMessage = null;
prewrittenFrames = Collections.emptyList();
} else if (message.sid == CfwTransport.SID) {
frames = CfwTransport.frame(message.message, message.magic, CfwTransport.BOTH,
if (message.cfwRetries > 0) cfwTransports[message.isLeftArmMessage ? 0 : 1].reset();
frames = cfwTransports[message.isLeftArmMessage ? 0 : 1].encode(
message.message, message.magic, CfwTransport.BOTH,
bleManager.getNegotiatedMtu(writeAddress));
} else {
frames = BleProtocol.framePb(
@@ -2594,6 +2631,8 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
}
}
if (!result && message.sid == CfwTransport.SID)
cfwTransports[message.isLeftArmMessage ? 0 : 1].reset();
return result;
}
@@ -2681,6 +2720,18 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
}
/** Also drain on the worker: a clear/timeout may have removed a blocking
* head since the last notification. Fully ACKed controls must never reach
* the generic timeout path just because no further BLE reply arrived. */
private void drainCfwAcknowledgementsLocked() {
while (true) {
OutboundMessage first = CfwMessageWindow.acknowledgedHead(inFlightMessages);
if (first == null) return;
lastAckAtMs = SystemClock.elapsedRealtime();
resolveAckLocked(first, first.ackPayload);
}
}
private void resolveAckLocked(int sid, int magic, byte[] pb) {
Iterator<OutboundMessage> iterator = inFlightMessages.iterator();
while (iterator.hasNext()) {
@@ -2994,7 +3045,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
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.
// with independently decodable RLE bands below the decoded-message limit.
commands.addAll(BleImageOptimizer.encodeFullFrameBands(
plan.packed, plan.width, plan.height, nextImageFrameId));
for (int i = 0; i < commands.size(); i++) {
@@ -3730,6 +3781,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
lastFaceclawWakeLeaseQueuedAtMs = 0;
faceclawWakeControlSentCount = 0;
cfwCleanupDelivered = false;
for (CfwTransport transport : cfwTransports) transport.reset();
lastCfwCleanupAckMagic = 0;
wearState = -1;
displayedFingerprint = "";
@@ -1,11 +1,9 @@
package com.faceclaw.app;
import java.io.ByteArrayOutputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.zip.Deflater;
import android.util.Log;
public final class BleImageOptimizer {
@@ -79,7 +77,7 @@ public final class BleImageOptimizer {
public final byte[] packed;
public final int width;
public final int height;
final byte[] payload; // bytes actually streamed: mode-6 zlib(rle(4bpp))
final byte[] payload; // bytes actually streamed: mode-6 rle(4bpp)
final int sessionId;
List<BleProtocol.ImageFragment> fragments = Collections.emptyList();
@@ -113,7 +111,7 @@ public final class BleImageOptimizer {
* Build a mode-3 bounding-box incremental payload, or null when a full
* update should be sent instead (frames not comparable, or the changed
* region spans the whole screen). Wire format:
* [3][left/4][top/2][width/4][height/2][fid_lo][fid_hi][zlib(rle(headerless 4bpp region))]
* [3][left/4][top/2][width/4][height/2][fid_lo][fid_hi][rle(headerless 4bpp region)]
* The region is top-down rows of the NEW frame, stride width/2 bytes. The
* box is aligned so left/width are multiples of 4 pixels and top/height
* multiples of 2 rows, letting each coordinate fit one byte and avoiding
@@ -260,7 +258,7 @@ public final class BleImageOptimizer {
/**
* Encode one CFW mode-3 rectangle delta:
* [3][left/4][top/2][width/4][height/2][fid_lo][fid_hi][zlib(rle(box pixels))]
* [3][left/4][top/2][width/4][height/2][fid_lo][fid_hi][rle(box pixels)]
* left/width must be multiples of 4 (=> left>>1, width>>1 are whole bytes), top/
* height multiples of 2. The box pixels are top-down rows of `next` (4bpp packed,
* width>>1 bytes/row), run-length encoded before deflate. Shared by the single-bbox
@@ -273,7 +271,7 @@ public final class BleImageOptimizer {
for (int y = 0; y < boxHeight; y++) {
System.arraycopy(next, (top + y) * stride + (left >> 1), region, y * regionStride, regionStride);
}
byte[] compressed = deflate(rleEncode(region));
byte[] compressed = rleEncode(region);
byte[] out = new byte[7 + compressed.length];
out[0] = 3;
out[1] = (byte) (left / 4);
@@ -326,8 +324,7 @@ public final class BleImageOptimizer {
}
// Break-even tuning for the rect splitter. Splitting adds ~15 fixed bytes per
// rect (seglen + mode-3 header + fid + zlib framing) and loses cross-rect
// dictionary sharing, so only split across gaps big enough to pay for that.
// rect (seglen + mode-3 header + fid), so only split across gaps big enough to pay for that.
// Gaps are in the changed-mask's native units: whole 4bpp bytes (2px) for
// columns, rows for the vertical bands. Kept above the 4px/2px box alignment so
// aligned rects never overlap.
@@ -477,8 +474,8 @@ public final class BleImageOptimizer {
}
/**
* RLE- then zlib-compress headerless 4bpp pixels for CFW load_image_z mode 6.
* Wire format: [6][zlib(rle(4bpp pixels))]. Always use mode 6: the logical
* Run-length encode headerless 4bpp pixels for CFW load_image_z mode 6.
* Wire format: [6][rle(4bpp pixels)]. Always use mode 6: the logical
* image can be larger than its EvenHub carrier, so a raw BMP fallback would
* carry dimensions the legacy container loader cannot accept.
*/
@@ -486,7 +483,7 @@ public final class BleImageOptimizer {
if (packed == null || packed.length == 0) {
return packed;
}
byte[] z = deflate(rleEncode(packed));
byte[] z = rleEncode(packed);
byte[] out = new byte[z.length + 1];
out[0] = 6;
System.arraycopy(z, 0, out, 1, z.length);
@@ -495,7 +492,7 @@ public final class BleImageOptimizer {
/**
* Run-length encode packed 4bpp pixels for CFW modes 3 and 6, whose payload is
* zlib(rle(pixels)) rather than zlib(pixels). Runs are over the pixel NIBBLES of
* RLE tokens; deflate belongs to the transport. Runs are over the pixel NIBBLES of
* {@code pix} in wire order (high nibble = left pixel), including the pad nibble
* that ends each row at odd widths — i.e. {@code pix} read as 2*length nibbles.
* One token is:
@@ -543,35 +540,6 @@ public final class BleImageOptimizer {
return (i & 1) != 0 ? (b & 0x0f) : (b >> 4);
}
// Level 6: BEST_COMPRESSION cost 18-109ms per frame on the BLE worker,
// but BEST_SPEED inflated typical payloads from ~2.7KB past the 3800-byte
// fragment boundary, adding a whole extra ack round trip (~350ms). The
// default level keeps payloads under one fragment at about half the CPU.
// One long-lived Deflater per thread: constructing one allocates and
// initializes a native zlib stream, which is measurable at per-frame rates.
private static final ThreadLocal<Deflater> DEFLATER =
new ThreadLocal<Deflater>() {
@Override protected Deflater initialValue() {
return new Deflater(Deflater.DEFAULT_COMPRESSION);
}
};
private static byte[] deflate(byte[] data) {
Deflater deflater = DEFLATER.get();
try {
deflater.setInput(data);
deflater.finish();
ByteArrayOutputStream out = new ByteArrayOutputStream(Math.max(64, data.length / 3));
byte[] buf = new byte[4096];
while (!deflater.finished()) {
out.write(buf, 0, deflater.deflate(buf));
}
return out.toByteArray();
} finally {
deflater.reset();
}
}
public static final class ImageUpdateStats {
final int paintMs;
final int tileCount;
@@ -0,0 +1,38 @@
package com.faceclaw.app;
import java.util.ArrayList;
import java.util.List;
/** Ordered completion and go-back-N recovery for the custom-message window. */
final class CfwMessageWindow {
// Flappy capture: p99 ACK 63ms, max 77ms. Leave room for full-frame
// processing while recovering a lost reply well before the stock timeout.
static final int ACK_TIMEOUT_MS = 500;
static final int MAX_RETRIES = 3;
private CfwMessageWindow() {}
static OutboundMessage acknowledgedHead(Iterable<OutboundMessage> messages) {
for (OutboundMessage message : messages) {
if (message.sid != CfwTransport.SID) continue;
return !message.cfwRetryPending && message.cfwAckLenses == CfwTransport.BOTH ? message : null;
}
return null;
}
static List<OutboundMessage> replayWindow(Iterable<OutboundMessage> messages, long nowMs) {
List<OutboundMessage> replay = new ArrayList<>();
boolean failed = false;
for (OutboundMessage message : messages) {
if (message.sid != CfwTransport.SID) continue;
failed |= message.cfwRetryPending || (message.cfwAckLenses != CfwTransport.BOTH
&& message.ackDeadlineAtMs > 0 && message.ackDeadlineAtMs <= nowMs);
replay.add(message);
}
// A lost ACK, first fragment, or NACK can leave an older attempt
// unresolved. Replaying only the named failure strands that older
// attempt at the head until its timeout. Rewind the unresolved window.
if (!failed) replay.clear();
return replay;
}
}
@@ -1,26 +1,79 @@
package com.faceclaw.app;
import java.io.ByteArrayOutputStream;
import java.util.zip.Deflater;
import java.util.ArrayList;
import java.util.List;
/** Faceclaw/7 private length-prefixed stream, independent of EvenHub image framing. */
/** Faceclaw/10 records: clear flags, wire length and decoded CRC; persistent zlib body. */
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() {}
public static final int COMPRESSED = 4, RESET_CONTEXT = 8;
private final Deflater deflater = new Deflater();
private boolean resetPending = true;
private int previousLenses;
public CfwTransport() {}
public synchronized void reset() {
deflater.reset();
resetPending = true;
previousLenses = 0;
}
/** Compress only when writing, in exactly the order seen by the receiver. */
public synchronized List<byte[]> encode(byte[] message, int streamId, int lenses, int mtu) {
validate(message, streamId, lenses, mtu);
if (previousLenses != lenses) reset();
boolean reset = resetPending;
deflater.setInput(message);
ByteArrayOutputStream out = new ByteArrayOutputStream();
byte[] chunk = new byte[4096];
int count;
do {
count = deflater.deflate(chunk, 0, chunk.length, Deflater.SYNC_FLUSH);
out.write(chunk, 0, count);
} while (count == chunk.length);
byte[] body = out.toByteArray();
int flags = lenses | COMPRESSED | (reset ? RESET_CONTEXT : 0);
if (body.length == 0) flags &= ~COMPRESSED; // repeated empty sync flush
if (body.length > MAX_MESSAGE) {
// Incompressible maximum-size records still fit as raw records.
// The attempted deflate advanced history: reset both ends before reuse.
reset();
body = message;
flags = lenses | RESET_CONTEXT;
} else {
resetPending = false;
previousLenses = lenses;
}
return frameRecord(body, crc(message), streamId, flags, mtu);
}
private static void validate(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");
}
/** 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");
}
validate(message, streamId, lenses, mtu);
return frameRecord(message, crc(message), streamId, lenses | RESET_CONTEXT, mtu);
}
private static List<byte[]> frameRecord(byte[] body, int checksum, int streamId, int flags, int mtu) {
int lenses = flags & BOTH;
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);
byte[] stream = new byte[body.length + 5];
stream[0] = (byte) flags;
stream[1] = (byte) body.length;
stream[2] = (byte) (body.length >>> 8);
stream[3] = (byte) checksum;
stream[4] = (byte) (checksum >>> 8);
System.arraycopy(body, 0, stream, 5, body.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);
@@ -58,14 +111,16 @@ public final class CfwTransport {
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[6] & 255) != SID || packet[7] != 0 || (packet[8] != 1 && packet[8] != 3)
|| (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));
return new Ack(packet[8] == 3, packet[9] & 255, u16(packet, 10), packet[12], u16(packet, 13), u16(packet, 15));
}
public static final class Ack {
public final boolean nack;
public final int streamId, messageId, lens, size, checksum;
Ack(int streamId, int messageId, int lens, int size, int checksum) {
Ack(boolean nack, int streamId, int messageId, int lens, int size, int checksum) {
this.nack = nack;
this.streamId = streamId; this.messageId = messageId; this.lens = lens;
this.size = size; this.checksum = checksum;
}
@@ -83,7 +83,7 @@ public class MessageBuilder {
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);
CfwMessageWindow.ACK_TIMEOUT_MS, tileIndex, leftArm);
}
public OutboundMessage cfwCleanup(
@@ -6,13 +6,14 @@ public final class OutboundMessage {
final String label;
final int sid;
final int flag;
final int magic;
int magic;
final byte[] message;
final int ackTimeoutMs;
final int tileIndex;
final boolean isLeftArmMessage;
int cfwAckLenses;
int cfwAckLenses, cfwRetries;
boolean cfwRetryPending;
final int cfwChecksum;
int imageUpdateId;
@@ -39,13 +40,27 @@ public final class OutboundMessage {
this.isLeftArmMessage = isLeftArmMessage;
}
/** Record only a matching processing ACK; completion requires both lenses. */
/** NACK names this attempt's stream/message sequence, even without a decoded size. */
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;
|| ack.messageId != 0 || (ack.lens != 1 && ack.lens != 2)) return false;
if (ack.nack) {
cfwRetryPending = true;
return false;
}
if (message.length != ack.size || cfwChecksum != ack.checksum) return false;
cfwAckLenses |= ack.lens;
return cfwAckLenses == CfwTransport.BOTH;
return !cfwRetryPending && cfwAckLenses == CfwTransport.BOTH;
}
/** Replace an attempt atomically under the communicator lock. */
void prepareCfwReplay(int streamId) {
magic = streamId;
++cfwRetries;
cfwAckLenses = 0;
cfwRetryPending = false;
ackDeadlineAtMs = 0;
ackPayload = new byte[0];
}
void setImageUpdatePosition(int updateId, int messageNumber, int messageCount) {