This website provides the up to date information on course material, exercises and announcements about PRJ3, the elevator project.

This website’s info supersedes the info in the LaTeX/pdf version of the same project. However the LaTeX/pdf version is made available as reference example on how to create consistent looking LaTeX documents for individual or group work.

The module workbook can be found here. The module description is also online.

Starting in the Autumn semester of 2018, prj3 is now a full semester project in three parts:

  1. Requirements engineering, learning the ropes.

  2. RE applied to an elevator system, producing a complete SRS

  3. Analyse, Design and Implement the system described in the SRS.

This website describes the third part.

Student groups are composed based on scores in the exams PRC1, PRC2, AAD and DVP1 plus the scores in PRJ2.
The groups will be mostly homogeneous with respect to grade ranking. Rationale: a homogeneous group is a better basis for discussion and can find a matching challenge.
In this module it is mandatory that you execute a proper time registration. See [time-registration].

1. Use of LaTeX

The final products, such as the descriptions of the architecture, the API, the reference implementation and the demo application shall be done in LaTeX for a consistent look. Make sure you use a proper setup of you LaTeX project, using input or include to compile the final report. For the drawings use a vector format, NOT jpeg. For visual paradigm that means export to pdf or svg and crop the figure to a proper size. No more screen shots, unless they are from the actual application.

All students should have a contribution to this part, the same as to the source code. Do NOT save (MS|Libre)office documents but only LaTeX for the text and the appropriate format for images or figures. Make sure the images have the proper size (readability) and (sometimes) leave out details that are not relevant to the narative in the text.

Realisation phase, Weekly subjects, week 1-7

Weeks 1 and 2 are the Analysis phase of the project. The product of these weeks is a refinement of the SRS, dotting all I-s and a course design. In particular, make proper separation between what goes into the behaviour of the 'machine', a.k.a. the state diagram and what can and should be realised by application of patterns other than the State pattern. This is the phase where you set the architecture, what components you will have and what subsystems. Ultimately, you will also fix the API.

Always try to follow the KISS principle. Keep it simple, stupid.

2. week 01: Analyse the SRS.

This week you will analyse the description in the SRS manual and make a proper analysis. Start with a group discussion, to make sure you have a common understanding of the system promised to the customer and described in the SRS. In any discussion, use a scrap paper or white board. Once the dust of then discussion has settled, set the design in stone, or rather in visual paradigm.

To formalise the artefacts, use Visual paradigm. Make sure that you use the proper UML symbols and relations. (Directions etc, in particular, who has what).

The expected artefacts are:

  • Analysis class diagram including CRC descriptions of the classes.

  • Sequence diagrams of the main scenarios. If you followed the advice in the use cases you should have about 5 sequence diagrams. If already created in the SRS, improve or correct them. A sequence diagram should model a use case from an event (e.g. sensor activation) to an observable effect.

  • Layered Model of the elevator. What is done where. Note that the hardware layer isolates the layer above from what can vary in the implementation. In this case you will at least have a pure graphical simulation and a GUI+hardware in the lower layers.

  • State model The system obviously has state behaviour. Model this state behaviour of the system and its subsystems using state diagrams. Note that the machine is the combination of cage and doors with their motors.

  • Data model Data model is a posh a word for how to keep track of all requests and commands of the elevator system. Design a data model with appropriate operations. It is allowed to think of a Java interface to model all required operations on the data model. The data model may keep up and down requests separate from target requests. From the start think of multiple shaft systems.

Next Monday morning we will svn-tag your work with TAG_WEEK1

3. week 02: Analyse of the Hardware and IO

Analysis, design and implementation of the hardware IO subsystem. The project’s deliverables, the API, the API implementation and the example application will use an USB connected hardware elevator model. The hardware elevator will be connected using USB and a small IOWarrior printed circuit board. You will be given the complete IOWarrior library (which is available from code mercenaries) plus a library that provides the elementary read and write operations to the hardware.

3.1. Deliverables Hardware Layer

Class model IO subsystem A complete design class model of the system. For the report you will need diagrams of the subsystems.
Implementation of IO subsystem As usual: no implementation is complete without tests!
Data model and implementation including tests of all the operations.
The test on the data model must have 100% statement coverage, to be determined with the jacoco coverage plug in.

3.1.1. Analysis Example

Elevator Analysis slides: Elevator example

You should realise that we expect to see three separate maven projects, the API,
the reference Implementation of the elevator system, which is the 'business logic' and the Demo Application
that show that this business logic can control a elevator demonstration system built using classes that provide the implementation of the API.

Next Monday morning we will svn-tag your work with TAG_WEEK2

4. week 03: GUI and Simulation

GUI and Simulation design and implementation of the widgets used in this design. You will design and implement the parts that are used in the lower layer, GUI wise.

4.1. Deliverables

Drawing of the gui design I would use inkscape. You might want to opt for Adobe Illustrator or a similar tool. Make sure you are able to deliver a vector type file. (SVG or PDF).
Widgets The Cage which should provide obstruction detection functionality. Up and down buttons including the appropriate. Floor sensor indicators which show when a floor sensor is activated. You may want to take a look at the fxample.zip example, that show how you can attach the hardware and cagewidgetsfx.zip to see how you can animate moving doors, floor sensors for a GUI implementation.
ButtonModels. Target buttons. Note that all these widgets get rather little real estate in the GUI picture.
State machine(s) implementation for the behaviour of the system.

Next Monday morning we will svn-tag your work with TAG_WEEK3

5. week 04: Data model and GUI integration

5.1. Deliverables

Integrated GUI simulation that shows the functionality of the widgets and the whole system so far. This simulation should already behave like a normal elevator system with respect to state behaviour. The data model should be used.
Strategy design Use the Strategy pattern to implement different behaviours of the system in several modes. Implement one simple but useful strategy.

Next Monday morning we will svn-tag your work with TAG_WEEK4

6. week 05: GUI - hardware integration

Combined hardware and software model in which the GUI shows two cages, one simulation and the other as a monitor to the hardware model. This implementation must be working for a building with 4 floors.

Next Monday morning we will svn-tag your work with TAG_WEEK5

7. week 06: Additional strategy implementations

Strategy implementations for the remaining operating modes.

7.1. Deliverables Documention, presentation and demo preparation

Complete class documentation extract-able with javadoc.+ all diagrams for the report. Report with sections requirements, analysis, design, implementation details, test plan describing what you intended to test, deployment manual and a User manual.

Next Monday morning we will svn-tag your work with TAG_WEEK6

8. week 07: Delivery week

Prepare for the products to be presented and demonstrated.

8.1. Deliverables

During the demonstration the use of compilers, editors, IDEs (other then editing a configuration) and the like is forbidden. All code should be runnable in delivered binary form, downloaded from the peerweb portfolio site. For Java that would be a jar file, possibly combined with a startup script. You may use several startup scripts to show different features of your application, but all should use the same (set of) jar file(s).

The App in a Jar All groups will provide a jar file that contains the application. This jar file must be self contained and have no external dependencies that have to be pre-installed. This should provide us to have very nice set of demo applications. The example project provides a way to do that. This application should be able to work with and without the iowarrior drivers and libraries installed.

All students must attend the presentation and demonstration of all groups.

Final execution report Time usage sheets for all group members summarised over the whole project.

Defect report Defects found during tests and integration with an impact analysis. An impact analysis describes what the subsequent effect of this defect is on the rest of or the overall system.

Next Monday morning we will svn-tag your work with TAG_WEEK7

9. Assessment and demo

In week 14 we will have a presentation and demo by all groups followed by an assessment for all individual students.

Appendix

Install the driver.

To be able to use the hardware elevator /usb combination we provide a set of libraries. They are described in the module manual and come with javadoc documentation.

To give you a flying start with maven, you might want to check out the sources of fxample which is available in demos and sample directory in the parent repository.

We will be using the IOWarrior-40 chip to connect the hardware through USB. If you want to experiment with this library, you can find it here.

I have used and tested it with Linux.

Installation under Linux

Installing the kit for Linux boils down to installing both native library libiowkit.so and codemercs.jar. The kernel module for the iowarrior, iowarrior.ko, is already integrated into modern Linux kernels.

On my machine the installation should be done into the following directories:

Directory /usr/lib for libiowkit.so Directory /usr/lib/jvm/java-8-oracle/jre/lib/ext for the utility jar codemercs.jar All this has been arranged in the repackaged iowSDK.zip. Unpack it in some convenient place like ~/Desktop or /tmp, enter the newly created iowSDK directory and sudo ./buildall.sh. You might need to do a modprobe iowarrior to load the iowarrior kernel module that comes with modern Linuxen. There after you can remove this iowSDK directory.

To get things running and test your hardware and driver setup you can use the following resources:

  • linux libiowkit

  • bitfactoryexample.zip, a zip file containing working bitfactory example jar named BitFactoryExample-1.0-SNAPSHOT-jar-with-dependencies.jar as a fat jar, which goes with a

  • elevator.properties file, required to be found in the directory you start your jar in.

The bitfactory example is swing project.

Unpack (unzip) this file in a convenient place and open a command line in the directory bitfactoryexample that is created by the unpacking.

Then on the commandline you should be able to run this simple test app with:

$ cd bitfactoryexample
$ java -jar BitFactoryExample-1.0-SNAPSHOT-jar-with-dependencies.jar

For your convenience there also is a run.sh and a run.bat file. Make the one you need executable and do

$ ./run.sh

Installation under Windows

The following has been tested under Windows XP, Vista and Windows 7 (excerpt from the readme file in the iowarrior kit)

  • Copy …​\Windows\iowkit api\x86\iowkit.dll to system DLLs directory (winnt\system32 directory in Windows 2000, windows\system32 in Windows >= XP. For a 64 bit windows, select the dll from the appropriate directory …​\Windows\iowkit api\x64\

  • Include the …​./Java/jar/codemercs.jar from the iorwarrior SDK in your project or in your java classpath.

SEBI Venlo IO Libraries

The elevator is connected to the host computer (your laptop) using USB. Writing all of the IO handling is beyond the objectives of this project.

We have wrapped the complexity of bit manipulation into some libraries.

Architecture

The libraries consists of several components each in a separate jar, and implemented as a maven project.

SEVenlo Component Diagram
Figure 1. application library dependencies

There is one over-arching maven project, a parent project in maven speak, called SEVenlo::ParentPom.

The base library is SEVenlo::HWIO, with the maven coordinates <groupId>nl.fontys.sevenlo</groupId> and <artifactId>sevenlohwio</artifactId>.

The base library defines all abstractions needed to build an application on the one hand and a 'bit' or io provider, like the iowarrior on the other hand. Bits typically are arranged in what the library calls BitAggregates. This is the abstraction that supports USB io but also parallel io and other kinds of hardware connectivity.

The essential class diagram is given below and can also be found in the API documentation of the SEVenlohwio library and the module manual.

SEVenlo HWIO
Figure 2. sevenlohwio base package

To use this library effectively, you need to add some ingredients yourselves, such as:

  • Application specific InputBits, which carry the relevant information, e.g. type of input, and things like floor number and elevator id.

  • Application specific `OutputBit`s and `BitGroup`s, that are used to control the hardware. Examples are: UP and DOWN Lights but also a Abstract Motor which uses a BitGroup of at least two bits or a floor indicator which uses say four lights in the hardware elevator module.

  • AbstractFactories that create said bits and bitgroups and connect them to the hardware.

The whole set of libraries is available through as set of maven coordinates, and made accessible through our maven repository at SEVenlo Maven Repository. It is not a source code repository such as subversion but instead a storage for the compiled jar files in possibly different versions.

The documentation can be found at sevenloio.

Examples and using Maven

You will work with maven as the preferred build tool. It has the advantage that dependency resolutions is done very effectively.

Using maven implies that you do NOT include the sources nor the jare files of the used libraries into your project. Instead you declare the dependecies in the pom.xml file and let maven figure out where and how to get the library.

This project uses a fontys venlo specific repository living at https://www.fontysvenlo.org/repository as well as the standard maven repositories.
In particular, the following defines (or adds) the fontys venlo repo to the project:

maven repo definition, simplest possible ~/.m2/settings.xml
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>sebivenlo</id>
            <repositories>
                <repository>
                    <id>fontysvenlo.org</id>
                    <url>https://www.fontysvenlo.org/repository</url>
                </repository>
            </repositories>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>sebivenlo</activeProfile>
    </activeProfiles>
    <offline>false</offline>
</settings>

Delivery of final Artifacts.

In real life you would not give your customer access to your repository and say, go ahead, build it, it works for me. Instead, you should provide the product separately. We use the peerweb upload facility to that effect.

How to deliver your assignment products:

All electronic products must be handed in via peerweb. See peerweb and this website for all deadlines.
Report: one document describing your analysis, design and its implementation, test installation and user manual to be handed in on paper too, properly bound at the copy shop. The document should also contain a reference to the repository. See the module_manual for what the document should contain.
The design diagrams, user interface illustrations etc. are copied into and explained in the report document. In the document code fragments are shown only when relevant. E.g. when the implementation is discussed in the describing text.
Models: One model file for each phase of analysis, design and implementation in the Visual Paradigm UML tool. Hand in by svn. The models should contain analysis, design and implementation as well as a reverse engineered model of the complete implementation. For practical reasons you may use more then one model file for each of the phases analysis, design and implementation. You may hand in three distinct models.
Implementation: All (re)sources needed to build the project should be in the project repository at all times. The sources should be accompanied with a pom.xml build script. It should be possible to build the application with just maven and an installed JDK >= Java 8.
We expect to see three separate maven projects, the API, the reference Implementation of the elevator system, which is the 'business logic' and the demo application that show that this business logic can control a elevator demonstration system built using classes that provide the implementation of the API.

For all but the first week you should produce an executable artefact or runnable program. By checking out the project and calling mvn package should result in a functional and runnable jar file. Say the produced jar file is called target/SuperElevator.jar
I will use the file like this: java -cp dist/SuperElevator.jar nl.fontys.sevenlo.PRJ32.DemoWeekX.

The prefix nl.fontys.sevenlo.PRJ32 is mandatory for all your packages. You may (maybe should) have additional packages under this top package name. You may (and are advised to do so) also create several maven projects with additional package and directory structures to reflect your functional decomposition.

Each week that has an executable will have a Main class named nl.fontys.sevenlo.PRJ32.DemoWeek<weeknr>. For each week, except the first, there will be a hand in of a runnable jar file.

Time registration.

Profesionals can give proper time estimations. It is about start to gain some experience.

Time registration is mandatory in this module. During the project you must keep a record of the times you estimate and you really use on the project. To be able to determine the realism of your entries, you should also enter these values for your other study related activities. For this timekeeping you should use the spreadsheet that is available in {Libre|Open}-Office and Microsoft excel 2007 format. Upload the filled out sheet into the repository each time at the end of the week. Deadline is typically at the end of the week (Sunday evening).

Time sheet

Note that the timesheet is personal. It is mandatory, but will NOT be used in the assessment. If you want to fool yourselves, feel free.

Deadlines

The last lecture week starts on Monday 2018-12-10 and ends on Friday 2018-12-14.

The presentations and assessments will take place in the week from 2018-12-17 to 2018-12-21, in which the Monday amd Tuesday are most likely. There will be a group presentation en demonstration, in which all students will participate.

Hand-in deadline: Wednesday 2017-12-12, 12:00.

To be able to study your artefacts, we maintain a strict deadline for the hand-in of the artefacts per peerweb: Wednesday 2018-12-12, 12:00. The 2 paper copies should also be on our desk by that time.

Student Repositories for the realisation phase

The following repositories have been provided:

Common stuff, such as example the example project, the timesheet template and the LaTeX sources of the latex module manual can be found in the svnroot repo. https://www.fontysvenlo.org/svn/2018/prj3realisation/svnroot

Q & A

TODO. Depends on student input.