Opening Book Tools for STM32

Purpose

Two scripts build an opening book for the Micro-Max chess engine running on an STM32 microcontroller. The book is stored in Flash as an array of polyglot_entry_t structures (Zobrist key + Polyglot move), sorted by key for binary search.

Generator — chess_book_builder.py v3.9

Automatically builds a tree of opening variations using Stockfish, filters out weak moves, and collects up to 1500 positions in the book.

Parameters (top of file)

Logic

The tree is expanded by White's moves only. For each position where it is White's turn, filtered_moves() asks Stockfish for the top MULTIPV lines and keeps those within THRESHOLD_CP of the best. For each resulting position (after White's move), Stockfish returns one best move for Black via engine.play(). That move is what gets written to the book.

Generation Stages

Move Filtering

The filtered_moves() function asks Stockfish for the top MULTIPV candidates and keeps only those within 40 cp of the best evaluation. Weak moves (e.g., Ke2 on move 2) are discarded, freeing space for deeper lines.

Timing

After each stage, the script prints elapsed time and an ETA based on seconds-per-position:

Stage 1 (ply 1): 2 pos. | 14.0s | total 14.0s | ETA: ~65min remaining
Stage 2 (ply 3): 20 pos. | 56s | total 70s | ETA: ~55min remaining

Output Files

Format of debut_book.c

#include "polyglot.h"

const polyglot_entry_t debut_book[] = {
\t{0x010C55ABU, 0x1234U, 1},
\t...
};

const int debut_book_size = 1500;

Format of book_session.json

{
  "version": "4.9",
  "book": [[key, "e2e4", "e4", pg], ...],
  "lines": [["1. e4 c5 2. Nf3 [0x010C55AB]", ["e2e4", "c7c5", "g1f3"], key], ...]
}

Dependencies

• zobrist_table.h — Zobrist number table (781 values), searched in the script directory
• stockfish-windows-*.exe — engine, searched in the script directory
• python-chess — chess library for Python

Running

python chess_book_builder.py

Diagnostics

After completion, stage statistics are printed:

Statistics by stage:
  ply 1 (stage 1): 2 positions
  ply 3 (stage 2): 20 positions
  ply 5 (stage 3): 100 positions
  ply 7 (stage 4): 300 positions
  ply 9 (stage 5): 500 positions
  ply 11 (stage 6): 578 positions

Manual Editor — chess_book_editor.py v4.9

A tkinter GUI for manual editing of the opening book. Board with gc2004d font, dark theme, localization (Russian / English).

Features

Key Search

Two independent searches — in Book Entries and in Lines:

PGN Navigation

Book Entry

Each entry: key (Zobrist, uint32_t) + move (UCI, 4 characters) + SAN + Polyglot (uint16_t).

The key is computed by compute_zobrist(board) before Black's move — i.e., for the position in which the Micro-Max engine will look up a response.

Dependencies

• zobrist_table.h — same table as the generator
• chess_book_editor_lang.py — localization file (50 keys, ru/en)
• python-chess, tkinter

Running

python chess_book_editor.py

Typical Workflow

1. Generate — run chess_book_builder.py, get book_session.json and debut_book.c
2. Verify — open book_session.json in the editor, search by keys, make sure hashes in lines and entries match
3. Edit — add missing lines by mouse or from PGN, remove extras
4. Export — save debut_book.c from the editor
5. Flash — compile debut_book.c with the Micro-Max code, flash the STM32

Zobrist Compatibility

Both scripts use the same zobrist_table.h table. Indexing:

• Pieces: (piece_type - 1) * 2 + (0 for White, 1 for Black) × 64 + square
• Side to move: ZOBRIST_NUMBERS[-1]
• Castling: last 4 values in the table

The key is masked to 32 bits: key & 0xFFFFFFFF — matching uint32_t on the STM32.

Troubleshooting