cube-helper-web

This library was created as part of a personal experiment with smart cubes and Web Bluetooth.

A small, focused helper library that connects a GAN smart cube via Web Bluetooth and exposes cube movements as simple, semantic events.

This library intentionally abstracts away Bluetooth, encryption and device-specific protocols, allowing applications to consume cube moves (R, U', F2, etc.) with a minimal and stable API.

✨ Motivation

Working directly with smart cubes in the browser is harder than it should be.

Even with existing low-level libraries, applications still need to deal with:

• Web Bluetooth APIs
• RxJS event streams
• Device-specific event formats
• Noise and connection lifecycle

This project exists to separate concerns:

Device & protocol complexity → library
Application logic → consumer

🧩 What this library does

• Connects to a GAN smart cube using Web Bluetooth
• Listens to cube movement events
• Emits normalized cube moves (R, U', F2)
• Exposes a small, framework-agnostic API

❌ What this library does NOT do

• No UI
• No DOM access
• No game logic
• No cube state solving
• No Bluetooth abstractions for non-GAN devices

This is a thin, intentional adapter, not a full cube SDK.

🚀 Installation

npm install @lfgf/cube-helper-web

Requires a browser with Web Bluetooth support (Chrome / Edge, HTTPS or localhost).

🛠️ Usage

import { connectGanCubeMoves } from "@lfgf/cube-helper-web";

const cube = await connectGanCubeMoves();

const unsubscribe = cube.onMove(({ move }) => {
  console.log("Cube move:", move);
});

// later
await cube.disconnect();

🧠 API connectGanCubeMoves(): Promise

Returns a connection object with:

type CubeConnection = {
  onMove(cb: (m: { move: string; ts: number }) => void): () => void;
  disconnect(): Promise<void>;
};

⚠️ Browser requirements

• Chrome or Edge (Chromium)
• User must explicitly allow Bluetooth access
• Device selection is user-driven (browser security model)

🔧 Internals

Internally, this library wraps gan-web-bluetooth, translating low-level BLE/RxJS events into a stable, callback-based API.

This design allows applications to remain decoupled from:

• Bluetooth APIs
• RxJS
• Device-specific event shapes

📦 Use cases

• Cube training or analytics tools
• Creative or experimental browser-based projects
• Rapid prototyping with physical input devices

📄 License

MIT