node-smartplay

node-smartplay — A JavaScript/TypeScript module for LEGO Smart Play BLE devices

Introduction

node-smartplay lets you discover and interact with LEGO Smart Play devices over Bluetooth Low Energy.

Currently supports the Smart Brick (audio-equipped brick). Additional device types will be supported as they are discovered.

Sample Usage

const { SmartPlay } = require("node-smartplay");

const smartPlay = new SmartPlay();

smartPlay.on("discover", async (device) => { // Wait to discover a device
    console.log("Found device, connecting...");
    await device.connect();

    const info = device.info;
    console.log(`  Name:     ${info.name}`);
    console.log(`  Model:    ${info.model}`);
    console.log(`  Firmware: ${info.firmware}`);
    console.log(`  MAC:      ${info.mac}`);
    console.log(`  Battery:  ${device.battery}%`);
    console.log(`  Volume:   ${device.volume}`);

    await device.setVolumeLow(); // Set volume to low (10)
    console.log("Volume set to low");

    device.disconnect();
});

smartPlay.scan(); // Start scanning for Smart Play devices
console.log("Scanning for Smart Play devices...");

More examples in the examples/ directory.

Installation

Node.js v18+ required.

npm install node-smartplay --save

node-smartplay uses @stoprocent/noble for BLE. See noble prerequisites.

API

SmartPlay (Scanner)

Method	Description
scan()	Start scanning for Smart Play devices.
stop()	Stop scanning.
getDevice(uuid)	Get a discovered device by UUID.
getDevices()	Get all discovered devices.

Event	Description
discover	Emitted when a device is found. Provides a SmartBrickDevice instance.

SmartBrickDevice

Method	Description
connect()	Connect and perform the handshake sequence.
disconnect()	Disconnect from the device.
readBattery()	Read the current battery level (%).
readVolume()	Read the current volume level.
readModel()	Read the device model name.
readFirmwareRevision()	Read the firmware version string.
setVolume(level)	Set volume to a VolumeLevel value.
setVolumeHigh()	Set volume to high (100).
setVolumeMedium()	Set volume to medium (40).
setVolumeLow()	Set volume to low (10).
setName(name)	Set the device name (max 12 bytes UTF-8).
readRawRegister(register)	Read a raw register value for exploration.

Property	Type	Description
battery	number	Current battery level (%).
volume	number	Current volume level.
connected	boolean	Whether the device is connected.
info	SmartBrickInfo	Device identity (name, model, firmware, MAC, UUID).

Event	Description
battery	Emitted when the battery level changes.
volume	Emitted when the volume changes.
connectionState	Emitted when the charging/connection state changes.
disconnect	Emitted when the device disconnects.

Compatibility

Device	Status	Notes
Smart Brick	Supported	Battery, volume, naming, device info. Authentication not yet supported (requires LEGO backend signing).

Known Limitations

• Authentication — ECDSA P-256 challenge-response requires LEGO's backend signing server. Device info, volume, and naming work without auth. Firmware updates and factory reset require it.

• Docked only — Devices are only connectable while on the charging base. Undocked, they use BLE 5.4 PAwR for device-to-device play and aren't visible to BLE scanners.

• Rotating BLE addresses — The stable identifier is the MAC address, available via device.info.mac after connecting.

• Linux permissions — You may need to grant node access to the Bluetooth adapter.

Reverse Engineering Notes

The notes/ directory contains reverse engineering documentation for the Smart Play BLE protocol, hardware, backend API, and file transfer system.

Development

npm install
npm run build