@systemic-games/pixels-web-connect

Pixels Web Connect

This is the Pixels package for front end web developers. It enables communications between Pixels dice and a web browser using Bluetooth Low Energy.

Find the latest published version on NPM.

Foreword

Pixels are full of LEDs, smarts and no larger than regular dice, they can be customized to light up when and how you desire. Check our website for more information.

Warning Before jumping into programming please make sure to read our Pixels developer's guide.

Please open a ticket on GitHub if you're having any issue.

Browser Support

This package relies on the Web Bluetooth API for accessing Bluetooth from the browser. At the time of writing only Chromium based browsers such as Chrome, Edge and Opera have support for these APIs.

On Linux, you need to enable Web Bluetooth support with this flag: chrome://flags/#enable-web-bluetooth.

Note: Currently all our testing is being done with Chrome on Windows.

Getting Started

To install the package:

npm i @systemic-games/pixels-web-connect

Start by calling the requestPixel function to request the user to select a Pixel die to connect to.

This function returns a Pixel object. Call the connect asynchronous method to initiate a Bluetooth connection with the die.

The Pixel class has a number of methods to retrieve information about the die state. It also let you add a listener for any Pixel message.

Communicating With Pixels

import {
    repeatConnect,
	requestPixel,
	Color,
} from "@systemic-games/pixels-web-connect";

// Ask user to select a Pixel
const pixel = await requestPixel();

// Connect to die
console.log("Connecting...");
await repeatConnect(pixel);

// Get last roll state
const rollState = pixel.rollState;
console.log(`=> roll state: ${rollState.state}, face up: ${rollState.face}`);

// Read RSSI (signal strength)
const rssi = await pixel.queryRssi();
console.log(`=> rssi: ${rssi}`);
// And battery level
console.log(`=> Battery: ${pixel.batteryLevel}%`);

// Make LEDs flash a color
await pixel.blink(Color.red);

// Add listener to get notified on rolls
pixel.addEventListener("roll", (face) => {
	console.log(`=> rolled face: ${face}`);
});

Playing Animations

Classes to manipulate animation data are available in a separate package: @systemic-games/pixels-edit-animation.

import {
  createDataSetForAnimation,
  EditAnimationRainbow,
} from "@systemic-games/pixels-edit-animation";

// Create a simple rainbow animation
const editDataSet = createDataSetForAnimation(
    new EditAnimationRainbow({
        duration: 3,
        count: 2,
        fade: 0.5,
    })
);

// And play it on the Pixel die
await pixel.playTestAnimation(editDataSet.toDataSet());

React Hooks

See the @systemic-games/pixels-react package.

Example

We've made a mini dice game "Odd Or Even", checkout the source code here.

Module documentation

To get more in depth information about this package see the module's export documentation here.

Documentation generated with TypeDoc.

Known Issues

On Windows 10, the OS notifies of a Bluetooth peripheral being disconnected a few seconds (around 4) before the peripheral actually gets the disconnection event. This will make a re-connection attempt to fail if made before that delay as the peripheral will still disconnect after this 4 seconds delay. Using repeatConnect() function is a good workaround as it will attempt to connect a few times before failing.

License

MIT

---

Made with Example TypeScript Package.