PixelsCpp — C++ Library & App for Pixels Dice

A C++ library and companion app for Pixels dice on Windows, using WinRT APIs for Bluetooth Low Energy communication.

Windows 10 version 1709 (Fall Creators Update) or later is required.

Fork Notice

This project was originally forked from GameWithPixels/PixelsWinCpp. After some attempts to contribute improvements upstream via pull requests with no response, I decided to make this repository fully independent and maintain it on my own.

This repo is no longer tracking upstream and may diverge significantly from the original project.

What's Changed

Since forking, this project has been substantially reworked:

• CMake build system — replaced the Visual Studio solution with a portable CMake build.
• System tray app — added a Windows tray application with a status window showing live die state, recent rolls, battery, and RSSI.
• Structured multi-die runtime — refactored into a shared runtime layer (DiceManager, DieConnection, ConfigManager) that supports both the CLI and tray app.
• BLE connection stability — disabled WinRT MaintainConnection (which silently loses GATT subscriptions), added event-driven disconnect detection with immediate reconnect, watchdog-based backoff, reconstructive reconnect, recovery scanning, and full BLE adapter reset as a last resort.
• Missed roll detection — detects rolls that occur during a disconnect via advertisement monitoring (debounced) and post-reconnect face comparison.
• Serialized BLE operations — per-die mutexes prevent race conditions in concurrent BLE calls.

This project includes:

• PixelsLib — A static C++ library for communicating with Pixels dice over BLE.
• Pixels — A console application for scanning, configuring, and reading dice rolls.
• PixelsTray — A Windows system tray application that runs in the background, connects to your configured dice, and displays live roll results.

Building

Prerequisites

• Windows 10 version 1709 or later
• Visual Studio 2022 (or later) with the C++ Desktop workload
• CMake 3.20 or later
• Windows 10 SDK (10.0.17134.0 or later)

Build Steps

1. Generate the build files:

   cmake -B build -G "Visual Studio 17 2022"

2. Build all targets:

   cmake --build build --config Debug

   Or build only the tray app:

   cmake --build build --config Debug --target PixelsTray

3. The built executables are located in build/bin/Debug/:

   
   • PixelsTray.exe — The tray application
   • Pixels.exe — The console application

PixelsTray (Tray Application)

PixelsTray is a Windows system tray application that connects to your Pixels dice and displays live roll results in the background.

First Launch

On first launch, if no dice configuration is found, a welcome dialog will guide you through setup:

Click OK to open the setup window where you can scan for and select your dice.

Dice Setup

The setup window scans for nearby Pixels dice. Wait for your dice to appear, select them, and click Save Setup:

This saves the selected dice IDs to pixels.cfg in the application directory.

Tray Icon

Once running, PixelsTray appears as an icon in the Windows system tray. Hover over it to see a quick summary of all dice:

The tooltip shows the connection status, battery level, current face, and last roll for each die.

Tray Menu Actions

Right-click the tray icon to access the menu:

The top of the menu shows a live summary for each die. Available actions:

• Show Status — Opens the Dice Status window
• Show Roll Log — Opens the live log window
• Rescan Dice — Restarts the BLE scanner to rediscover dice
• Setup Dice... — Opens the dice setup window to reconfigure your dice
• Export Config... — Save your current configuration to a file
• Import Config... — Load a configuration from a file
• Open Config Folder — Opens the folder containing the configuration files
• Quit — Disconnect all dice and exit the application

Dice Status Window

The status window provides a detailed live view of all connected dice:

For each die it shows:

• Status — Connection state (ready, connecting, disconnected)
• Battery — Current battery level
• Current — The face currently showing on the die
• Last Roll — The last recorded roll result
• Recent — History of recent roll results

Roll Log Window

The log window shows a live stream of all BLE events, roll state changes, and diagnostic messages:

This is useful for debugging connectivity issues or verifying that rolls are being detected correctly.

Configuration Files

PixelsTray uses two configuration files, both located in the application directory.

pixels.cfg

Stores the selected dice IDs. Created automatically by the setup process:

version=1
dice=0x35EDAF0D,0xBB55091C

• version — Config format version
• dice — Comma-separated list of Pixel IDs (hex format)

pixels.ini

Controls application behavior like logging. Edit this file with any text editor:

[Pixels]
; Set debug=true to see all log messages (default: false shows only roll results)
debug=true

; Set log_to_file=true to save logs to a file
log_to_file=true

; Path for log file (leave empty for default: pixels_log.txt in app folder)
log_file_path=

• debug — When true, shows all BLE messages and diagnostics. When false, shows only roll results.
• log_to_file — When true, writes all log output to a text file.
• log_file_path — Custom path for the log file. Leave empty to use the default (pixels_log.txt in the app folder).

Console Application (Pixels.exe)

The console app supports the following modes:

• --list — Scan and print nearby Pixels dice.
• --setup — Scan, choose 1 or 2 dice, and save pixels.cfg.
• --rolls-only — Print only roll result lines (minimal output).
• No arguments — Load pixels.cfg and connect to the configured dice.

Quickstart

1. Discover nearby dice:

   Pixels.exe --list

2. Choose your active dice and save config:

   Pixels.exe --setup

3. Run normally with the saved config:

   Pixels.exe

Documentation

See the library documentation here.

Documentation generated with Doxygen.

License

MIT