Statechart assignment

General Information

The due date is Monday 17 November 2003, before 23:55.
Submissions must be done via WebCT. Beware that WebCT's clock may differ slightly from yours. As described on the Assignments page, all results must be uploaded to WebCT and accessible from links in the index.html file.
The assignment must be made in groups of 2 people. It is understood that all partners will understand the complete assignment (and will be able to answer questions about it).
Grading will be done based on correctness and completeness of the solution. Do not forget to document your requirements, assumptions, design, implementation and modelling and simulation results in detail !
Extensions, if given, will involve extending not only the alotted time, but also the assignment !

Introduction

In this assignment, you will build a Statechart model which describes the behaviour of an MP3 player. You will go into sufficient detail to make real-time execution of the model in the tool SVM (Statechart Virtual Machine, developed by Thomas Feng) possible. Detailed requirements of the player's behaviour are given lower.

In this assignment you are required to:

Refine the given requirements where deemed necessary. You must explicitly describe your refinements/assumptions.
Draw (with whatever drawing tool you like) the Statechart. Provide an image (inline) in your solution index.html. Not all details of enter/exit/transition actions must (but may) be represented on the drawing. You must however show and name all states and all transitions.
Start from the template SVM Statechart description file MP3Player.des and encode in it the complete Statechart satisfying all given requirements. Your solution should be given in a new file named MP3Solution.des.

The Statechart describes the behaviour of an MP3 player.

The Statechart "interfaces" between

MP3Library.py which encodes a wrapper MP3 file and audio device access
MP3PlayerGUI.py which encodes a simple Tkinter GUI for the MP3 player The GUI look like this

Here is some more information (also found in these file's headers):

  MP3Library.py
  # Class MP3Handle provides a wrapper around the
  # details of accessing MP3 files as well as the audio device.
  # Note how access to the audio device is implicit:
  # mp3.play() plays the current MP3 file and audio is produced.
  #
  # This wrapper can generate the following (hardware) events
  # to be handled (update state, send messages to the GUI) by the
  # Statechart:
  #  "Playing Started"
  #  "Playing Stopped"
  #  "Time Advance"
  #
  # From the Statechart, the modeller may access
  # the wrapper's methods, to query or to control the devices.
  #  Query: get_time
  #  Control: load, play, pause, stop, resume, forward, rewind
  # All of the above have the obvious meaning. resume() resumes
  # playing after playing has been paused.
  #

  MP3PlayerGUI.py
  # class MP3PlayerGUI provides a simple Tkinter GUI for an MP3 player
  #
  # Instantiating the class sets up the MP3 player widgets in a Frame
  # and binds user-initiated GUI events such as clicking on a Button
  # to methods of class MP3PlayerGUI.
  #
  # These methods (window_close, ..., fbackwd_released)
  # send an event (a string such as 'GUI Forward Pressed') to
  # the SVM executive so the Statechart can react to it.
  #
  # Events which the Statechart may receive
  # (and hence needs to handle) are:
  # 'GUI Quit'
  # 'GUI Debug'
  # 'GUI Play/Pause'
  # 'GUI Stop'
  # 'GUI Forward Pressed'
  # 'GUI Forward Released'
  # 'GUI Backward Pressed'
  # 'GUI Backward Released'
  #
  # The methods set_time, hide_time, and show_time
  # can be called from the Statechart to alter parts of the
  # visual appearance of the GUI.

Behaviour requirements

The name of the MP3 file to play is given on the command line using the syntax
```
      svm MP3Solution.des "FILE=[.mp3]"
     
```
Upon starting the application, the system should start in a default state which should be reflected by the user interface (showing time 00:00, all buttons in NORMAL state, i.e., not DISABLED). Also, the playing should commence immediately.
While active (active means not stopped: while playing/paused/seeking), the system will react to 'Time Advance' events sent by the device (every 0.1s) by updating the GUI's time display (with a time value obtained by querying the device for the time - the Statechart itself has no notion of how far in the MP3 file we are). Note that this frequent updating of the display should always return the system in the state it was in just before the update.
While active, the user may Pause (event 'GUI Play/Pause') and subsequently resume (again triggered by event 'GUI Play/Pause') normal playing mode.
While paused, the system will alternately show_time and hide_time the GUI time display. Switching between showing and hiding is done every 0.5s. When exiting from the Paused mode, the time display will always be shown.
While active, the user may also start seeking through the MP3 file. Seeking can either be done in the forward direction or in the backward direction. In either direction, the seeking is initiated by a button press. It continues until the button is released. For FastForward seeking this involves the events 'GUI Forward Pressed' and 'GUI Forward Released'. For FastBackward seeking this involves the events 'GUI Backward Pressed' and 'GUI Backward Released'.
While Seeking, two things happen concurrently.
On the one hand, the display flashes on and off (showing and hiding the time). Switching between showing and hiding is done every 0.3s. Note that in the mean time, the time value in the display is still properly updated every 0.1s as described in 3.

On the other hand, every 0.2s, the device is told to move forward() or backward() in case of FastForwarding or FastBackward-ing respectively by 2 seconds. Note that "Fast" thus means "10x as fast as normal speed".
The Stop button can be pushed (event 'GUI Stop') which will stop the playing/seeking/pausing. This will also disable the appropriate buttons (all except Play/Pause). If playing is started again later (after the user presses the Play/Pause button), this must happen from the beginning of the file (i.e., the device needs to be rewinded).
When the end of the MP3 file is reached (either through FastForwarding or through regular playing), the system should go back to the beginning of the file (time 00:00) and wait there as if stopped.
If the user pressed the close window in the window manager (event 'GUI Quit'), the system should go to its final state, and close the application (taken care of by the FINALIZER).
Where relevant, when entering a state in the Statechart, you must set the appropriate GUI buttons to NORMAL or DISABLED (with SETBTN()).

Hints

You may make liberal use of ENTER and EXIT actions. They will reduce the complexity of the model.

You use put output actions such as

  O: [DUMP("Playing Started")]

to get output on stdout.

The tool

You will use SVM developed by Thomas Feng. You can download it from the SVM homepage. The distribution contains several interesting examples, including a fully functional CD Player.

Note that for the assignment you need PyGame to access the MP3 and audio devices. PyGame is installed on the SOCS unix machines.

The assignment material

The starting point is here (.tgz)

A sample MP3 file is Space.mp3 by Filip Claeys.

You are encouraged to use the RedHat 9 machines in Trottier (Python and PyGame are installed). Do read the README file in the distribution. Though PyGame is also installed on the FreeBSD machines, to get audio, you may have to kill the "artsd" daemon. This is not necessary under RedHat.