ChessLink object

class chess_link.ChessLink(appque, name)

This implements the ‘Chess Link’ protocol for Millennium Chess Genius Exclusive and future boards compatible with that protocol.

For the details of the Chess Link protocol, please refer to: magic-link.md.

position array

This class refers to chess boards using the position 8x8 array. Field values: 1: white pawn, 2: w-knight, 3: w-bishop, 4: w-rook, 5: w-queen, 6: w-king, 0: empty square, -1; black pawn, -2: b-knight, -3: b-bishop, -4: b-rook, -5: b-queen, -6: b-king.

Communcation with the Chess Link board is asynchronous. Replies from the board are written to the python queue (appqueue) that is provided during instantiation.

Every message in appqueue is a short json string. Currently implemented are:

Version:

{'version': '01.04', 'actor': '<actor-name>'}

New game detected (board has been set to start position):

{'new game', '', 'actor': '<actor-name>', 'orientation': True}

Transport error:

{'error': '<error message>', 'actor': '<actor-name>'}

Board position has changed:

{'fen': fen, 'actor': '<actor-name>'}

See remarks on position2fen(): move counts, castling are not valid, only the position part should be used.

Valid move on board detected:

{'move': {'uci': '<uci-format move, e.g. e2e4>', 'fen': '<resulting fen position>', 
 'actor': '<actor-name>'}}

See remarks on position_to_fen(): move counts, castling are not valid, only the position part should be used.

In order for the board to detect valid move, a list of possible valid moves has to given to the board using move_from(). Typically, this list is generated using the python module python_chess. See chess_link_agent.py for an example.

__init__(appque, name)

Constructor, searches, configures and connectors to Chess Link compatible Millennium Chess Genius Exclusive or similar boards.

Parameters

• appque – a Queue that receive chess board events

• name – identifies this protocol

fen_to_position(fen)

Convert a FEN position into an 8x8 position array.

Note that the current implementation of position arrays does not maintain move-counts, castling stati or any history data.

Returns

8x8 position array.

get_debounce()

Asynchronuosly request the current debounce setting. The answer will be written to the queue appqueue given during initialization.

See see magic-link.md.

get_led_brightness_percent()

Asynchronuosly request the current led brightness setting. The answer will be written to the queue appqueue given during initialization.

See see magic-link.md.

get_orientation()

ChessLink tries to autodetect the orientation of the board by looking for initial start positions.

If the board has never been set to the initial start position, the orientation must be set using set_orientation().

get_position()

Asynchronuosly request the Chess Link board position. The answer will be written to the queue appqueue given during initialization.

By default, the Chess Link board sends a position to appqueue on all changes to the board position, so explicit calls to get_position() should not be required most of the times.

get_scan_time_ms()

Asynchronuosly request the current scan time setting. The answer will be written to the queue appqueue given during initialization.

See see magic-link.md.

get_version()

Asynchronuosly request the Chess Link version number. The answer will be written to the queue appqueue given during initialization.

move_from(fen, legal_moves, color, eval_only=False)

Register all legal moves possible in current position. Once the legal moves are registered, the background thread checks for board changes, and signals a legal move using the python queue appqueue given during initialization.

Non-legal changes or incomplete moves will cause the affected fields to blink continously.

Parameters

• fen – current position

• legal_moves – dictionary of key:fen value: uci_move (e.g. e2e4). python_chess is the recommended module to calculate all legal moves.

• color – color to move (ChessLink.WHITE or ChessLink.BLACK)

• eval_only – True: indicate ponder evals

new_game(pos)

Initiate a new game

Parameters

pos – position array of the current position. If the hardware board has currently a different position, all differences are indicated by blinking leds.

position_initialized()

Check, if a board position has been received and chess link board is online.

Returns

True, if board position has been received.

position_to_fen(position)

Convert a 8x8 position array to a fen position. Typically, an 8x8 position is generated by the Chess Link board, which has no information about the current move, side to move, or castling status.

The returned FEN has always ending w KQkq - 0 1 after the actual position (only rudimentary checks for castling are done)

Returns

FEN string derived from postion-array

quit()

Quit ChessLink

Try to terminate transport threads gracefully.

reset()

Reset Chess Link module.

set_debounce(count)

Set the debounce-value. Debouncing helps to prevent random fluke events. Should be tested together with different set_scan_time_ms() values.

Parameters

count – 0-4, 0: no debounce, 1-4: 1-4 scan times debounce.

set_led(pos, freq, ontime1, ontime2)

Static blinking leds according to position.

Parameters

• pos – position array, field != 0 indicates a led that should blink.

• freq –

  blink frequency, see magic-link.md.

• ontime1 – 8-bit value, bits indicate cycles led is on.

• ontime2 – 8-bit value, bits indicate cycles led is off.

set_led_brightness(level=1.0)

Set the led brighness.

Parameters

level – 0.0 - 1.0: 0(darkest) up to 1.0(brightest).

set_led_off()

Switch off all leds.

set_orientation(orientation)

Set the Chess Link board orientation.

Setting the orientation is only necessary, when autodecection cannot work, because the board has never been set to a start position.

Parameters

orientation – True: cable right, False: cable left.

set_scan_time_ms(scan_ms=41)

Set the scan time value. Lower scan times make the board less susceptible to random unexpected events and can be used together with set_debounce() to prevent random fluke events.

Parameters

scan_ms – 30.72(fastest)-522.24(slowest), scan time in ms. A value around 100ms is recommended, board default is 41ms.

short_fen(fen)

Utility-function to cut off all information after the actual position, since the board does not know about move counts or castling.

E.g. rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1 is transformed to rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR

Returns

position-only part of the fen string.

show_delta(pos1, pos2, freq=32, ontime1=15, ontime2=240)

Indicate difference between two position arrays using the board’s leds.

Parameters

• pos1 – position array of the start position

• pos2 – position array of the target position

• freq –

  blink frequency, see magic-link.md.

• ontime1 – 8-bit value, bits indicate cycles led is on.

• ontime2 – 8-bit value, bits indicate cycles led is off.

show_deltas(positions, freq)

Signal leds to show difference between current position on board, and intended position. This is used to signal moves by other agents, or discrepancies with the current position.

Up to four half-moves can be indicated at sequence of up to 5 positions.

Parameters

• positions – array of position arrays. Max length is 5 (4 half-moves incl. start position)

• freq – Blink frequency

write_configuration()

Write the configuration for hardware connection (USB/Bluetooth LE) and board orientation to ‘chess_link_config.json’

Returns

True on success, False on error