Specification of Chatroom behaviour using Statecharts
Specification of Chatroom behaviour using Statecharts  

General Information

  • The due date is Sunday 7 December 2014, before 23:55.
  • Submissions must be done via BlackBoard. Beware that BlackBoard's clock may differ slightly from yours.
    All results must be uploaded to BlackBoard and accessible from links in the main (index.html) file.
  • The assignment must be made in groups of maximum 2 people. It is understood that all partners will understand the complete assignment (and will be able to answer questions about it). Clearly identify who did what.
  • 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!
  • Contact Yentl Van Tendeloo if you have any questions or problems.


This assignment will make you familiar with Statechart modelling, simulation, and code synthesis (and a bit of testing).

Problem statement

In this assignment, you will design a Statechart model specifying the reactive behaviour of a chat client.

Note that incremental development is good practice: start modelling and trying out (after simulation and subsequently, code synthesis) small parts of the desired behaviour (satisfying only some of the requirements) in isolation. These can be saved and loaded later to incremental build the full solution Statechart.

The model and its visual representation must both be included in your index.html solution page.

The application's reactive behaviour (Python code) will be synthesized from the Statechart.

(Behaviour) Requirements

  1. The client is either disconnected or connected to a chatserver.
  2. The client has a (hardcoded) list of servers that it can connect to. A server is identified by its IP address (or hostname) and a port.
  3. If the client is disconnected, the user can not enter any input and must wait for a connection to be established.
  4. The client will autonomously connect to a server by sending a connection request. If the server does not respond within a certain amount of time, another server is chosen until one of the connections succeeds.
  5. As soon as the client is connected, the client will actively poll the server after a certain interval. Should the server not respond after a certain timeout, the client will automatically go to disconnected mode and the user is again unable to enter any input.
  6. After transferring to disconnected mode, the client will automatically try to establish a connection to another server. After a connection is successfully made, the user can again give input.
  7. All input that was made by the user before the disconnect should remain in memory and visible to the user.
  8. In connected mode, the user starts without having joined any room. The user can give the input 'j' (Join) to join a specific room. After pressing 'j', the input box is colored green and only numerical input is accepted. Other input is not accepted, and will result in a warning print in the console about the rejected input.
  9. After joining a room, the user starts to receive messages from the server that should be shown in the chat window. The user can either leave the room again by pressing 'l' (Leave), or can send a message by pressing 'm' (Message).
  10. After pressing 'm', the entry box colors white and the user can type a message. The message will be sent after return is pressed.
  11. Should a disconnect from the server occur while the user has already joined a room, the same room should automatically be joined after reconnection to the server.
  12. Make sure that backspace also works in every input mode.
  13. Input processing must happen in a way that resembles Finite State Automata.
  14. You should pick one of the above requirements and build a testing harnass for it which will determine whether your Statechart satisfies the requirement. You do this by adding orthogonal component(s), which model the environment (generate events) and wait for the correct output (black box testing).

Interface provided by the controller

add_message(msg, color)
    shows the message in the chat window, with the specified color (as a string).

    adds a string to the input field and visualizes the change.

    removes the final character from the input field and visualizes the change.

    clears the input field and visualizes the change.

    color the input field in the 'join' mode.

    color the input field in the 'message' mode.

    color the input field in the 'command' mode.

    returns the current content of the input field.

Events sent to the Statechart (as strings):

- connected
    a connection to the server is established
- disconnected
    the connection to the server was broken
- joined
    the room was succesfully joined
- left
    the room was succesfully left
- receive_message
    a message from someone else in the chatroom is received.
    The event has a single parameter, containing the message.
- alive
    the server has replied to the poll

Events sent to the Statechart on the tkinter_input port:

- input
    a keystroke has occurred.
    The event has a single parameter, containing the input character.
    Some special characters include backspace (\b) and carriage return (\r).

You can send the following events to the network component:

- connect
    establish a connection to the server.
    This event takes 2 parameters: the hostname and portnumber.
- disconnect
    disconnect from the server
- join
    join a specific room.
    This event takes a single parameter: the roomnumber to connect to.
- leave
    leave the current room
- poll
    poll if the server is still alive.
- send_message
    send a message to all users in the room.
    This event takes a single parameter: the message to broadcast.

Starting point

As you should only focus on the reactive behaviour of the chat client, we have provided a starting point for you. The starting point includes a working chatserver (in Statecharts) and a network client (in Statecharts). Additionally, the binding with TkInter (the GUI) is also provided.

You should therefore only change the classes/chatwindow.xml file. Initialisation of the network client is already performed in the starting point.

Practical information

Modelling of the Statechart model can be done using the AToMPM SCCD formalism. For installation, see the AToMPM installation instructions (only section 1 is required for this course). Afterwards, please unzip the patch file in your root AToMPM folder. Students that already have AToMPM installed for the course "Model-Driven Engineering" can unzip this file in their existing AToMPM folder. If you already have an account in AToMPM, you will manually have to copy the folders in the users/(default)/ folder into your own user folder. This patch contains the Statecharts and DEVS formalisms used in this assignment, as well as some example models and some bugfixes. A detailed guide about how to load and export a model is given in AToMPM basic usage. To use AToMPM, use Google Chrome (Firefox or others are NOT yet supported) and go to http://localhost:8124/atompm. In the toolbar, load the toolbar /Formalisms/SCCD/SCCD.defaultIcons.metamodel. Designed models can be exported by loading the /Toolbars/SCCD/compile.buttons.model toolbar and pressing the 'export' icon, either without state highlighting (leftmost button) or with state highlighting (rightmost button).

AToMPM and the SCCD formalism do NOT work on a non-English Windows installation. Please change it to English, or use Linux or Mac (language doesn't matter for these).

Left click on the desired model and afterwards right click somewhere in the canvas to place the selected model. You can edit attributes of the model by either using the middle mouse button, or selecting the model and pressing the 'insert' key on your keyboard. As the synthesized model will be in Python, you should write your methods in Python code. Drawing connections is done by right clicking on the source model and dragging the mouse to the destination model. When you are happy with your model, you can export it to SCCDXML and compile it by invoking python python_sccd_compiler/sccdc.py -p eventloop chatclient.xml. Afterwards, you can execute your model by running python run_client.py.

As this assignment uses a server, you will have to start a server with the command python run_server.py 8000 (for port 8000). You can have multiple servers running, as long as each has a different port. By default, 2 server locations are included in the ChatClient method: localhost port 8000 and 8001. The server will print some information about its communication, so you can see whether or not your calls reach the server. The server itself is also written in SCCDXML, but is provided in compiled form for your convenience. If you want to manually compile it, run python python_sccd_compiler.py/sccdc.py -p threads chatserver.xml.

Please hand in any file that you modified. Include links to these files in your index.html. DO NOT include files that weren't modified. Also, please include your model as an image. You can use the SVG export functionality of AToMPM by loading the toolbar /Toolbars/Utilities/Utils.model and pressing its first button.

It is good practice to model and simulate different parts of the overall solution in isolation (incremental, bottom-up design).

You are encouraged to use all functionality that Statecharts offer, such as history states, after events, and orthogonal components.

Additional patches

To use shallow history states, please unzip the latest version of the SCCD patch again: patch file. Allow it to overwrite all existing files. This will not delete your models in any way.
Maintained by Hans Vangheluwe. Last Modified: 2014/11/25 10:18:08.