Web Bluetooth helper for GAN smart cubes (moves stream)
npm install @lfgf/cube-helper-webThis 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.
---
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
---
- 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
---
- 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.
---
``bash`
npm install @lfgf/cube-helper-web
Requires a browser with Web Bluetooth support (Chrome / Edge, HTTPS or localhost).
---
š ļø Usage
`ts
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:
`ts``
type CubeConnection = {
onMove(cb: (m: { move: string; ts: number }) => void): () => void;
disconnect(): Promise
};
---
ā ļø 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