BTCube Web

A TypeScript library for interacting with multiple models of bluetooth speedcubes via Web Bluetooth API. It is an evolution of the previous qysc-web package which only supported the QY-SC

This library is availible on the NPM registry at https://www.npmjs.com/package/btcube-web A sample app can be seen at https://simonkellly.github.io/btcube-web

Features

• Web Bluetooth integration for QYSC devices
• Support for MoYu V4/V5 and GAN legacy/V1/V2/V3 smart cubes
• Cube state management and manipulation
• Gyro support where available
• RxJS integration for reactive programming
• TypeScript support with full type definitions

This library follows closely to the standard set by gan-web-bluetooth and implements the qiyi smart cube protocol described at qiyi_smartcube_protocol with some help from qy-cube

Installation

npm install btcube-web
yarn add btcube-web
bun add btcube-web

Usage

There is a very basic sample-app within this repository, but the core usage can be seen below.

import { connectSmartCube } from 'btcube-web';

const cube = await connectSmartCube();

cube.events.moves.subscribe(move => {
  console.log('Cube Moved:', move);
});

await cube.commands.disconnect();

Upgrading to 2.0

Version 2.0 adds GAN support and completes the MoYu V4/V5 implementation. When upgrading:

• connectSmartCube() now resolves after a valid initial state and rejects failed or timed-out handshakes. Initial state and the latest information are replayed to new subscribers.
• The MAC provider callback remains supported. You can also pass an options object: connectSmartCube({ requestMacAddress: async device => prompt("Bluetooth MAC for " + device.name) }). GAN and MoYu require a real Bluetooth MAC when automatic discovery fails; the previous all-zero fallback is removed.
• Commands are explicitly typed. Use cube.commands.disconnect(), freshState() and sync() (only after physically solving the cube). Check optional commands before calling them, for example await cube.commands.requestBattery?.().
• events.info is an Observable, and includes device information as well as battery and gyro events. Narrow on event.type before reading variant-specific fields.
• Move timestamps are milliseconds. QiYi timestamps were previously raw ticks; device and local timestamps have separate clock origins. Missing timestamps remain absent, and recovered moves can be identified by recovered.
• Optional streams include orientation, history, connection, diagnostics and decoded protocol packets. Streams complete on disconnect; subscribe to connection to handle an unexpected disconnect.
• A state update does not imply a move event. Use events.state for the current pattern and events.moves for chronological turns; missing history triggers a state refresh rather than invented moves.

The sample app demonstrates connection options, battery events, live 3D gyro orientation, and optional gyro controls using the existing layout. Web Bluetooth requires a supported browser and HTTPS or localhost.

Development

This project uses Bun as the package manager and build tool.

bun install

bun run check

bun run build

bun publish

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.