Handle coalesced envelope frames; trace truncated values (Samsung >64B issue)

Another developer reports Samsung devices truncating inbound notifications
larger than 64 bytes, and the missing-settings-reply issue indeed reproduces
only on the Samsung tablet. Every frame the tablet DID deliver was <=55 bytes;
a reply would only trip a 64-byte limit if it were bigger -- e.g. a fuller
first-reply snapshot, or a reply coalesced into one notification value with
one of the lens's own sid-0x80 notifies (11+55 = 66 bytes).

The coalescing case also exposed a latent app-side bug: parseFrame only ever
read the FIRST envelope in a notification value, so a second frame packed into
the same value was silently dropped even on healthy devices.

- BleProtocol.splitFrames(): split a notification value into its individual
  aa21/aa12 envelope frames (self-describing via the length byte), returning
  a trailing partial frame as-is so callers can log stack truncation.
- Device-info probe, flash-prompt communicator, and flasher control channel
  now process every frame in a value. The probe additionally logs multi-frame
  values (with the raw value size) and marks frames whose actual length falls
  short of the declared length as TRUNCATED, so the next tablet run can
  confirm whether the stack truncates or drops oversized values.

The existing first-request retries remain the workaround for replies the
Samsung stack drops outright. Known residual exposure, not addressed here:
the custom firmware's settings reply carries the capability string and is
well over 64 bytes in a single frame, so on affected Samsung devices the
main communicator would never see CFW capabilities; the durable fix is
firmware-side (chunk lens-to-phone notifications at <=64 bytes), since an
app cannot recover bytes the stack never delivers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016ZqzwmRQ3HQxasBz5rYyZV
This commit is contained in:
James BabcockandClaude Fable 5 committed 2026-08-23 19:47:57 -07:00
1 parent 3e440830a3
commit b952cc2269
4 files changed
+67 -13

No files matched your search

@@ -251,18 +251,32 @@ public class FaceclawDeviceInfoProbe implements FaceclawBleListener {
if (!BleProtocol.NOTIFY_CHAR_UUID.equalsIgnoreCase(characteristicUuid)) {
return;
}
BleProtocol.ParsedFrame frame = BleProtocol.parseFrame(data);
// One notification value can carry several envelope frames back to
// back; reading only the first would silently drop the rest.
List<byte[]> frames = BleProtocol.splitFrames(data);
if (frames.size() > 1) {
emitLog("rx " + address + " value carries " + frames.size() + " frames (raw " + data.length + " bytes)");
}
for (byte[] buf : frames) {
handleFrame(address, buf, data.length);
}
}
private void handleFrame(String address, byte[] buf, int rawValueLength) {
BleProtocol.ParsedFrame frame = BleProtocol.parseFrame(buf);
if (!frame.ok) {
emitLog("rx " + address + " unparseable frame len=" + data.length
+ " head=" + FaceclawFirmwareUtil.bytesToHex(java.util.Arrays.copyOf(data, Math.min(16, data.length))));
emitLog("rx " + address + " unparseable frame len=" + buf.length + " (raw value " + rawValueLength + ")"
+ " head=" + FaceclawFirmwareUtil.bytesToHex(java.util.Arrays.copyOf(buf, Math.min(16, buf.length))));
return;
}
// Log every control frame while diagnosing 2.2.9: sid/flag/type/magic
// plus a payload prefix is enough to reconstruct what the lens said.
emitLog(String.format("rx %s sid=0x%02x flag=0x%02x type=%d magic=%d frag=%d/%d len=%d pb=%s",
int declared = buf.length > 3 ? buf[3] & 0xff : 0;
String truncated = buf.length < 8 + declared ? " TRUNCATED(declared=" + declared + ")" : "";
emitLog(String.format("rx %s sid=0x%02x flag=0x%02x type=%d magic=%d frag=%d/%d len=%d%s pb=%s",
address, frame.sid, frame.flag, frame.msgType, frame.msgSeq,
data.length > 5 ? data[5] & 0xff : 0, data.length > 4 ? data[4] & 0xff : 0, frame.pb.length,
FaceclawFirmwareUtil.bytesToHex(java.util.Arrays.copyOf(frame.pb, Math.min(40, frame.pb.length)))));
buf.length > 5 ? buf[5] & 0xff : 0, buf.length > 4 ? buf[4] & 0xff : 0, frame.pb.length, truncated,
FaceclawFirmwareUtil.bytesToHex(java.util.Arrays.copyOf(frame.pb, Math.min(48, frame.pb.length)))));
if (frame.sid == BleProtocol.SID_UI_SETTING
&& BleProtocol.parseSettingsFirmwareInfo(frame.pb) != null) {
// Any settings frame carrying firmware versions answers the probe's
@@ -513,12 +513,16 @@ public class FaceclawFirmwareFlasher implements FaceclawBleListener {
public void onNotification(String address, String characteristicUuid, byte[] data) {
if (BleProtocol.NOTIFY_CHAR_UUID.equalsIgnoreCase(characteristicUuid)) {
// Control channel: only the security-auth response is awaited here.
BleProtocol.ParsedFrame frame = BleProtocol.parseFrame(data);
if (frame.ok && frame.sid == BleProtocol.SID_SECURITY_AUTH) {
synchronized (lock) {
if (authLatch != null && frame.msgSeq == pendingAuthMagic) {
authAckPb = frame.pb;
authLatch.countDown();
// A value can carry several envelope frames back to back (e.g. the
// response packed with one of the lens's own sid-0x80 notifies).
for (byte[] buf : BleProtocol.splitFrames(data)) {
BleProtocol.ParsedFrame frame = BleProtocol.parseFrame(buf);
if (frame.ok && frame.sid == BleProtocol.SID_SECURITY_AUTH) {
synchronized (lock) {
if (authLatch != null && frame.msgSeq == pendingAuthMagic) {
authAckPb = frame.pb;
authLatch.countDown();
}
}
}
}
@@ -343,7 +343,14 @@ public class FaceclawFlashPromptCommunicator implements FaceclawBleListener {
if (!BleProtocol.NOTIFY_CHAR_UUID.equalsIgnoreCase(characteristicUuid)) {
return;
}
BleProtocol.ParsedFrame frame = BleProtocol.parseFrame(data);
// A value can carry several envelope frames back to back.
for (byte[] buf : BleProtocol.splitFrames(data)) {
handleFrame(address, buf);
}
}
private void handleFrame(String address, byte[] buf) {
BleProtocol.ParsedFrame frame = BleProtocol.parseFrame(buf);
if (!frame.ok) {
return;
}
@@ -604,6 +604,35 @@ public class BleProtocol {
}
/**
* Split one notification value into individual `aa21`/`aa12` envelope
* frames. A value normally holds exactly one frame, but the firmware can
* pack several (each self-describing via the length byte at offset 3), and
* a frame that only reads the first would silently drop the rest. A value
* that does not start with an envelope, or a trailing partial frame
* (truncated by the stack — observed on a Samsung tablet for values over
* 64 bytes), is returned as-is so the caller can log it.
*/
public static List<byte[]> splitFrames(byte[] value) {
List<byte[]> out = new ArrayList<>();
if (value == null || value.length == 0) {
return out;
}
int offset = 0;
while (offset + 8 <= value.length
&& value[offset] == (byte) 0xaa
&& (value[offset + 1] == 0x21 || value[offset + 1] == 0x12)) {
int len = value[offset + 3] & 0xff;
int end = Math.min(value.length, offset + 8 + len);
out.add(Arrays.copyOfRange(value, offset, end));
offset = end;
}
if (offset < value.length) {
out.add(Arrays.copyOfRange(value, offset, value.length));
}
return out;
}
public static ParsedFrame parseFrame(byte[] buf) {
if (buf == null || buf.length < 10 || buf[0] != (byte) 0xaa || (buf[1] != 0x21 && buf[1] != 0x12)) {
return new ParsedFrame(false, 0, 0, new byte[0], -1, -1);