MARS documentation page


MARS is a client-server Audience Response System dedicated to e.g. teachers, moderators to support their courses to evaluate knowledge, assess opinions or illustrate concepts, or just for fun!

MARS is published under the GNU GPLv3 open source licence and is free. Polls remain completely under your control and can be shared if, and only if, you choose to do so.

MARS puts the control on the poll material back into your own hands, as opposed to many online commercial products that take away from you the ownership as well as the control over your intellectual property.


The UI design of MARS is inspired by contemporary flat looks. It uses the w3.css kit, font awesome icons and a number of customizations.

polls fig 1

- fig. 1: the poll list -

polls fig 2

- fig. 2: the poll editor -

polls fig 3

- fig. 3: the question editor -

session fig 1

- fig. 4: session in group mode as cast on videoprojector; remaining time is seen on the live progress bar on the bottom -

client fig 1

- fig. 5: the client app during registration, on a smartphone -


MARS uses following concepts:

Poll management

Polls are managed via the Polls top menu bar option. The screen will display a list of all available polls in your local system. The action icons associated to any given poll will determine following activities :

polls fig 1

Poll creation

To create a new poll, click on the green button labelled "create a new poll" at the top of the list. A pop-up will appear where you can fill in the title of the new poll, as well as choose (mandatory) the poll type (see definition above : quiz or poll type). This will initialize a new, empty poll that will be listed in the poll list. To create questions for this new poll, simply click on its "edit" icon to launch the poll editor (see below).

Poll edition

The poll editor allows, much like a slide sorter in presentation software, to add questions, to modify question ordering and to delete questions. Each question composing the poll is depicted along with a number of action buttons :

polls editor fig 1

- the poll editor -

Add questions

To add a new question, click on the "add question" button on the top of the poll editor. This will lauch the question editor with a new question (see below).

Move questions

To move questions use the "move-up/down" buttons as seen on the screenshot above. Their effect is to move the related question one slot up or down in the list of questions.

Delete questions

The DELETE button will remove the related question from the list. Be careful as there is no coming back.

Edit questions

The EDIT button will lauch the question editor with the related question (see below).

Question edition

The question editor allows to completely define all aspects of a question, including all texts, optionally an image illustration etc. All actions on the editor are immediately reflected in a live preview.

Any question can have one of two available layouts: one column and two columns. The two-colum layout allows to fit in additional text and/or an image. Images are hosted externally (e.g. by image hosting sites). More multimedia contents may be available in future versions (sound, video).

The different options and actions are best explained by a picture as well as personal experiments:

question editor fig 1

- the question editor -

Poll play

Reminder: polls can be played (i.e. run in front of a student group) in one of two modes explained above: the group mode and the normal mode. The process of poll play is called a session.

To start a new session with a given poll, see fig. 1 above : two buttons allow to start a session in one of the two modes.

Session lifecycle

A session goes through following states:

  1. waiting: this is the initial state. The session is started, but waits for the participants to register on this session with their terminals (i.e. smartphones). Of course this screen should be visible to all via a videoprojector. The registration URL is indicated for all to see., as well as the session id and a PIN used for client identification. The status zone on the right shows in realtime the number of enrolled students. When all students are enrolled, the teacher can run the session by a click on the green start button:

    session fig 1

    - the session in waiting state (here, in normal mode) -

  2. running: this is the live execution of the session. Its shape depends on the session mode:
  3. finished is the state of a session having terminated normally. Its results are stored and can be viewed later.
  4. cancelled is the state of a session having been terminated manually by the teacher. Although such a session is recorded and can even be restarted, its stored results are perhaps incomplete.

Any type of session in any mode is stored and can be viewed later, but also can be restarted by means of the Session management interface (see below). This allows to conduct a given poll among differents student groups, cumulating the results.

Session management

Sessions are managed by means of the Session list interface, attained by the "Sessions" button on the top menu bar.

Session list

The following picture summarizes actions related to the Session list:

session fig 2

Session results

Session results are available a) after a normal run in normal or group mode, the screen shows already available results as calculated by the server; b) when selected in the Session list through the "view" icon.

Session results have three parts from top to bottom:

  1. the score result table showing the results and scores. In a quiz type of poll, results are red/green per person/per question and an individual score is readily available. In a poll type, results are neutral.
  2. the raw data table which is hidden by default, but can be viewed to discuss individual answers if so desired.
  3. the charts showing the results graphically, which is particularly useful in the poll type.

The following picture shows a portion of the charts part in a real case:

session fig 4

User management

General principles

As of writing (v. 0.87) user management is simplified. Two user roles exist:

In all cases the system can only be used by persons having been through the above approval process (and by the admin himself, of course) and authenticate locally. This strategy isolates MARS from the many possible external authentification methods (LDAP etc.).

Security considerations

Due to the particular http interface between clients and server in the MARS system, man-in-the-middle attacks must be avoided by installing the system on a HTTPS server.

MARS never sends out passwords in cleartext.

Techie section

MARS is a client-server application based on Angular (client side) and PHP (server side). The database is PostGresql. The editor is Atom.