====== Object Transportation System Using LEGO Mindstorms RCX ======

=== Preparation ===

Ensure that BrickOS is properly installed (see brickos.sourceforge.net). Also
ensure that the RCX is flashed with the BrickOS image. Then, extract our
project archive file into the main BrickOS folder. It should create a
subdirectory named "rtods". All commands should be executed within this
directory.

=== Compiling ===

To compile the project, execute:

  make realclean; make

=== Deploying ===

To deploy the project, first ensure that the RCX has been flash with an ID. This
can be done with the following command:

  ../util/dll -r0 -nXXX

Then, execute the following command:

  ../util/dll -rXXX train.lx

=== Testing ===

Several example test scenarios have been provided in the
"tests-expected-output/" directory. In order to try one, edit the "train.c"
file, and change the following line:

  #include "problemdefs/problemdef.h"

to this:

  #include "problemdefs/problemdef-XXX.h"

where XXX is the test number you would like to use. Then recompile and deploy
the program as explained above, and observe the behavior, comparing it to the
expected behavior as recorded in "test-*" in "tests-expected-output/"

(Note: you can create your own problem definition files; see the next section)

=== Problem definition file ===

The problem definition files in the "problemdefs/" directory are C header files
which are included into the main program, which specify various real-time
parameters of the system. Below is a description of each:

* NUM_STATIONS: the number of bins in the system, including both input and
                output bins.
* UNIT_TRANSIT_TIME: worst-case time in milliseconds to travel from one station
                     to an adjacent station.
* CHECK_TIME: worst-case time in milliseconds to complete an input bin check or
              or to dump objects at the output bin, assuming the train is
              already located at the station.

* sttn_period: an array listing the period for each input bin. The first index
               is ignored, as this would correspond to the output bin, which has
               no period.

* sttn_obj_deadline: an array listing the relative deadline for objects picked
                     up at each station. Again, index 0 is ignored as above.

* TBS_SIZE: the parameter U_s, the size of the TBS server. This must be
            scaled by TBS_MAXSIZE. That is, to represent a TBS of size 1/3,
            this must be (TBS_MAXSIZE * 1 / 3).

* ADV_TBS: uncomment (define) this macro to enable "Advanced TBS" with delivery
           WCET reduction.
* ADV_EDF: uncomment (define) this macro to enable "Advanced EDF" with
           preemption emulation (a.k.a. "early execution")

=== List of files ===

* Makefile:              standard makefile provided by BrickOS.
* train.c:               the main C file for the project.
* train_edf_sched.c:     the C code for the EDF scheduler. This is #included
                         into train.c, not compiled separately (due to BrickOS
                         makefile limitations).
* scheduler_api.h:       simple header file listing the functions a scheduler
                         must implement.
* problemdef/*.h:        problem definition files.
* tests-expected-output: test case output expectations.
* README:                this file.

