- Create an API key on Lichess.org with the authorization
board:play, run the script with a crafted command line, start playing against opponents with your Chessnut board in bluetooth - In offline mode, record your OTB games by replaying all the moves, save the PGN in the same folder automatically
- In offline mode, lift your king to get an hint of move/threat or to play against your local UCI/XBoard engine
- Cheat sheet of the command line at the end of this README
If you want to play on Lichess.org with your Chessnut board, you need the official application for your smartphone over bluetooth with GPS and screen switched on (it does not work as a service). Their lost official application for PC does not support bluetooth and is not available on Linux. ChessConnect.de does not work with Lichess.org but Chess.com. Graham's driver consumes too much CPU on desktop and is just a library used offline by selected chess GUIs that are not mine. LucasChess does not recognize bluetooth and weights hundreds of megabytes for nothing. Lichess.org only supports DGT boards... STOP!
On contrary to DGT, the integration is obviously a pure mess by design while, as a customer, we just expect something working out of the box without effort! The requirement is to run a minimalistic daemon on PC that connects over bluetooth to play locally or on the open-source chess platform Lichess.org.
To integrate with Lichess.org, the first step was to communicate with the board, which is made possible by hbldh/bleak and some technical documentation at chessnutech/EasyLinkSDK. The second step was to emulate the existing DGT connector hosted on Lichess.org (a TypeScript reimplementation of andrescavallin/lichess-dgt-boards-browser) until we realized that it does not stream the opponent's moves and that there is no light on the DGT boards. Good reasons to buy a Chessnut though. Finally, the code switched to a full API integration with Lichess.org and received later offline capabilities to play against your computer without smartphone.
You bought a physical board to improve your OTB skills: time to make it easier!
- Buy a Chessnut Air/Air+/Pro (obvious)
- Buy a bluetooth dongle with BLE support for your computer
- Install Python
- Download/Clone this repository
- Run
pip install bleak chessorpip install -r requirements.txt - Create an API key on Lichess.org with the authorization
board:play - Write this API key in the options in file
chessnut_connector.py, or run the script with the option--apikey lip_XXX - Start your Chessnut board
- Run
python chessnut_connector.py --bell --apikey lip_XXX(python3under Linux) - Setup your position with the kings at last
- Start a new game on Lichess.org in a slow time control (15+10 is recommended)
- Verify that the pieces are correctly in place and eventually press the button "New game" of your board
Pros
- You can audit the source code
- The code is asynchronous and won't consume much CPU
- All the detected events from the board are parsable in plain text format (example below)
- Promotion, enpassant and castling can be played slowly
- Offline moves without AI can be taken back or overridden with the same piece
- Make use of the button "New game" on the edge of your board to force the current position at any moment
- You can record your OTB games by moving the pieces offline
- You don't need to look at your computer while you are playing: the lights and sounds are enough
- A tutor is integrated to suggest a move/threat after you lift your/his king, and provided that the game is not rated
- UCI/XBoard engines are supported (exe/py/js/jar)
- The elapsed move time is exported to PGN
Cons
- You can play slow time controls only because you have to move the opposite pieces on your own time
- You must validate each move without compensation or pre-move. Always wait for the bell (if enabled)
- Don't slide the pieces on the board. Lift them up and down
- Take away the taken piece first without sliding
- The lights are not used to show you the misplaced pieces
- The disconnections are not managed
- Chess960 is not fully supported, except 415 431 447 455 461 462 503 509 510 519 525 526 533 534 549 550 693 694
- Other board types are not supported. Refer to ChessConnect.de that has the widest implementation
The application is a daemon that outputs text in the console. It does all the technical communication for you after you did a short setup and understood the command line.
usage: python chessnut_connector.py [-h] [--device DEVICE] [--sampling SAMPLING] [--bell] [--ledpath]
[--apikey APIKEY] [--acks] [--offline] [--no-move-validation] [--no-pgn]
[--save-pgn] [--no-clock] [--tutor] [--half-hint] [--ai] [--engine ENGINE]
[--engine-xboard] [--engine-depth ENGINE_DEPTH] [--engine-time ENGINE_TIME]
[--engine-options ENGINE_OPTIONS] [--engine-eval]
Unofficial asynchronous Chessnut bluetooth connector for PC and Lichess.org
options:
-h, --help Show this help message and exit
--device DEVICE Bluetooth LE address of your favorite device for a faster connection
--sampling SAMPLING Seconds between each comparison of the board
--bell Ring the bell after each valid move
--ledpath Show the full LED path of a piece
--apikey APIKEY API key generated on Lichess.org that has the authorization board:play
--acks Show the technical acknowledgements (not recommended)
--offline Record a game offline
--no-move-validation Undoable moves in manual games
--no-pgn Disable the recording of the moves
--save-pgn Automatically save the ended games in PGN format in the same folder
--no-clock Do not save the elapsed move time in PGN
--tutor Enable the chess assistant (non-rated games only)
--half-hint Show the piece to move in tutor mode, not the full move
--ai Play locally against the computer
--engine ENGINE Path to the executable chess analyzer
--engine-xboard Use XBoard-v2 to communicate with the chess analyzer (UCI by default)
--engine-depth ENGINE_DEPTH Depth for the chess analysis
--engine-time ENGINE_TIME Max time in seconds for the chess analysis
--engine-options ENGINE_OPTIONS Options for the UCI engine in format "opt1=abc|opt2=123"
--engine-eval Show the evaluation on the chess analysis
The following sample log is a short overview of what you can get while playing with the application:
lichess Lichess.org API key verified
tech Detecting device...
tech Using device XX:XX:XX:XX:XX:XX
tech Connected to Chessnut XX:XX:XX:XX:XX:XX
tech Protocol: CNCA100_V205
tech Microcode: CNAIR_10_240928
tech Battery level: 45%
tech Reset the LEDs
tech Initializing the board
piece Board initialized from its current position
board r n b q k b n r
board p p p p p p p p
board . . . . . . . .
board . . . . . . . .
board . . . . . . . .
board . . . . . . . .
board P P P P P P P P
board R N B Q K B N R
fen rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR
lichess Board successfully linked to game XXXXXXXXXXXX
tech Reset the LEDs
lichess Listening for moves in game XXXXXXXXXXXX
move rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR e2e4 e2e4 white
lichess Move e2e4/e2e4 processed for game XXXXXXXXXXXX
pgn Recording a new game
pgn 1.e2e4 played
board r n b q k b n r
board p p p p p p p p
board . . . . . . . .
board . . . . . . . .
board . . . . P . . .
board . . . . . . . .
board P P P P . P P P
board R N B Q K B N R
fen rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR
tech Reset the LEDs
lichess Move received from the opponent
move - c7c5 - black
tech Setting up the LEDs
piece ! Piece "p" removed at c7
move rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR c7c5 c7c5 black
pgn 1...c7c5 played
board r n b q k b n r
board p p . p p p p p
board . . . . . . . .
board . . p . . . . .
board . . . . P . . .
board . . . . . . . .
board P P P P . P P P
board R N B Q K B N R
fen rnbqkbnr/pp1ppppp/8/2p5/4P3/8/PPPP1PPP/RNBQKBNR
tech Reset the LEDs
With the option --bell, the console generates a sound once a move is validated. The objective is to never look at the computer while you are playing. The console may be helpful if the board does not respond as expected.
- Replicate a terminated OTB game with assistance:
python chessnut_connector.py --device "XX:XX:XX:XX:XX:XX" --bell --tutor --engine "C:/chess/stockfish18.exe" --offline --no-move-validation --ledpath --save-pgn- Play in front of a human being, record the moves without assistance:
python chessnut_connector.py --device "XX:XX:XX:XX:XX:XX" --bell --offline --no-move-validation --save-pgn- Play online without assistance:
python chessnut_connector.py --device "XX:XX:XX:XX:XX:XX" --bell --apikey lip_XXX --ledpath- Play online, non-rated against bots with assistance:
python chessnut_connector.py --device "XX:XX:XX:XX:XX:XX" --bell --tutor --engine "C:/chess/stockfish18.exe" --apikey lip_XXX --ledpath- Play locally against UCI engine Stockfish:
python chessnut_connector.py --device "XX:XX:XX:XX:XX:XX" --bell --engine "C:/chess/stockfish18.exe" --engine-depth 8 --engine-options "Skill Level=10|UCI_LimitStrength=true|UCI_Elo=1500" --engine-eval --ai --ledpath --save-pgn- Play locally against an XBoard engine:
python chessnut_connector.py --device "XX:XX:XX:XX:XX:XX" --bell --engine "C:/chess/xboard.exe" --engine-xboard --engine-depth 8 --engine-eval --ai --ledpath --save-pgn- Unofficial asynchronous Chessnut bluetooth connector for PC and Lichess.org
- Copyright (C) 2026 ecrucru
- https://github.com/ecrucru/chessnut-connector
- GNU Affero General Public License version 3