A DIGITAL WRISTWATCH IN ESTEREL 
================================

PRESENTATION
------------

Here is the program for the esterel wristwatch, with full
tcltk C real-time execution, xes simulation, 
and client/server mixed execution.

   - The tcl/tk simulation runs an actual real-time
     wristwatch model "tkwatch" on your computer.

   - The xes simulation runs "xwatch" the xes graphical animator with fake time
     handling to require less input events for the simulation to
     behave in an interesting way: 2 seconds per minutes, etc., 

   - The client/server simulation "clientserver" runs the tcl/tk
     simulation with simultaneous xes animation of the actual
     real-time execution in a parallel process. 

   - a batch tty simulation "swatch" on a standard simulation input
     file sww.esi.
  

The postscript file of the associated paper 

   "Programming a Digital Watch in Esterel (version v5_92)"

is in file "doc/wristwatch.ps" and "doc/wristwatch.pdf".

BUILDING AND RUNNING THE WRISTWATCH
-----------------------------------

To build all objects files and run them, select the makefile 
corresponding to your architecture:

- Unix :

     cp Makefile.Unix Makefile
     make

  or
     
     make -f Makefile.Unix

  Note: On Solaris, the textual simulator was compiled using
        SparcWorks cc. The result is incompatible with the libraries
        used by /usr/ucb/cc. Change CC to /opt/SUNWspro/bin/cc.

- Windows NT :

  NT command interpreter:

     copy Makefile.VC Makefile

  or

     nmake /f Makefile.VC 

  Cygwin bash:

     cp Makefile.cygwin Makefile
     make

  or

     make -f Makefile.cygwin

  Note : This makefile uses CL.EXE and LINKER.EXE from VisualC++ 6.0.
         These programs must be directly accessible. If it is not the
	 case, edit Makefile.VC to get the correct pathes. 
         Also, create /bin and /tmp and copy /sh into /bin/sh if not 
         already done (highly recommended for Cygnus anyway)

The make command runs tkwatch, xeswatch, clientserver, and swatch right away.
Use "make tkwatch", "make xeswatch", "make clientserver", and "make swatch" 
to run the individula demos.

The make command builds four binary files:

  tkww.exe : the Tk based watch
  sww[.exe]: the watch tty-oriented simulator (csimul library) (the
             .exe suffix is not generated on Unix).
  xww.exe  : the watch xes simulator with symbolic debugging
             and fake time to make simulation simpler
  xwwrt.exe  : the watch xes simulator with symbolic debugging
               and real time, used in clientserver simulation
 
Use the "clean" target to clean the directory of auxiliary files.
Use the "clobber" target to remove all objects and clean the directory.

RUNNING THE TK SIMULATION
-------------------------
The "tkww.exe" object file run a graphical simulation with
an interface that mimics the one in the wristwatch document.
Type

   make [-f <makefile>] tkwatch

or

   xes tkww.exe

to run it. (we call xes only to set some variables for Tcl/Tk).
To quit, either type "q" in the watch window or use the file->quit
menu item. The file->connect menu item is used to manually connect the tkwatch
to an external xes simulator.

RUNNING THE XES SIMULATION
--------------------------

To run the xes simulation with fake fast time, type

   make [-f <makefile>] xeswatch

or

   xes xww.exe

Click on input buttons and look at the source code. In the control
panel, click on "Show Tree" to see the module instantiation tree, and
click on any module name to pop the source code of the module (you can
also click on the "run" keyword that instantiates the submodule in the
source window of the parent module). Click on valued signal or
variable declarations (in blue or red) to pop up their current
values. Load the sww.esi input tape in the recorder and run it.  Read
the online hep or the xes.1 man page or more detail.

RUNNING the client/server simulation
------------------------------------

To run tkww and xes in parallel, type

   make -f <makefile> clientserver

Click on the tcl/tk watch. The animation follows the actual watch.
The events received by tcl/tk from the user and timer are
(asynchronously) sent to the xes process. 

Since these are two separate asynchronous processes
initialized at different times, the watch times can differ by a 
few seconds. We could improve on this in different ways (left to the
reader), but this demo merely illustrate the capacity of Esterel
to run an actual execution and a source code animation in parallel.

RUNNING THE TTY SIMULATION
--------------------------

To simulate the wristwatch in standard Esterel tty-oriented 
csimul simulation mode, type 

   make [-f <makefile] swatch

or

   sww[.exe]

You can run a demo simulation by typing 

   sww[.exe] sww.esi

The file sww_ref.eso is the result that should be produced by the
previous command. The error message about HS and S being incompatible
is normal.

TRYING THE VARIOUS COMPILATION MODES
------------------------------------

Try changing compilation options by changing 
ESTEREL_FLAGS and ESTEREL_FLAGS_FOR_SIMUL in your makefile.

   - Add option -v to see the compiling phases

   - Add -A to ESTEREL_FLAGS or change -I into -A in ESTEREL_FLAGS_FOR_SIMUL 
     to run automaton code

SUBDIRECTORIES
--------------

The subdirectories are as follows:

- watch : the WATCH module and its C data-handling code

- stopwatch : the STOPWATCH module and its C data-handling code

- alarm : the ALARM module and its C data-handling code

- button : the BUTTON module

- display : the DISPLAY module and its C data-handling code

- beep : the C data-handling code for the beeper

- tkmain : the main C programs for Unix Tk simulation.

- doc : contains wristwatch code documentation.

- tkmain : the tcl/tk code to run tkww.

- clientserver : code to develop your own client/server applications.

BUG REPORTS
-----------

Please report any misfunctioning to :

e-mail: esterel-bugs@sophia.inria.fr
