brilliant-ble

Low-level library for Bluetooth LE connection to Brilliant Labs Frame and Halo devices via WebBluetooth.

Frame SDK documentation | GitHub Repo | API Docs | Live Examples

Installation

npm install brilliant-ble
Copy

Usage

import { BrilliantBle, BrilliantDeviceType } from 'brilliant-ble';

export async function run() {
  const ble = new BrilliantBle();

  const deviceName = await ble.connect();
  console.log(`Connected to ${deviceName} (${ble.type})`);

  ble.setPrintResponseHandler(console.log);

  // Send a break signal to stop any running Lua app
  await ble.sendBreakSignal();

  // Send Lua command — Frame and Halo share the same Lua API
  const luaCommand = "frame.display.text('Hello!', 1, 1)frame.display.show()print('done')";
  await ble.sendLua(luaCommand, { awaitPrint: true });

  await new Promise(resolve => setTimeout(resolve, 2000));

  // Halo-specific: remove main.lua from the device
  if (ble.type === BrilliantDeviceType.HALO) {
    await ble.sendRemoveSignal();
  }

  await ble.disconnect();
};
Copy

Device type detection

After connect() resolves, ble.type is set to a BrilliantDeviceType value:

Halo is detected automatically by the presence of its audio TX characteristic (UUID 7a230005-...).

Halo-specific APIs