brilliant-msg 2.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, CitizenOneX
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,122 @@
+# brilliant-msg
+
+A TypeScript package for handling rich application-level messages for [Brilliant Labs Frame and Halo](https://brilliant.xyz/) devices, including sprites, text, audio, IMU data, photos, and click events.
+
+[Frame SDK documentation](https://docs.brilliant.xyz/frame/frame-sdk/) | [GitHub Repo](https://github.com/brilliantlabsAR/brilliant_sdk/tree/main/webbluetooth/packages/brilliant-msg) | [API Docs](https://brilliantlabsAR.github.io/brilliant_sdk/brilliant-msg/api) | [Live Examples](https://brilliantlabsAR.github.io/brilliant_sdk/brilliant-msg/)
+
+## Installation
+
+```bash
+npm install brilliant-msg
+```
+
+## Usage
+
+```typescript
+import { BrilliantMsg, StdLua, TxCaptureSettings, RxPhoto, BrilliantDeviceType } from 'brilliant-msg';
+import frameApp from './lua/camera_frame_app.lua?raw';
+
+// Take a photo using the Frame camera and display it
+export async function run() {
+  const frame = new BrilliantMsg();
+
+  try {
+    const deviceId = await frame.connect();
+
+    // send the std lua files to Frame
+    await frame.uploadStdLuaLibs([StdLua.DataMin, StdLua.CameraMin]);
+
+    // Send the main lua application from this project to Frame that will run the app
+    await frame.uploadFrameApp(frameApp);
+
+    frame.attachPrintResponseHandler(console.log);
+
+    // "require" the main frame_app lua file to run it, and block until it has started.
+    // It signals that it is ready by sending something on the string response channel.
+    await frame.startFrameApp();
+
+    // hook up the RxPhoto receiver
+    const rxPhoto = new RxPhoto({});
+    const photoQueue = await rxPhoto.attach(frame);
+
+    // give Frame some time for the autoexposure to settle
+    await new Promise(resolve => setTimeout(resolve, 5000));
+
+    // Request the photo by sending a TxCaptureSettings message
+    await frame.sendMessage(0x0d, new TxCaptureSettings({}).pack());
+
+    const jpegBytes = await photoQueue.get();
+
+    // display the image on the web page
+    const img = document.createElement('img');
+    img.src = URL.createObjectURL(new Blob([jpegBytes], { type: 'image/jpeg' }));
+    document.body.appendChild(img);
+
+    // stop the photo listener and clean up its resources
+    rxPhoto.detach(frame);
+
+    frame.detachPrintResponseHandler()
+
+    // break out of the frame app loop and reboot Frame
+    await frame.stopFrameApp()
+  }
+  catch (error) {
+    console.error("Error:", error);
+  }
+  finally {
+    // Ensure the device is disconnected in case of an error
+    try {
+      await frame.disconnect();
+      console.log("Disconnected.");
+    } catch (disconnectError) {
+      console.error("Error during disconnection:", disconnectError);
+    }
+  }
+};
+```
+
+## Halo support
+
+Frame and Halo are detected automatically after `connect()`. The `BrilliantDeviceType` enum is re-exported from `brilliant-msg` for convenience.
+
+### Circular text layout (Halo)
+
+Halo has a circular display. Use `CircularTextLayout` with `TxTextPage` to fit text within the circle:
+
+```typescript
+import { TxTextPage, CircularTextLayout, RectangularTextLayout } from 'brilliant-msg';
+
+// For Halo's circular display
+const layout = new CircularTextLayout({ width: 640, height: 400, fontSize: 36 });
+
+// For Frame's rectangular display
+// const layout = new RectangularTextLayout({ width: 640, height: 400, fontSize: 36 });
+
+const page = new TxTextPage({ layout, text: 'Hello from Halo!' });
+const pageData = await page.rasterizeNextPage();
+if (pageData) {
+  // Send header packet, then each sprite
+  await frame.sendMessage(0x0a, pageData.pack());
+  for (const sprite of pageData.rasterizedSprites) {
+    await frame.sendMessage(0x0a, sprite.pack());
+  }
+}
+```
+
+### Click events (Halo)
+
+Halo sends tap/click events with single, double, and long-press types:
+
+```typescript
+import { RxClick, ClickType } from 'brilliant-msg';
+
+const rxClick = new RxClick();
+const clickQueue = await rxClick.attach(frame);
+
+const click = await clickQueue.get();
+if (click === ClickType.SINGLE) console.log('single click');
+if (click === ClickType.DOUBLE) console.log('double click');
+if (click === ClickType.LONG)   console.log('long press');
+
+rxClick.detach(frame);
+```

package/dist/async-queue.d.ts

@@ -0,0 +1,48 @@
+/**
+  A simple Promise-based queue used by the Rx classes
+  to manage asynchronous operations. This queue allows for
+  putting and getting values in a FIFO manner, handling
+  asynchronous operations without blocking the main thread.
+*/
+export declare class AsyncQueue<T> {
+    private promises;
+    private resolvers;
+    /**
+     * Constructs a new AsyncQueue instance.
+     * Initializes an empty queue for storing promises and their resolvers.
+     */
+    constructor();
+    private add;
+    /**
+     * Adds a value to the end of the queue.
+     * If there are pending `get` operations, this will resolve the oldest one.
+     * Otherwise, the value is stored until a `get` operation is called.
+     * @param value The value to add to the queue.
+     */
+    put(value: T): void;
+    /**
+     * Retrieves a value from the front of the queue.
+     * If the queue is empty, this method waits until a value is added.
+     * @returns A Promise that resolves with the value from the front of the queue.
+     */
+    get(): Promise<T>;
+    /**
+     * Checks if the queue is currently empty.
+     * This checks if there are any resolved or pending promises in the queue.
+     * @returns True if the queue is empty, false otherwise.
+     */
+    isEmpty(): boolean;
+    /**
+     * Gets the current number of items in the queue.
+     * This represents the number of promises (resolved or pending) currently held by the queue.
+     * @returns The number of items in the queue.
+     */
+    size(): number;
+    /**
+     * Clears all items from the queue.
+     * This removes all pending promises and their resolvers.
+     * Note: This does not explicitly reject pending promises from `get()` calls,
+     * so consumers awaiting `get()` might remain pending indefinitely if not handled.
+     */
+    clear(): void;
+}

package/dist/brilliant-msg.d.ts

@@ -0,0 +1,175 @@
+import { BrilliantBle } from 'brilliant-ble';
+/**
+ * Enum representing the available standard Lua libraries that can be uploaded.
+ */
+export declare enum StdLua {
+    DataMin = "stdDataMin",
+    AudioMin = "stdAudioMin",
+    CameraMin = "stdCameraMin",
+    CodeMin = "stdCodeMin",
+    IMUMin = "stdIMUMin",
+    ImageSpriteBlockMin = "stdImageSpriteBlockMin",
+    PlainTextMin = "stdPlainTextMin",
+    SpriteMin = "stdSpriteMin",
+    SpriteCoordsMin = "stdSpriteCoordsMin",
+    TapMin = "stdTapMin",
+    TextSpriteBlockMin = "stdTextSpriteBlockMin"
+}
+type BrilliantMsgDataHandler = (data: Uint8Array) => void;
+/**
+ * BrilliantMsg class handles communication with the Frame device.
+ * It wraps the BrilliantBle class and provides higher-level methods for uploading standard Lua libraries
+ * and Frame applications.
+ * It also manages the registration and unregistration of data response handlers for different Rx message types.
+ * Subscribers can register their own handlers for specific message codes.
+ */
+export declare class BrilliantMsg {
+    /** The underlying {@link BrilliantBle} instance used for Bluetooth Low Energy communication. */
+    ble: BrilliantBle;
+    private dataResponseHandlers;
+    /**
+     * Constructs an instance of the BrilliantMsg class.
+     * Initializes a new BrilliantBle instance and sets up internal data response handling.
+     */
+    constructor();
+    /**
+     * Connects to the Frame device and optionally runs the initialization sequence.
+     * Note: Print and Disconnect handlers should be set directly on the BrilliantBle instance
+     * (e.g., `frameMsg.ble.setPrintResponseHandler(...)`, `frameMsg.ble.setDisconnectHandler(...)`)
+     * or via `frameMsg.attachPrintResponseHandler(...)` before or after calling connect.
+     * @param initialize If true, runs the break/reset/break sequence after connecting. Defaults to true.
+     * @param connectOptions Options including name and namePrefix for device filtering.
+     * @returns The device ID or name if connection was successful.
+     * @throws Any exceptions from the underlying BrilliantBle connection or initialization.
+     */
+    connect(initialize?: boolean, connectOptions?: {
+        name?: string;
+        namePrefix?: string;
+    }): Promise<string | undefined>;
+    /**
+     * Disconnects from the Frame device if currently connected.
+     * @returns A Promise that resolves when disconnection is complete.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Checks if the Frame device is currently connected.
+     * @returns True if connected, false otherwise.
+     */
+    isConnected(): boolean;
+    /**
+     * Displays a short string of text on the Frame's display.
+     * The text is sanitized to escape single quotes and remove newlines.
+     * @param text The text to display. Defaults to an empty string.
+     * @returns A Promise that resolves with the print response from the device if `awaitPrint` is true (default), otherwise void.
+     */
+    printShortText(text?: string): Promise<string | void>;
+    /**
+     * Uploads specified standard Lua libraries to the Frame device.
+     * @param libs An array of {@link StdLua} enum values indicating which libraries to upload.
+     * @returns A Promise that resolves when all specified libraries have been uploaded.
+     */
+    uploadStdLuaLibs(libs: StdLua[]): Promise<void>;
+    /**
+     * Uploads a Frame application (Lua script) to the device.
+     * @param fileContent The content of the Lua application file as a string.
+     * @param frameFileName The target filename on the Frame device. Defaults to 'frame_app.lua'.
+     * @returns A Promise that resolves when the file has been uploaded.
+     */
+    uploadFrameApp(fileContent: string, frameFileName?: string): Promise<void>;
+    /**
+     * Starts a Frame application on the device by requiring its module name.
+     * @param frameAppName The name of the Frame application module (without .lua extension). Defaults to 'frame_app'.
+     * @param awaitPrint Whether to wait for a print response from the device. Defaults to true.
+     * @returns A Promise that resolves with the print response if `awaitPrint` is true, otherwise void.
+     */
+    startFrameApp(frameAppName?: string, awaitPrint?: boolean): Promise<string | void>;
+    /**
+     * Stops the currently running Frame application by sending a break signal.
+     * Optionally, it can also reset the device.
+     * @param reset If true, sends a reset signal after the break signal. Defaults to true.
+     * @returns A Promise that resolves when the signals have been sent.
+     */
+    stopFrameApp(reset?: boolean): Promise<void>;
+    /**
+     * Attaches a handler for print responses from the Frame device.
+     * This handler will be called with any text data printed by Lua scripts on the device.
+     * @param handler A function to handle the print response string. Defaults to `console.log`.
+     */
+    attachPrintResponseHandler(handler?: (data: string) => void | Promise<void>): void;
+    /**
+     * Detaches the currently set print response handler.
+     * After calling this, print responses from the device will no longer be processed by a custom handler.
+     */
+    detachPrintResponseHandler(): void;
+    /**
+     * Sends a message (msg_code and payload) to the Frame device.
+     * @param msgCode The message code (an integer identifying the message type).
+     * @param payload The Uint8Array payload for the message.
+     * @param showMe If true, prints the message being sent to the console. Defaults to false.
+     * @returns A Promise that resolves when the message has been sent.
+     */
+    sendMessage(msgCode: number, payload: Uint8Array, showMe?: boolean): Promise<void>;
+    /**
+     * Registers a handler for a subscriber interested in specific message codes from Frame.
+     * @param subscriber The subscriber object/identifier.
+     * @param msgCodes Array of message codes the subscriber is interested in.
+     * @param handler The function to call with the incoming data (Uint8Array).
+     */
+    registerDataResponseHandler(subscriber: any, msgCodes: number[], handler: BrilliantMsgDataHandler): void;
+    /**
+     * Unregisters all data response handlers associated with a specific subscriber.
+     * @param subscriber The subscriber object/identifier whose handlers should be removed.
+     */
+    unregisterDataResponseHandler(subscriber: any): void;
+    /**
+     * Internal method to handle incoming data responses from BrilliantBle (as Uint8Array)
+     * and dispatch to appropriate BrilliantMsg subscribers.
+     * @param data The incoming data response as a Uint8Array.
+     */
+    private _handleDataResponse;
+    /**
+     * Sends a Lua command string to the Frame device.
+     * This is a proxy to `BrilliantBle.sendLua()`.
+     * @param str The Lua command string to send.
+     * @param options Configuration options for sending the Lua command.
+     * @returns A Promise that resolves with the print response if `awaitPrint` is true, otherwise void.
+     */
+    sendLua(str: string, options?: {
+        showMe?: boolean;
+        awaitPrint?: boolean;
+        timeout?: number;
+    }): Promise<string | void>;
+    /**
+     * Sends raw data to the device.
+     * @param data The Uint8Array payload to send.
+     * @param options Configuration options.
+     * @returns A Promise that resolves with the Uint8Array data response if awaitData is true, or void.
+     */
+    sendData(data: Uint8Array, options?: {
+        showMe?: boolean;
+        awaitData?: boolean;
+        timeout?: number;
+    }): Promise<Uint8Array | void>;
+    /**
+     * Sends a reset signal to the Frame device.
+     * This is a proxy to `BrilliantBle.sendResetSignal()`.
+     * @param showMe If true, prints a message to the console indicating the signal was sent. Defaults to false.
+     * @returns A Promise that resolves when the signal has been sent.
+     */
+    sendResetSignal(showMe?: boolean): Promise<void>;
+    /**
+     * Sends a break signal (Ctrl+C) to the Frame device.
+     * This is a proxy to `BrilliantBle.sendBreakSignal()`.
+     * @param showMe If true, prints a message to the console indicating the signal was sent. Defaults to false.
+     * @returns A Promise that resolves when the signal has been sent.
+     */
+    sendBreakSignal(showMe?: boolean): Promise<void>;
+    /**
+     * Gets the maximum payload size for sending data to the Frame device.
+     * This is a proxy to `BrilliantBle.getMaxPayload()`.
+     * @param isLua True if the payload is for a Lua command, false for other data types.
+     * @returns The maximum payload size in bytes.
+     */
+    getMaxPayload(isLua: boolean): number;
+}
+export {};