<refentry id="reference-gmptogtp">

<refmeta>
<refentrytitle>gmptogtp</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="source-name">GoGui</refmiscinfo>
<refmiscinfo class="version">GoGui &version;</refmiscinfo>
<refmiscinfo class="manual">GoGui Reference</refmiscinfo>
</refmeta>

<refnamediv>
<refname>gmptogtp</refname>
<refpurpose>
Adapter from Go Text Protocol to Go Modem Protocol.
</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>gmptogtp</command>
<arg><option>-baud</option> <replaceable>n</replaceable></arg>
<arg><option>-color</option><group choice="plain">
  <arg choice="plain">black</arg><arg choice="plain">white</arg></group></arg>
<arg><option>-config</option> <replaceable>file</replaceable></arg>
<arg><option>-device</option> <replaceable>serial</replaceable></arg>
<arg><option>-flow</option> <group choice="plain">
  <arg choice="plain">rtscts</arg><arg choice="plain">xonxoff</arg>
  <arg choice="plain">none</arg></group></arg>
<arg><option>-simple</option></arg>
<arg><option>-size</option> <replaceable>n</replaceable></arg>
<arg><option>-verbose</option></arg>
<arg><option>-wait</option></arg>
<arg><replaceable>program</replaceable></arg>
</cmdsynopsis>

<cmdsynopsis>
<command>gmptogtp</command>
<arg choice="plain"><option>-list</option></arg>
</cmdsynopsis>

<cmdsynopsis>
<command>gmptogtp</command>
<arg choice="plain"><option>-help</option></arg>
</cmdsynopsis>

<cmdsynopsis>
<command>gmptogtp</command>
<arg choice="plain"><option>-version</option></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsection>
<title>Description</title>
<para>
Go Text Protocol adapter program for playing games using the
Go Modem Protocol over a serial line.
</para>
<para>
If a program argument is given, the given program is run as a child
process and expected to communicate via GMP through its standard input and
output.
For using a serial device, an implementation of the
<ulink url="http://java.sun.com/products/javacomm/">
Java Communications API</ulink> should be installed
(<ulink url="http://www.rxtx.org/">rxtx</ulink>
is a version supporting Unix).
Note that GMP is an asynchronous protocol, commands can be sent
by both sides at any time, while GTP is synchronous.
This problem is resolved in the following way:
A separate thread always listens to the serial device, acknowledges
received GMP commands immediately, and puts them on an internal
queue.
GTP commands that need to receive a command from GMP
(e.g. <command>genmove</command>) check, if such a command
is already on the queue, and wait for a new command otherwise.
If an unexpected GMP command was received, the GTP command will return
with an error; subsequently only a GTP command that corresponds
to the GMP command will succeed.
GTP commands that are waiting for a GMP command can be interrupted
with the special comment line
<command>#&#160;interrupt</command> used by
<application>GoGui</application> to interrupt commands.
</para>
</refsection>

<refsection>
<title>Options</title>

<variablelist>
<varlistentry>
<term>
<option>-baud</option> <replaceable>n</replaceable>
</term>
<listitem>
<para>
Speed of serial device (default 2400).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-color</option> black | white
</term>
<listitem>
<para>
Color of the modem player.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-config</option> <replaceable>file</replaceable>
</term>
<listitem>
<para>
Read command line options and arguments from <replaceable>file</replaceable>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-device</option> <replaceable>serial</replaceable>
</term>
<listitem>
<para>
Serial device name.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-flow</option> rtscts | xonxoff | none
</term>
<listitem>
<para>
Flow control for serial device.
Possible values are hardware control (RTS/CTS), software control (XON/XOFF),
or no control. 
Default: RTS/CTS.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-help</option>
</term>
<listitem>
<para>
Display help and exit.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-list</option>
</term>
<listitem>
<para>
List all serial devices and exit.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-simple</option>
</term>
<listitem>
<para>
Use simple version of the Go Modem Protocol, as defined in the
<ulink url="http://www.tanaka.ecc.u-tokyo.ac.jp/sig-gi/fjk2k-go/cfp-english.txt">
Appendix A in Call For Participation to the FJK Computer Go
Tournament 2000</ulink>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-size</option> <replaceable>n</replaceable>
</term>
<listitem>
<para>
Board size (default 19).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-verbose</option>
</term>
<listitem>
<para>
Print debugging messages.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-version</option>
</term>
<listitem>
<para>
Print version and exit.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<option>-wait</option>
</term>
<listitem>
<para>
Wait for other side to send the first newgame command.
</para>
</listitem>
</varlistentry>

</variablelist>
</refsection>

<refsection>
<title>GTP Extensions</title>
<para>
<variablelist>

<varlistentry>
<term><command>gogui_interrupt</command></term>
<listitem>
<para>
Indicate interrupt ability for GoGui.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>gogui_title</command></term>
<listitem>
<para>
Return a title for GoGui.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>gmp_queue</command></term>
<listitem>
<para>
Print received queued commands, which have already been
acknowledged.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><command>gmp_talk <replaceable>text</replaceable></command></term>
<listitem>
<para>
Send text as talk characters.
If no argument is given, all received talk is returned and the received talk
buffer is cleared.
</para>
</listitem>
</varlistentry>

</variablelist>
</para>
</refsection>

<refsection>
<title>Examples</title>

<refsection>
<title>List serial ports</title>
<simpara>
Test, if GmpToGtp can see serial ports:
</simpara>
<para>
<programlisting>
<userinput>
gmptogtp -list
</userinput>
</programlisting>
</para>
</refsection>

<refsection>
<title>Test GNU Go's GMP mode</title>
<simpara>
GNU Go can communicate via GMP over standard input and output.
It does not make much sense to use it with GmpToGtp that way, because GNU Go
implements GTP directly, but it can be used to test GNU Go's GMP mode without
needing a real serial port:
</simpara>
<para>
<programlisting>
<userinput>
gmptogtp -color white -verbose "gnugo --mode gmp"
</userinput>
</programlisting>
</para>
<simpara>
or with a graphical display:
</simpara>
<para>
<programlisting>
<userinput>
gogui -program "gmptogtp -color white -verbose \"gnugo --mode gmp\""
</userinput>
</programlisting>
</para>
</refsection>

<refsection>
<title>Play game between a program and the serial line with graphical
display</title>
<simpara>
Use a combination between GmpToGtp, TwoGtp and GoGui to play a game
between a Go engine (GNU Go as black) on the first serial port with 2400 baud.
Note that the colors are fixed by the command line options, they cannot be
negotiated. Other options to gmptogtp that might be necessary are -flow and
-simple.
</simpara>
<para>
<programlisting>
<userinput>
GNUGO="gnugo --mode gtp"
GMPTOGTP="gmptogtp -color white -device /dev/ttyS0 -baud 2400 -verbose"
TWOGTP="twogtp -black \"$GNUGO\" -white \"$GMPTOGTP\" -verbose"
gogui -auto -verbose -program "$TWOGTP"
</userinput>
</programlisting>
</para>

<para>
<!-- Empty paragraph to enforce some space in JEditorPane (Java 1.5.0) -->
</para>

</refsection>

</refsection>

</refentry>
