Learning Objectives

Understand how to model resources sharing in order to:

1 – Ensure it does not jeopardize the program execution because of performance issues.

2 – Define timing properties of communicating tasks.

3 – Integrate new functions such as an obstacle detection task.

Handout & Setup

The presentation of the lecture on AADL can be found from here.

To run the tutorial, you will need a Linux distribution (tested on Debian and Ubuntu), or Windows with WSL2/Virtual Machines.

For those who do not have a Linux computer we provide a Virtual Machine (VM) for VMWare Workstation Player that can be installed from https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html. When prompted by VMWare : select “I moved the VM”. The password to log into the VM is “password”. This VM already contains a directory named “SS-CPSIoT-2023-files” that contains all the tools and models that you will need.

For those using Linux directly, the tools and models are provided here. The root directory of the archive contains the following:

Osate folder:
- A pre-packaged version of OSATE with RAMSES pre-installed.
- OSATE needs to be run differently depending on whether the user interface of your Linux distribution is based on X Windows or Wayland, otherwise the AADL graphical editor may not work. Run the “osate” executable directly if using X11 or “osate_wayland.sh” if using Wayland.
- OSATE might ask you to setup a workspace. Choose a path where you would like to save the project and note the path down
- Prefer using
```
Osate/workspace
```

ev3cc.tar file:
- Install docker on your machine
  - For ubuntu/debian:
```
sudo apt-get install docker.io
```
- load EV3CC on docker.
```
docker load -i ev3cc.tar
```
AI folder:
- AADL Inspector for timing analysis.
- The executable is AI-1.9/bin/AADLInspector

line-follower folder:
- Contains the AADL and C source files required for the workshop.
- The initial AADL design in these source files is almost complete.

Tools Presentation

The tools you are going to use during this exercise are:

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/blog/index.php/ramses/).
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.

How to import the AADL project into OSATE:

Launch OSATE from the folder.
If using the Wayland script:
```
bash osate_wayland.sh
```
If unsure whether you have Wayland or X11 -> run the Wayland version.
Import the initial AADL design into OSATE: Select menu File -> Import…
1. Select General -> Existing project into workspace -> Next -> Select Archive File
2. Select the archive file named “line-follower-ev3-2023.zip”.
3. Click 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 of the model, 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 “ev3_cpu” and “ev3_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 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”.

You will notice the red error squiggles and the ‘Problems’ view will show the following

Description Resource Path Location Type
The referenced property set 'ai' of property 'Root_System' is not listed in a with clause. line-follower-light.aadl /line-follower/aadl_src line: 200 /line-follower/aadl_src/line-follower-light.aadl Xtext Check (fast)

AI property set requires a ‘with’ clause as described. These allow you to import the specific property sets into the current AADL model. Look for the WITH clauses at the top of the file and then add ‘WITH AI;’ there.

In the outline view (on the right side of the editor), select the system implementation named “lineFollower.LightSensor”. This describes the entire system to be generated and therefore is the appropriate target for code generation.

Right click on it (still in the outline view) and click on “launch RAMSES”.

A new window opens to configure RAMSES.

Select “EV3DEV” as a target.
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:

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.
The C files to activate software functions and to implement communications among them located in the generated-code directory
The build system (Makefiles and operating system configuration files) to produce executable binaries
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.

In case the compilation failed run “sudo make” in the output directory of the line follower project.

How to upload a file on the brick:

Connect the EV3 brick to the computer with the USB cable.
Switch on the EV3 brick by pressing the center button.
Find the IP Address of the EV3 brick on the top of the main menu. (May take some time to show up on connection ~1 minute)

Open a terminal and run:

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

(password is: maker)

It should take about 4 seconds to upload the code. Any errors during uploading will be shown.
You can run the program by executing ‘runBlackLineFollower.sh’ on the brick directly.

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 summer school.

Run the AADL Inspector executable from the AI/bin folder that you copied to your computer from the tutorial USB stick or using the shortcut if you are using the provided virtual machine.
File >> Load.
Go to the AADL project folder.
Find the line-follower-line.aic file.
Et Voila! You have it loaded.

OSATE and AADL inspector use the same AADL files. Therefore, every time you modify the file from one of the tools, you will need to refresh it from the other tool. For OSATE, you will need to right-click >> Reload the file in AADL-Inspector.
To save the AADL file from 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
Timing_analysis_part

Click on the Cheese icon (Wine tool incoming next update)
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 the C source code in order to make sure the robot stops moving when 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 that:

The setRobotState subprogram is called by thread ContrThread.impl.
The features of the subprogram call and the calling thread are connected.

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

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

PresentERS

Dominique Blouin (dominique.blouin@telecom-paris.fr)

Anish Bhobe (anish.bhobe@ip-paris.fr)

Rakshit Mittal (rakshit.mittal@uantwerpen.be)