Add sound demo to Faceclaw; use CFW mode 6 (headerless 4bpp) for images

This commit is contained in:
James Babcock committed 2026-07-03 23:32:46 -07:00
1 parent 116e8891e7
commit acda9cdd7e
15 files changed
+262 -22

No files matched your search

@@ -243,6 +243,30 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
interruptibleSleep.interrupt();
}
/** Play one quantized buzzer tone via CFW load_image_z mode 5 kind 1. */
public void playBuzzerNote(int note, int oct, int beat) {
synchronized (lock) {
if (!running || !sessionReady || !fixedLayoutCreated) {
logLine("skip buzzer note; session not ready");
return;
}
byte[] payload = BleProtocol.buildBuzzerNotePayload(note, oct, beat);
OutboundMessage message = messageBuilder.imagePayload(
DASHBOARD_TILE,
nextMapSessionId(),
payload,
"buzzer note=" + note + " oct=" + oct + " beat=" + beat,
connectionOptions.sendImagesToLeft
);
message.onTimeout = () -> {
handleTransportFailure("buzzer note ack timeout");
};
pendingMessages.addLast(message);
logLine("queue " + message.label);
}
interruptibleSleep.interrupt();
}
public Bitmap createPreviewBitmap(int[] colors, int width, int height) {
if (colors == null) {
throw new IllegalArgumentException("colors are required");
@@ -74,7 +74,7 @@ public final class BleImageOptimizer {
final int tileIndex;
final BleProtocol.ImageTileOptions tile;
final byte[] bmp; // raw 4bpp BMP, kept for the displayed-tile dedup cache
final byte[] payload; // bytes actually streamed: zlib BMP when it shrinks, else == bmp
final byte[] payload; // bytes actually streamed: mode-6 zlib 4bpp when it shrinks, else == bmp
final int sessionId;
List<BleProtocol.ImageFragment> fragments = Collections.emptyList();
@@ -88,27 +88,24 @@ public final class BleImageOptimizer {
}
/**
* zlib-deflate a tile BMP for transmission when CFW image decompression is
* enabled and it actually shrinks the payload. The CFW's load_image_z
* inflates any image buffer whose first byte is a zlib stream (CM nibble 8);
* a raw BMP (starts 0x42) is loaded unchanged, so the raw fallback is always
* safe and mixing raw/compressed tiles is fine. java.util.zip.Deflater's
* default is the zlib wrapper (2-byte header + adler32) at windowBits 15,
* matching the firmware inflate.
* zlib-deflate headerless 4bpp pixels for CFW load_image_z mode 6 when it
* shrinks the payload. Wire format: [6][zlib stream]. A raw BMP (starts 'B')
* is sent verbatim when compression does not help.
*/
static byte[] maybeCompress(byte[] bmp) {
if (!ConnectionOptions.COMPRESS_IMAGES_ZLIB || bmp == null || bmp.length == 0) {
if (bmp == null || bmp.length == 0) {
return bmp;
}
byte[] z = deflate(bmp);
// CFW wire format: a compressed payload is [mode byte][zlib stream]. Mode 1
// = zlib of a 4bpp BMP (load_image_z inflates it and hands the BMP to the
// stock loader). A raw BMP (starts 'B') is still sent verbatim.
if (z == null || z.length + 1 >= bmp.length) {
byte[] packed = BmpUtil.pack4bppFromBmp(bmp);
if (packed.length == 0) {
return bmp;
}
byte[] z = deflate(packed);
if (z == null || z.length + 1 >= packed.length) {
return bmp;
}
byte[] out = new byte[z.length + 1];
out[0] = 1;
out[0] = 6;
System.arraycopy(z, 0, out, 1, z.length);
return out;
}
@@ -121,6 +121,14 @@ public class BleProtocol {
return wrapEvenHub(5, magic, 9, concat(inner));
}
/** CFW load_image_z mode 5 kind 1: play one quantized buzzer note. */
public static byte[] buildBuzzerNotePayload(int note, int oct, int beat) {
int clampedNote = Math.max(1, Math.min(7, note));
int clampedOct = Math.max(0, Math.min(3, oct));
int clampedBeat = Math.max(1, Math.min(255, beat));
return new byte[] {5, 1, (byte) clampedNote, (byte) clampedOct, (byte) clampedBeat};
}
public static byte[] buildImageRawData(ImageTileOptions tile, int sessionId, int totalSize, ImageFragment fragment, int magic) {
List<byte[]> inner = new ArrayList<>();
inner.add(encodeVarintField(1, tile.containerId));
@@ -19,11 +19,6 @@ public class ConnectionOptions {
public static final int BATTERY_REFRESH_INTERVAL_MS = 5 * 60_000;
public static final int BATTERY_INPUT_QUIET_MS = 5_000;
public static final int IMAGE_FRAGMENT_SIZE = 3800;
// Stream image tiles as zlib(DEFLATE)-compressed BMPs. REQUIRES the custom
// firmware (load_image_z inflates any image buffer that starts with a zlib
// stream; a raw BMP is loaded unchanged). Turn OFF when talking to stock
// firmware, which would reject the compressed bytes as an invalid BMP.
public static final boolean COMPRESS_IMAGES_ZLIB = true;
public static final int IMAGE_RETRY_DELAY_MS = 2_000;
public static final int MAX_CONSECUTIVE_ACK_TIMEOUTS = 8;
public static final int EVEN_APP_WRITE_FAILURE_WINDOW_MS = 15_000;
@@ -54,6 +54,29 @@ public class MessageBuilder {
);
}
public OutboundMessage imagePayload(
BleProtocol.ImageTileOptions tile,
int sessionId,
byte[] payload,
String label,
boolean leftArm
) {
BleProtocol.ImageFragment fragment =
new BleProtocol.ImageFragment(0, payload, payload.length);
int magic = magicPool.allocate();
return new OutboundMessage(
"sound",
label,
BleProtocol.SID_EVENHUB,
BleProtocol.FLAG_REQUEST,
magic,
BleProtocol.buildImageRawData(tile, sessionId, payload.length, fragment, magic),
ACK_TIMEOUT_MS,
-1,
leftArm
);
}
public OutboundMessage imageFragment(BleProtocol.ImageFragment fragment, BleImageOptimizer.TileImagePlan plan, boolean requestAck, boolean leftArm) {
int magic = requestAck ? magicPool.allocate() : 0;
return new OutboundMessage(
@@ -116,4 +116,45 @@ public class BmpUtil {
| ((bmp[12] & 0xff) << 16)
| ((bmp[13] & 0xff) << 24);
}
/**
* Strip the BMP header and row padding, producing the headerless 4bpp wire
* format expected by CFW load_image_z mode 6: top-down rows, stride =
* ceil(width/2), high nibble = left pixel.
*/
public static byte[] pack4bppFromBmp(byte[] bmp) {
if (bmp == null || bmp.length < 0x36 || bmp[0] != 0x42 || bmp[1] != 0x4d) {
return new byte[0];
}
int width = readUint32Le(bmp, 18);
int heightSigned = readInt32Le(bmp, 22);
int height = heightSigned < 0 ? -heightSigned : heightSigned;
int pixelOffset = readBmpPixelOffset(bmp);
if (width <= 0 || height <= 0 || pixelOffset < 0 || pixelOffset >= bmp.length) {
return new byte[0];
}
int packedStride = (width + 1) >> 1;
int bmpStride = (packedStride + 3) & ~3;
if (pixelOffset + (long) bmpStride * height > bmp.length) {
return new byte[0];
}
byte[] out = new byte[packedStride * height];
for (int y = 0; y < height; y++) {
int srcY = height - 1 - y;
int srcRow = pixelOffset + srcY * bmpStride;
System.arraycopy(bmp, srcRow, out, y * packedStride, packedStride);
}
return out;
}
private static int readUint32Le(byte[] buf, int offset) {
return (buf[offset] & 0xff)
| ((buf[offset + 1] & 0xff) << 8)
| ((buf[offset + 2] & 0xff) << 16)
| ((buf[offset + 3] & 0xff) << 24);
}
private static int readInt32Le(byte[] buf, int offset) {
return readUint32Le(buf, offset);
}
}
+8
View File
@@ -155,6 +155,7 @@ class DashboardController {
setTranscribeRenderActive: (active) => this.setTranscribeRenderActive(active),
startDedicatedVoiceInput: (mode) => this.startDedicatedVoiceInput(mode),
stopDedicatedVoiceInput: () => this.stopDedicatedVoiceInput(),
playBuzzerNote: (note, oct, beat) => this.playBuzzerNote(note, oct, beat),
});
this.offAndroidNotification = onAndroidNotificationPosted((notificationKey) => {
void this.handleAndroidNotificationPosted(notificationKey).catch((error) => {
@@ -674,6 +675,13 @@ class DashboardController {
this.startVoiceControlIfEnabled();
}
private async playBuzzerNote(note: number, oct: number, beat: number): Promise<void> {
if (this.phase !== "connected" || !this.communicator) {
return;
}
await this.communicator.playBuzzerNote(note, oct, beat);
}
private setStopwatchRenderActive(active: boolean): void {
if (!active || this.phase !== "connected" || !this.communicator) {
if (this.stopwatchRenderTimer) {
+10
View File
@@ -266,6 +266,16 @@ export class FaceclawCommunicatorBridge {
return this.enqueueJavaCall(() => Boolean(this.communicator.sendShutdown(exitMode)));
}
async playBuzzerNote(note: number, oct: number, beat: number): Promise<void> {
await this.enqueueJavaCall(() => {
this.communicator.playBuzzerNote(
Math.round(note),
Math.round(oct),
Math.round(beat),
);
});
}
async close(): Promise<void> {
await this.enqueueJavaCall(() => this.communicator.close());
}
+75
View File
@@ -0,0 +1,75 @@
import { getDefaultSmallFont } from "../../graphics/bdffont";
import { G2_LENS_HEIGHT, G2_LENS_WIDTH, GrayImage } from "../../graphics/image";
import { Layer, type DashboardInputEvent, type LayerContext } from "../layers";
const NOTE_NAMES = ["C", "D", "E", "F", "G", "A", "B"] as const;
const DEFAULT_BEAT = 4; // ~250ms at 62ms units
export class BuzzerDemoLayer implements Layer {
private note = 1;
private oct = 2;
paint(_ctx: LayerContext, _paintBelow: () => GrayImage): GrayImage {
const image = new GrayImage(G2_LENS_WIDTH, G2_LENS_HEIGHT, 0);
const font = getDefaultSmallFont();
image.drawText(font, 24, 20, "Buzzer demo", 200);
image.drawText(font, 24, 44, `Note: ${NOTE_NAMES[this.note - 1]} Octave: ${this.oct}`, 180);
image.drawText(font, 24, 68, "Scroll: change note", 150);
image.drawText(font, 24, 84, "Click: play note", 150);
image.drawText(font, 24, 252, "Double-click: back", 130);
const keyWidth = 64;
const keyY = 130;
const keyX = Math.floor((G2_LENS_WIDTH - keyWidth * NOTE_NAMES.length) / 2);
for (let i = 0; i < NOTE_NAMES.length; i++) {
const selected = i + 1 === this.note;
const x = keyX + i * keyWidth;
image.drawRect(x + 2, keyY, keyWidth - 4, 48, selected ? 220 : 80);
const label = NOTE_NAMES[i]!;
image.drawText(
font,
x + Math.max(4, Math.floor((keyWidth - font.measureText(label)) / 2)),
keyY + 18,
label,
selected ? 0 : 200,
);
}
return image;
}
async handleInput(event: DashboardInputEvent, ctx: LayerContext): Promise<void> {
switch (event.type) {
case "scroll-up":
this.advanceNote(1);
return;
case "scroll-down":
this.advanceNote(-1);
return;
case "click":
await ctx.actions.playBuzzerNote(this.note, this.oct, DEFAULT_BEAT);
return;
case "double-click":
ctx.stack.pop();
return;
default:
return;
}
}
private advanceNote(delta: number): void {
let next = this.note + delta;
if (next > 7) {
this.note = 1;
this.oct = Math.min(3, this.oct + 1);
return;
}
if (next < 1) {
this.note = 7;
this.oct = Math.max(0, this.oct - 1);
return;
}
this.note = next;
}
}
+15
View File
@@ -14,9 +14,11 @@ export type NightscoutSettings = {
siteUrl: string;
apiToken: string;
};
export type BatteryDisplayMode = "icon" | "percentage";
export type SystemCardSettings = {
showFaceclawLogo: boolean;
showBatteryIndicators: boolean;
batteryDisplayMode: BatteryDisplayMode;
showAndroidNotifications: boolean;
showSignalStrength: boolean;
};
@@ -197,6 +199,15 @@ export const showBatteryIndicatorsSetting = new ConfigSettingBoolean({
defaultValue: true,
});
export const batteryDisplayModeSetting = new ConfigSettingEnum<BatteryDisplayMode>({
id: "batteryDisplayMode",
label: "Battery display",
storageKey: "dashboard.systemCard.batteryDisplayMode",
defaultValue: "icon",
values: ["icon", "percentage"],
formatValue: batteryDisplayModeLabel,
});
export const showAndroidNotificationsSetting = new ConfigSettingBoolean({
id: "showAndroidNotifications",
label: "Show Android Notifications",
@@ -267,6 +278,10 @@ export function screenTimeoutLabel(value: ScreenTimeoutSetting): string {
return value === "never" ? "Never" : value;
}
export function batteryDisplayModeLabel(value: BatteryDisplayMode): string {
return value === "icon" ? "Icon" : "Percentage";
}
export function loadNightscoutSettings(): NightscoutSettings {
return {
siteUrl: nightscoutSiteUrlSetting.get(),
+1
View File
@@ -48,6 +48,7 @@ const dashboardActions: LayerActions = {
setTranscribeRenderActive: () => {},
startDedicatedVoiceInput: () => {},
stopDedicatedVoiceInput: () => {},
playBuzzerNote: () => {},
};
const dashboardFont = getDefaultSmallFont();
export const TOP_LEFT_MENU_LAYOUT = { x: 8, y: 8, width: 272, height: 128 };
+7
View File
@@ -10,6 +10,7 @@ import { TelepromptLayer } from "../apps/teleprompt";
import { StopwatchLayer } from "../apps/stopwatch";
import { TranscribeLayer } from "../apps/transcribe";
import { ScreenTestLayer } from "../apps/screen-test";
import { BuzzerDemoLayer } from "../apps/buzzer-demo";
import { AboutPage } from "./about-page";
import { GrayImage } from "~/graphics/image";
@@ -105,6 +106,12 @@ function createAppsMenuLayer(): MenuLayer {
ctx.stack.push(new ScreenTestLayer());
},
},
{
label: "Buzzer demo",
onSelect: (ctx) => {
ctx.stack.push(new BuzzerDemoLayer());
},
},
],
TOP_LEFT_MENU_LAYOUT,
);
+2 -1
View File
@@ -1,5 +1,5 @@
import { dashboardState, TOP_LEFT_MENU_LAYOUT } from "../dashboard";
import { dashboardSlotIds, enumSettingMenuItem, showSignalStrengthSetting, showAndroidNotificationsSetting, showBatteryIndicatorsSetting, showFaceclawLogoSetting, systemCardNameSetting, textSettingMenuItem, toggleSettingMenuItem, voiceControlEnabledSetting, dashboardSlotSettings, nightscoutSiteUrlSetting, nightscoutApiTokenSetting, screenTimeoutSetting } from "../dashboard-settings";
import { batteryDisplayModeSetting, dashboardSlotIds, enumSettingMenuItem, showSignalStrengthSetting, showAndroidNotificationsSetting, showBatteryIndicatorsSetting, showFaceclawLogoSetting, systemCardNameSetting, textSettingMenuItem, toggleSettingMenuItem, voiceControlEnabledSetting, dashboardSlotSettings, nightscoutSiteUrlSetting, nightscoutApiTokenSetting, screenTimeoutSetting } from "../dashboard-settings";
import { MenuLayer } from "../menu";
export function createSettingsMenuLayer(): MenuLayer {
@@ -84,6 +84,7 @@ function createSystemCardSettingsMenuLayer(): MenuLayer {
textSettingMenuItem(systemCardNameSetting),
toggleSettingMenuItem(showFaceclawLogoSetting),
toggleSettingMenuItem(showBatteryIndicatorsSetting),
enumSettingMenuItem(batteryDisplayModeSetting),
toggleSettingMenuItem(showAndroidNotificationsSetting),
toggleSettingMenuItem(showSignalStrengthSetting),
],
+35 -1
View File
@@ -7,7 +7,7 @@ import { type DashboardPluginCardBounds } from "../dashboard-plugins";
import { dashboardState } from "../dashboard";
import { getDefaultMediumFont, getDefaultSmallFont } from "~/graphics/bdffont";
import { getDashboardLogo } from "~/graphics/logo";
import { showAndroidNotificationsSetting, showBatteryIndicatorsSetting, showFaceclawLogoSetting, showSignalStrengthSetting, systemCardNameSetting } from "../dashboard-settings";
import { batteryDisplayModeSetting, showAndroidNotificationsSetting, showBatteryIndicatorsSetting, showFaceclawLogoSetting, showSignalStrengthSetting, systemCardNameSetting } from "../dashboard-settings";
const NOTIFICATION_ICON_SIZE = 24;
const SYSTEM_CARD_ITEM_HEIGHT = 38;
@@ -70,6 +70,10 @@ function systemCardFlowItemWidth(item: SystemCardFlowItem): number {
if (item.type === "notification") {
return NOTIFICATION_ICON_SIZE;
}
if (batteryDisplayModeSetting.get() === "percentage") {
const percentText = formatBatteryPercent(item.percentCharge);
return Math.max(smallFont.measureText(percentText), smallFont.measureText(item.label));
}
return Math.max(BATTERY_ICON_WIDTH, smallFont.measureText(item.label));
}
@@ -98,14 +102,44 @@ function addBatteryItem(
});
}
function formatBatteryPercent(percentCharge: number): string {
const clamped = Math.max(0, Math.min(100, Math.round(percentCharge)));
return `${clamped}%`;
}
function drawBatteryFlowItem(image: GrayImage, x: number, y: number, item: Extract<SystemCardFlowItem, { type: "battery" }>): void {
const itemWidth = systemCardFlowItemWidth(item);
const labelX = x + Math.max(0, ((itemWidth - smallFont.measureText(item.label)) / 2) | 0);
image.drawText(smallFont, labelX, y + BATTERY_ITEM_Y_OFFSET, item.label, 150);
if (batteryDisplayModeSetting.get() === "percentage") {
drawBatteryPercentFlowItem(image, x, y, item, itemWidth);
return;
}
const battery = drawBattery(item.percentCharge, item.isCharging);
image.bitBlt(battery, x + ((itemWidth - battery.width) / 2) | 0, y + 16 + BATTERY_ITEM_Y_OFFSET);
}
function drawBatteryPercentFlowItem(
image: GrayImage,
x: number,
y: number,
item: Extract<SystemCardFlowItem, { type: "battery" }>,
itemWidth: number,
): void {
const percentText = formatBatteryPercent(item.percentCharge);
const textWidth = smallFont.measureText(percentText);
const textX = x + Math.max(0, ((itemWidth - textWidth) / 2) | 0);
const textY = y + 16 + BATTERY_ITEM_Y_OFFSET;
if (item.isCharging) {
const padX = 2;
const padY = 1;
image.fillRect(textX - padX, textY - padY, textWidth + padX * 2, smallFont.lineHeight + padY * 2, 255);
image.drawText(smallFont, textX, textY, percentText, 0);
return;
}
image.drawText(smallFont, textX, textY, percentText, 200);
}
function formatDashboardDate(now: Date): string {
return `${WEEKDAYS[now.getDay()]} ${MONTHS[now.getMonth()]} ${now.getDate()} ${pad2(now.getHours())}:${pad2(now.getMinutes())}`;
}
+1
View File
@@ -18,6 +18,7 @@ export type LayerActions = {
setTranscribeRenderActive: (active: boolean) => Promise<void> | void;
startDedicatedVoiceInput: (mode: "wakeword" | "full") => Promise<void> | void;
stopDedicatedVoiceInput: () => Promise<void> | void;
playBuzzerNote: (note: number, oct: number, beat: number) => Promise<void> | void;
};
export type PaintBelow = () => GrayImage;