
                             xboard232          version 0.0   1 Jul 2002
                             ---------


Description:

Xboard232 is an adaptor which adds Auto232 capability to xboard.  That
is, it allows chess engines supporting the Auto232 protocol over a
null-modem serial cable to be used with xboard on Unix.

Xboard232 is similar to WinBoard232 by Eberhard Börger, except
xboard232 runs on Unix, not Windows.



Requirements:

2 computers connected by a null-modem serial cable;
1 of the computers runs xboard on Unix, which must have X-Windows;
The other computer runs any Auto232-capable chess program.



Compiling:

At the shell prompt, type:

    make



Installing:

Copy xboard232 to any directory in the user's PATH, e.g, as root:

    cp xboard232 /usr/local/bin/



Usage:

Xboard232 takes a single argument, the name of the serial port the
null-modem cable is connected to.

However, xboard232 is not normally started standalone, but as an
argument to xboard, as the following example demostrates.



Example of usage:

                       A                       B
                   ---------              -----------
                   |       |              |xboard   |
                   |Fritz7 |  null-modem  |xboard232|
                   |WinXP  |--------------|crafty   |
                   |       |    serial    |Unix     |
                   ---------              -----------

In this example, Fritz7 on WinXP computer A plays against crafty on
Unix computer B under the control of xboard on computer B.  To set up
this example, follow these steps:

1: Connect and test the null-modem serial cable.  I use HyperTerminal
on WinXP and minicom on Unix for testing.  You might have to change
the protection mask on the Unix serial port to allow non-root users to
use it, e.g, chmod o+rw /dev/ttyS0

2: Ensure xboard, crafty and xboard232 are installed in directories in
the user's PATH on computer B.

3: Start Fritz7 on computer A.  Under Game/Levels/Long-game, set the
time controls to the same settings as you are going to use for xboard,
e.g, 40 moves per 5 minutes for both players.  From File/New, start a
two computer match.  Select the Auto232 driver and the serial port
(Com1, Com2,...) for the null-modem cable.  Click OK until the two
computer game starts.

4: Start xboard on computer B with a command like:

    xboard -tc 5:00 -fcp "crafty xboard" -scp "xboard232 /dev/ttyS0"

Use different time controls as desired.  Add more crafty arguments as
desired inside the first pair of quotes.  Useful crafty options
include bookpath, logpath, egtb, hash, hashp, smpmt and so on.  See
the crafty docs for these.  Change /dev/ttyS0 to the null-modem
cable's serial port.  Swap -fcp and -scp if Fritz7 plays white instead
of black.  Append other xboard arguments as desired.  You will
probably want to make a little shell script, so you don't have to type
it all in every time.

5: Finally, select "Two machines" in the xboard Mode menu to start the
two computer game.



How xboard232 works:

Xboard232 sends and receives Auto232 commands over the serial port.
Xboard232 talks xboard protocol over stdin and stdout.



Limitations:

Xboard232 is a very crude program.

Xboard232 does not keep track of chess pieces, nor whose turn it is to
play, nor does it know anything about the rules of chess.  It simply
converts chess moves from one protocol to the other and relays them
on.  It does not detect illegal moves, nor does it necessarily detect
the end of a game.

Xboard232 cannot distinguish captures, castles and en-passants from
normal moves, so it only sends Auto232 NMOVE commands, never CAPMOVE,
EPMOVE, OOMOVE nor OOOMOVE.  Fritz7 seems to be OK with that, but
other Auto232-capable programs might not be.  Minor piece pawn
promotions are handled properly.

I have not tested xboard232 with any programs other than Fritz7 and
xboard.  Xboard232 does not implement any part of the standard Auto232
protocol that is not used by those programs.  Xboard232 does not
implement Analysis nor any advanced xboard commands.

Xboard232 does not communicate time information.  Both sides are
expected to keep time.  Unfortunately, independent chess clocks drift
apart, especially when slow network communication is involved.
Sometimes one side will claim a win on time while the other side keeps
playing.

At the end of a game, Fritz7 sometimes wants to change sides for the
next game.  On the other hand, xboard always expects the first chess
program to play white and the second chess program to play black.  I
can't think how to handle this dilemma automatically, so for now we
can't play more than one game at a time without manual intervention.

To keep things simple, xboard232 is single-threaded, unlike the
"standard" Auto232 implementation.  Timeouts may be handled
differently to the standard.  Xboard232 does not send an Auto232
SAVEGAME command at the end of a game, like it should.



Copyright:

Xboard232.c and xboard232.h are derived from copyrighted works for
which the following conditions apply:
> This code can be used freely by other chess programmers under the
> following conditions:
> A) The History and Copyright-comments must be left in the code.
> B) The code or any executables produced by it must not be sold
>    (this is also valid for modifications of this code).
> C) Executables/Object-code can be distributed in a bundled form
>    with chess-programs. There must be NO extra price tag for the
>    the autoplayer-version of the chess program.
> D) Credit should be given in the About-Box of the program to
>    Stefan Meyer-Kahlen and Ch.Donninger. (This point is only a
>    question of etiquette).
> E) The authors can not be blamed for bugs. It is the duty of each
>    chess programmer to test the code and fix bugs. Serious bugs
>    should be reported to the authors.
> F) This code can be distributed freely to other chess programmers
>    if the copyright conditions above are NOT changed.

Other source files are public domain.



References:

    xboard:           http://www.tim-mann.org/xboard.html

    crafty:           ftp://ftp.cis.uab.edu/pub/hyatt/

    Fritz7:           http://www.chessbase.com/

    Xboard protocol:  http://www.tim-mann.org/xboard/engine-intf.html

    Auto232 protocol: http://remi.coulom.free.fr/programs0046.tar.gz

    WinBoard232       http://www.amateurschach.de/schach/download/download.htm

    Unix serial port programming: Serial-Programming-HOWTO

--
Peter McGavin.   (p.mcgavin@irl.cri.nz)
