python-mchess

python-mchess is a collections of libraries to work with Millennium's Chess Genius Exclusive chess board via the Chess Link interface. Alternatively, an eOne board can be used that has the Chess Link interface built in.

Note: the client-side will be renamed to 'turquoise', hence main script is now turquoise.py

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:

State of the project

• With version 0.4.0 the old Flask stack has been replaced by aiohttp (the old version with is tagged as 0.3.0, has however a security problem)
• The python library used for bluetooth supports only Linux, an platform independent alternative is available with bleak, but prefers async model.

Installation instructions

The project requires Python 3.8 and later (tested with 3.11). Please use a Python virtual environment to install the dependencies:

git clone https://github.com/domschl/python-mchess
cd python-mchess
# In folder python-mchess:
python -m venv mchess
cd mchess
# Windows: Scripts\activate.bat
source bin/activate
# Now install dependencies:
python -m pip install -r requirements.txt
# On Linux, install bluepy, skip for macOS and Windows:
python -m pip install bluepy

Update notes

Version 0.4.1 uses a different web stack, using aiohttp. Use requirements.txt as described above to install the new dependencies. It works with the same configuration as the old flask-basked stack.

Notes on venv usage

To check, if you are running a venv environment:

pip -V
# should show something like:
# <some-path>/python-mchess/mchess/lib/python3.11/site-packages/pip (python 3.11)
# path should contain 'python-mchess/mchess'

• On Linxu/macOS use source bin/activate.
• On Windows, use Scripts\activate.bat instead of bin/activate to activate the environment. On Windows, the Scripts folder is hidden by default. Use dir /a to list all files and folders.
• To deactivate the virtual environment, use deactivate on Linux/macOS, or
• Scripts\deactivate.bat on Windows.

Web client

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

# In folder python-mchess:
cd mchess/web
npm install

This installs the dependencies cm-chessboard and charts.js.

Configuration

Now configure some engines:

# In folder python-mchess:
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
}

An example for lc0 (Leela Chess Zero) with CUDA backend:

  "name": "lc0",
  "path": "/home/user/lc0/build/release/lc0",
  "engine_params": ["--backend=cuda"],
  "active": true

Note: The field "engine_params" is optional and can contain a list of additional parameters for the engine that are given on start.

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

Start

Then in directory mchess, simply start from console:

python3 turquoise.py

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 16).

Enter help in terminal to get an overview of available console commands (e.g. switch sides, take back moves, analyze position).

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

Early alpha preview of web client "Turquoise"

Note: Bluetooth LE hardware detection either requires admin privileges for the one-time intial bluetooth scan, or the setcap command below.

Bluetooth LE board search without sudo (recommended)

# adapt path:
sudo setcap 'cap_net_raw,cap_net_admin+eip' PATH/TO/LIB/python3._x_/site-packages/bluepy/bluepy-helper
# e.g. for venv installation with python 3.11 (in directory python-mchess/mchess):
sudo setcap 'cap_net_raw,cap_net_admin+eip' lib/python3.11/site-packages/bluepy/bluepy-helper

# The simply start mchess, scanning is started automatically:
python3 turquoise.py

Bluetooth LE board search with sudo

If the above fails, try to scan once with sudo:

sudo python3 turquoise.py

If turqoise.py has been started with sudo, it is advisible to change the ownership of chess_link_config.json to the user account that is used for games, otherwise turquoise.py cannot update the configuration (e.g. orientation changes) automatically.

Restart the program, once the board has connected (the connection address is saved in chess_link_config.json)

Do NOT use sudo on subsequent starts, or the communication might fail. If scan was executed with sudo, then 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. (chown your-username chess_link_config.json)

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 output of python module, allows terminal interactions: enter 'help' for an overview of console commands

Usage

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).

Enter help on the terminal console to get an overview of commands, and see below for more customization options

Customization

Currrently, there doesn't exist much of a GUI to configure mchess, and configuration relies on a number of JSON files.

preferences.json, general options for mchess

• outdated! The documentation of preferences.json is not up-to-date.

chess_link_config.json, configuration options for Millennium ChessLink hardware

This file configures the Millennium chess board ChessLink hardware connection. This file is created during automatic hardware detection at start of mchess.py.

Sample chess_link_config.json for USB-connection

{
    "transport": "chess_link_usb",
    "address": "/dev/ttyUSB0",
    "orientation": true,
    "btle_iface": 0,
    "autodetect": true,
    "protocol_debug": false
}

Json files in mchess/engines

Currently mchess supports up to two concurrent UCI chess engines. Each engine needs a configuration file mchess/engines/<engine-name>.json. On first start mchess.py automatically searches for stockfish, komodo and crafty.

The mandatory fields in <engine-name>.json are:

Once the UCI engine is started for the first time, the UCI-options of the engine are enumerated and added to the <engine-name>.json config file. That allows further customization of each engine. Some commonly used options are:

Warning: all customizations are reset, if an engine-update changes the available UCI-options. If a new engine version introduces new UCI-options, all fields are reset to engine-defaults.

Additionally a file <engine-name>-help.json is auto-created, it contains descriptions for each UCI-option, and will be used in the future for an UCI-customization option.

Architecture

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

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

Troubleshooting

• Start with option -v to get more logging output, logs are written to file turquoise.log:

python3 turquoise.py -v

• Linux users: many distris require users to be be in group DIALOUT in order to access USB and serials.

usermod -aG dialout <username>

• ChessLink communication debug

Open chess_link_config.json and insert a line:

"protocol_debug": true,

like so:

{
  "protocol_debug": true,
  "transport": "chess_link_bluepy",
  "address": "xx:xx:xx:xx:xx:xx",
  "btle_iface": 0,
  "orientation": true,
  "autodetect": true
}

This will show bit-level communication with the ChessLink board.

History

• 2023-10-03: Version 0.4.1 removed Flask code completely, new aiohttp based stack should be drop-in replacement working with same configuration as 0.3.0 flask.
• 2023-10-03: Version 0.4.0 start development: Replaced outdated Flask web stack with aiohttp, fixing security problems
• 2023-08-19: Minimal house-keeping, support installation via venv and requirements.txt do make project accessible again.
• 2020-06-19: Main file renamed from mchess.py to turquoise.py. Major cleanup of internals, basis for extending functionality, v0.3.0
• 2020-04-28: Work started on updating changes in module depencies (especially the async interface python-chess)

Documentation

• Chess-JSON protocol used by agents and websocket clients: Chess Json. Note: protocol is still subject to change.
• API Documentation for chess_link.py

Important external projects used by this project

• python-chess: a pure Python chess library
• cm-chessboard: a chessboard rendered in SVG, coded in ES6. Views FEN, handles move input, animated, responsive, mobile friendly.
• bluepy: Python interface to Bluetooth LE on Linux
• Chess pieces by Cburnett
• charts.js

Acknowledgements

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