frame-ble
    Preparing search index...

    Class FrameBle

    Class for managing a connection to and transferring data to and from the Brilliant Labs Frame device over Bluetooth LE using WebBluetooth

    Index

    Constructors

    constructor

    Methods

    connect disconnect getMaxPayload isConnected sendBreakSignal sendData sendLua sendMessage sendResetSignal setDataResponseHandler setDisconnectHandler setPrintResponseHandler uploadFile uploadFileFromString

    Constructors

    • Creates an instance of FrameBle. The constructor is currently empty as most setup occurs during the connect method.

      Returns FrameBle

    Methods

    • Connects to a Frame device.

      Prompts the user to select a Bluetooth device if one is not already known or connected. Handles connection attempts, retries, and characteristic setup.

      Parameters

      • options: {
            name?: string;
            namePrefix?: string;
            numAttempts?: number;
            retryDelayMs?: number;
        } = {}

        Optional configuration for the connection process.

        • Optionalname?: string

          The exact name of the device to connect to.

        • OptionalnamePrefix?: string

          The prefix of the device name to filter by.

        • OptionalnumAttempts?: number

          The maximum number of connection attempts. Defaults to 5.

        • OptionalretryDelayMs?: number

          The delay in milliseconds between retry attempts. Defaults to 1000ms.

      Returns Promise<undefined | string>

      A promise that resolves with the name or ID of the connected device, or undefined if connection fails.

      Error if Web Bluetooth is not available, if device selection is cancelled, or if connection fails after all attempts.

    • Disconnects from the currently connected Frame device. If no device is connected, this method does nothing. It also triggers the handleDisconnect cleanup logic if not connected, or relies on the 'gattserverdisconnected' event if connected.

      Returns Promise<void>

      A promise that resolves once the disconnection process has been initiated, or immediately if already disconnected.

    • Gets the maximum payload size for a single BLE transmission. This value is determined after device connection. For Lua strings, the full maxPayload can be used. For data packets (which include a 0x01 prefix byte), the effective payload is maxPayload - 1.

      Parameters

      • isLua: boolean

        If true, returns the max payload for Lua strings. Otherwise, for data packets.

      Returns number

      The maximum payload size in bytes.

    • Checks if the Frame device is currently connected.

      Returns boolean

      True if the device is connected, false otherwise.

    • Sends a break signal (0x03) to the Frame device. This typically interrupts any currently running Lua script on the device.

      Parameters

      • showMe: boolean = false

        If true, logs the transmitted signal (hex format) to the console. Defaults to false.

      Returns Promise<void>

      A promise that resolves after a short delay post-transmission.

    • Sends raw data to the device. The data is prefixed with a 0x01 byte to distinguish it from Lua commands.

      Parameters

      • data: Uint8Array

        The raw application payload to send as a Uint8Array. This is the actual data without the prefix.

      • options: { awaitData?: boolean; showMe?: boolean; timeout?: number } = {}

        Optional configuration for sending data.

        • OptionalawaitData?: boolean

          If true, waits for a data response from the device. Defaults to false.

        • OptionalshowMe?: boolean

          If true, logs the transmitted data (including prefix, hex format) to the console. Defaults to false.

        • Optionaltimeout?: number

          The timeout in milliseconds to wait for a data response if awaitData is true. Defaults to 5000ms.

      Returns Promise<void | Uint8Array<ArrayBufferLike>>

      A promise that resolves with the Uint8Array data response if awaitData is true, or void otherwise.

      Error if not connected, if TX characteristic is not available, or if the data payload is too large.

    • Sends a Lua command string to the Frame device.

      Parameters

      • str: string

        The Lua command string to send.

      • options: { awaitPrint?: boolean; showMe?: boolean; timeout?: number } = {}

        Optional configuration for sending the Lua command.

        • OptionalawaitPrint?: boolean

          If true, waits for a print response from the device. Defaults to false.

        • OptionalshowMe?: boolean

          If true, logs the transmitted data (hex format) to the console. Defaults to false.

        • Optionaltimeout?: number

          The timeout in milliseconds to wait for a print response if awaitPrint is true. Defaults to 5000ms.

      Returns Promise<string | void>

      A promise that resolves with the print response string if awaitPrint is true, or void otherwise.

      Error if the Lua string payload is too large or if a timeout occurs while awaiting a print response.

    • Sends a multi-packet message to the device. This method handles chunking the payload and sending it in multiple BLE packets according to a specific protocol (message code, total size header, then data chunks).

      Parameters

      • msgCode: number

        A number (0-255) representing the message type or command.

      • payload: Uint8Array

        The Uint8Array data to send as the message payload.

      • showMe: boolean = false

        If true, logs details of each transmitted packet to the console. Defaults to false.

      Returns Promise<void>

      A promise that resolves when all parts of the message have been sent and acknowledged.

      Error if msgCode is out of range, payload is too large, or if max payload size is too small for the protocol.

    • Sends a reset signal (0x04) to the Frame device. This typically causes the device to restart its Lua environment.

      Parameters

      • showMe: boolean = false

        If true, logs the transmitted signal (hex format) to the console. Defaults to false.

      Returns Promise<void>

      A promise that resolves after a short delay post-transmission.

    • Sets or updates the handler for asynchronous data responses from the device.

      Parameters

      • handler: undefined | ((data: Uint8Array) => void | Promise<void>)

        The function to call when data (as Uint8Array) is received. Pass undefined to remove the current handler.

      Returns void

    • Sets or updates the handler for disconnection events.

      Parameters

      • handler: undefined | (() => void)

        The function to call when the device disconnects. Pass undefined to remove the current handler.

      Returns void

    • Sets or updates the handler for asynchronous print (string) responses from the device.

      Parameters

      • handler: undefined | ((data: string) => void | Promise<void>)

        The function to call when a print string is received. Pass undefined to remove the current handler.

      Returns void

    • A convenience method that calls uploadFileFromString. Uploads file content to a specified path on the Frame device.

      Parameters

      • fileContent: string

        The string content of the file to upload.

      • frameFilePath: string = "main.lua"

        The path on the Frame device where the file will be saved. Defaults to "main.lua".

      Returns Promise<void>

      A promise that resolves when the file upload is complete.

    • Uploads content to a file on the Frame device by sending Lua commands. The content is escaped and chunked to fit within payload limits.

      Parameters

      • content: string

        The string content to write to the file.

      • frameFilePath: string = "main.lua"

        The path to the file on the Frame device. Defaults to "main.lua".

      Returns Promise<void>

      A promise that resolves when the file upload is complete.

      Error if any step of the file upload process fails (e.g., opening file, writing chunk).

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods