Tools Presentation

The tools you are going to use during this exercise are (tools are already installed on your virtual machine, so we just put the links  for information):

• OSATE, an AADL editor and analysis environment (http://osate.org/)
• RAMSES, a model transformation and code generation tool integrated with OSATE (install it from menu Help>>Intall Additional OSATE Components in OSATE or from https://mem4csd.telecom-paristech.fr/.
• AADL Inspector, an AADL editor and tool suite including timing analysis capabilities (https://www.ellidiss.com/products/aadl-inspector/)

The application will be executed on a Lego EV3 robot (https://en.wikipedia.org/wiki/Lego_Mindstorms_EV3), on which the EV3DEV operating system (https://www.ev3dev.org/) has been installed.

Initial Design

An initial AADL design of the application, almost complete, is available in the provided VM.

How to import the AADL project into OSATE:

1. Launch OSATE , the application is installed on the virtual machine and available on the Desktop or here: ~/Osate/osate
2. If not done yet, download the initial AADL design TODO: ADD-LINK
3. Unzip the archive file of the initial AADL design.
4. Import the initial AADL design in OSATE: in the menu, click on File -> Import…
   1. Select General -> Existing project into workspace -> Next
   2. Select the directory with the initial AADL design (result from step 3.)
   3. Finalize import (click Next until Finish)

–> Result: you should have an AADL project named “line-follower” in your OSATE workspace now.

You can navigate through the project to start understanding the design. The easiest way to start is probably to use the graphical editor as it provides a first synthetic view on the architecture. Graphical editor files are stored in the diagrams folder. You can open the one we have prepared for you: lineFollower_LightSensor.aadl_diagram

Let us describe the structure, which contains:

• The root AADL system implementation definition (named lineFollower.LightSensor)
• The hardware platform definition, made up of a processor and memory subcomponents respectively named nxt_cpu and nxt_mem
• The software application defined as an AADL process subcomponent (named BlackLineFollower) made up of:
  • A global variable (AADL data subcomponent) named Direction
  • Three thread subcomponents named Bg_th, C_th, and Log_th (respectively for getting the light sensor value, control the line follower robot and log the PID controler inputs/outputs).
    

Textual files contain details that cannot be seen on the architecture diagram. You can open the textual definition of a component from the graphical editor: for instance, select the thread subcomponent named C_Th, right click on it, and select “Open AADL source”.

You are now on the definition of the thread subcomponent. Its implementation is ContrThread.impl. In the textual AADL editor, you can use “Ctrl+click” to navigate through model elements. For instance, do a “Ctrl+click” on ContrThread.impl

You are now on the definition of the thread implementation itself. In this definition, property values have been associated to the thread :

• The Dispatch_Protocol property value makes the thread periodic: the code of this thread will be executed periodically
• A Period property defines how often the thread is executed.
• A Priority property defines the relative priority of the thread.
• A Compute_Entrypoint_Call_Sequence defines the sequence of subprograms that will be executed when the thread is dispatched. You can have a look at the subprograms definition, in which you will find references to C functions and source files. Do not hesitate to open them to better understand the application.

Tips:

• Yellow arrows in the toolbar () help you to go navigate to/from locations you were looking at in a recent history.

Part 1: Basic Model Editing

In this first step, you are going to try to generate code and deploy the initial design on the robot. Note that aadl source files are stored in the aadl_src folder and c files are stored in the c_src folder.

Code generation, first try

To do so, open file “line-follower-light.aadl”. In the outline view (on the right side of the editor), select the system implementation named “lineFollower.LightSensor”. Right click on it (still in the outline view) and click on “launch RAMSES”.

A new window opens to configure RAMSES.

1. Select “EV3DEV” as a target
2. Click on Apply and close

An error message appears saying :

RAMSES execution failed with 1 error(s)

  <Internal Error> Called subprograms must have a behavior annex or reference existing source code (Source_Name and Source_Text properties) in line-follower-light.aadl at line 43

Error Fix

Fix the model using the Source_Name property. Navigate to the subprogram implementation by control clicking on the subprogram type to navigate to its definition at line 23 of file line-follower-subprograms.aadl. See the  Source_Name property on the above computePID subprogram. You can see the definition of the property by control clicking on it with. A comment describes the property.

After completing the model, relaunch RAMSES. Look at what RAMSES has produced:

1. An intermediate AADL model (output/refined-models/local-communications/ev3dev/line-follower-light-local-communications.aadl). This model includes a representation of the generated code and can be analyzed to make sure software application fits in terms of memory and processor utilization.
2. The C files to activate software functions and to implement communications among them located in the generated-code directory
3. The build system (Makefiles and operating system configuration files) to produce executable binaries
4. The binary files themselves, by calling the make tool.

Upload the code and have fun

Now, you can upload the executable binary file on the robot to run the line follower.

How to upload a file on the brick:

1. Connect the EV3 brick to the computer with the USB cable
2. Switch on the EV3 brick by pressing the center button
3. Find the IP Address of the EV3 brick on the top of the main menu.
4. In the virtual machine open a terminal and run:

$ ssh robot@<ip-address> 
$ cd <path-to-line-follower-folder>/outputs/
$ make
$ scp ./generated-code/nxt_cpu/BlackLineFollower/BlackLineFollower robot@<ip-address>:~/BlackLineFollower

(password is: maker)

It should take about 4 seconds to upload the code. Any errors during copy will be shown.

Part 2: Timing Performance Analysis

Let’s have a look at threads scheduling to have a better understanding of functions execution. We will use AADL Inspector for this, a commercial tool we can use with a temporary license for the school.

1. Run AADL Inspector from the shortcut on the desktop.
2. File >> Load
3. Go to the AADL project folder
4. Find the line-follower-line.aic file.
5. Et Voila! You have it loaded.

Every time you modify the file in OSATE, you need to right-click >> Reload the file in AADL-Inspector.
To save in AADL-Inspector, right-click >> Save. (CTRL+S doesn’t work – sorry we don’t make the rules)
then right-click >> refresh in OSATE.

Once AADL Inspector is launched, you can do schedulability tests (check if the deadlines of the threads will be met).

You may need to select the system to run tests on.

On the right side of the tool, select Timing Analysis

1. Click on the Cheese icon (Wine tool incoming next update)
   
2. Click on the Cheese icon with THE on it. open the diagnostic to understand the error.
   

Observations: the system is not schedulable

Propose a solution, and test it: how to reduce the cpu load? Modify the model (from AADL Inspector and not in OSATE), and make sure the system is schedulable with your modifications. Note: you cannot change the execution time of the threads, this has been estimated by measuring the timing execution of the object code on the brick. However the period of the threads is a good place to look at…

You probably found a configuration that kind of works. To improve it, we need to log the inputs/outputs of the PID controller. Go to the next section of the exercise to have indications on how to proceed.

Part 3: Obstacle Detection

The objective of this part is to adapt the model and C source code in order to make sure the robot stops moving if it detects an obstacle on its trajectory. In order to do this, you need to have a robot equipped with an obstacle sensor.

We provide you with an AADL model which defines a new thread implementation called EventThread.impl located in file line-follower-obstacle.aadl. This thread will set the state variable defining if the robot can go forward or should stop. If you look closer at the AADL files, the thread EventThread.impl sets the global variable called brake in the aadl model.

In file line-follower-obstacle.aadl, we also provide a new process implementation Proc_light.obstacle_detection that extends the process of the previous model of file line-follower-light.aadl. This process adds a subcomponent for the aforementioned obstacle detection thread (see line 63).

Looking at the computeSpeed C code in file line-follower-light.c, you can see that the program checks for the value of the global variable state to set the motor speed to zero in case the state variable is set to STOP. We therefore need to set that state variable with the value of the global variable called brake. The state will depend on the distance of the obstacle as provided by a call to the GetSonarSensorLib subprogram in the EventThread.impl AADL thread. This call is followed by a call to subprogram select_State that outputs a state parameter in C code and that is connected to the shared Direction data on the AADL side. However this is not sufficient for the code generator, since we need to protect the concurrent data access to Direction. In order to do this, add a call to the provided C code subprogram setRobotState in the thread called ContrThread.impl. Don’t forget to connect the features of the subprogram call to the features of the calling thread.

Make sure: the setRobotState subprogram is called by thread ContrThread.impl; features of the subprogram call and the calling thread are connected

Once you modified the AADL model update the source code as well to make sure that:

1. The control thread continues to produce log entries.
2. The robot remains controlled when it restarts following the loop (i.e. the obstacle is removed)