No description, website, or topics provided.
Switch branches/tags
Nothing to show
Clone or download
Latest commit 28579fe Nov 14, 2018
Failed to load latest commit information.
images Screen Sep 21, 2018
mchess Format-tests for web Nov 14, 2018
.gitignore Using npm for javascript stuff for now Nov 14, 2018
LICENSE MIT License added. Aug 25, 2018 Web agent included in diagram Nov 14, 2018 cleanup Nov 9, 2018


Alpha status License

python-mchess is a collections of libraries to work with Millennium's Chess Genius Exclusive chess board via the Chess Link interface.

It provides two layers of functionality:

  • A hardware driver for the Chess Genius Exclusive chess board, supporting piece recognition and leds via USB or Bluetooth LE
  • A sample implementation to connect arbitrary UCI engines to the chess board.

Currently, the following platforms are under development:

Linux Raspberry Pi macOS Windows
USB x x x x
Bluetooth LE x x

Alpha installation instructions

This project is under heavy development, and basically everything described below might change at some point.


python-mchess is written for Python 3.x

python-mchess board driver for Chess Link depends on PySerial and (Linux/Raspberry Pi only) BluePy

Optional UCI engine support

In order to use UCI engines with mchess, additionally python-chess is used.

pip3 install pyserial [bluepy] [python-chess]

Then clone the repository

git clone

Now configure some engines:

cd mchess/engines

Copy engine-template.json for each UCI engine to a file <engine-name>.json, and edit the fields 'name' and 'path'.

A sample content for stockfish in Linux would be: engines/stockfish.json:

    "name": "stockfish",
    "path": "/usr/bin/stockfish",
    "active": true

Note: Windows users need to use paths with \\ for proper json encoding.

Web client

The web agent requires python modules Flask, Flask-Sockets and gevent.

Node JS packet manager npm is needed to install the javascript dependencies:

cd mchess/web
npm install

This installs the dependencies Normalize.css and cm-chessboard.


Then in directory mchess, simply start from console:


This will start chess agents for the chess board, automatically detecting board hardware via USB or BLuetooth LE (Linux, Raspberry PI only), and load the [first active] UCI engine (testet with Leela Chess Zero (Lc0) and Stockfish 9).

The web client can be reached at http://localhost:8001. From remote use http://computer-name:8001.

Note: Bluetooth LE hardware detection requires admin privileges for the one-time intial bluetooth scan. For first time start with Bluetooth LE support, use:

sudo python3

Once the board is found, stop the program and restart without sudo. You might want to set ownership for chess_link_config.json to your user-account, since the file will be rewritten, if the detected board orientation is changed.

All engine descriptions in directory 'engines' will now contain the default-UCI options for each engine. Those can be edited e.g. to enable tablebases or other UCI options.

Console mchess


On start, the current position from Chess Genius Exclusive board is imported and displayed on the console. Simply start making a move on the board, and the UCI engine will reply. During the time, the engine calculates, the best current line is displayed on the board for up to 3 half-moves (see preferences.json to enable/disable this feature).


                                |  |   Start and connect agents
                                +--------------------+   agents represent player activities
                        |                |               |                      |
         +---------------------+  +--------------+  +-------------------+ +--------------+
         | |  | |  | | | |
         +---------------------+  +--------------+  +-------------------+ +--------------+
                        |            uci-engines         I/O hardware      multiple web
                        |            Stockfish,                            clients
                        |            Lc0 etc.                
 -  -  -  -  -  -  -  - | -  -  -  -  -  -  -  -  -  -  -  -
               | |           Python 3 chess link library, can be
               +---------------+           reused for other projects without agents above
                  |         |
  +-------------------+  +----------------------+
  | |  | |
  +-------------------+  +----------------------+
         Chess Genius Exclusive board hardware
         via Chess Link

It whould be straight forward to include other agents at a later point.


API Documentation for


  • Thanks to Millennium GmbH for providing all information necessary for the implementation and for providing a ChessLink sample. See: for more information on ChessLink.