Learning Objectives

Understand how to model resources on hardware.

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

2 – Define timing properties of communicating tasks.

3 – Connect C driver code with AADL models.

4 – Refine ‘base systems’ to specific implementations.

Handout & Setup

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

The tools and models are provided in a USB stick given to you for the tutorial. The root directory of the archive contains the following:

• OSATE folder:
  
  • A pre-packaged version of OSATE with RAMSES pre-installed.
  • Run OSATEusing the “run_osate.sh” script.
  • OSATE might ask you to setup a workspace. Choose a path where you would like to save the project and note the path down.
  • Use the workspace inside the OSATE folder.

    Osate/workspace

  • Import the tutorial-cruise-control folder using Import > General > Existing Projects into Workspace
    
  • Should show up completely in a sec.

• ev3cc.tar file:
  
  • Install docker on your machine
    • For Debian based Systems.

      sudo apt-get install -S docker.io

    • For Arch based Systems

      sudo pacman -S docker

  • Load EV3CC on docker.

    docker load -i ev3cc.tar

• AI folder:
  
  • AADL Inspector for timing analysis.
  • The executable is AI-1.9/bin/AADLInspector

• tutorial-cruise-control folder:
  
  • Contains the AADL and C source files required for the tutorial.
  • 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:

1. Launch OSATE from the folder.

   bash run_osate.sh

2. The project should already exist in the workspace.
   1. If not, do the following steps.
3. 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 “tutorial-cruise-control.zip”.
   3. Click Finish

–> Result: you should have an AADL project named “tutorial-cruise-control” 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: Cruise_Control_Basic_Cruise_Control_basic.aadl_diagram

Let us describe the structure of the model, which contains:

• The root AADL system implementation definition (named Cruise_Control.basic)
• 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 Distance_Control) made up of:
  • Two thread subcomponents named Th_Sensor and Th_Control (respectively for getting the sonar sensor value and to control the robot motors).
    

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 Th_Control, right click on it, and select “Open AADL source”.

You are now on the definition of the thread subcomponent. Its implementation is PID_Control_Thread.impl. In the textual AADL editor, you can use “Ctrl+click” to navigate through model elements. For instance, do a “Ctrl+click” on PID_Control_Thread.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.

Importing AADL Packages

To do so, open file cruise-control-basic.aadl.

You will notice the red error squiggles and a Problem view at the bottom. Find the following in the Errors.

The referenced property set 'ai' of property 'Root_System' is not listed in a with clause. cruise-control-main.aadl /tutorial-cruise-control/aadl_src line: 222 /tutorial-cruise-control/aadl_src/cruise-control-main.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.

Subprograms

Subprograms are AADL components that describe specific behaviors that the system will execute. These can be described in various ways, either using plain source code in C or Ada, or using an AADL language extension called Behavior Annexe, which supports behavior specification for components such as subprograms or threads.

For our task, we will use C code for behavior.
The file cruise-control-subprograms.aadl contains all the subprograms that are used by the PID controller. In this, the PID_Compute_Call subprogram is empty. We will connect this to the source code in c_src/pid_controller.h (and the respective ‘.c’ file.)

The function signature is as follows.

Properties

We declare the properties by putting the properties  keyword inside the subprogram. (Hint: Use the other subprograms as inspiration)
We declare 3 properties:

• Source_Language
  This declares the language in use.
• Source_Text
  This is a List. AADL uses Round Parentheses with commas as separators.
  Write the link to the files for pid_error.
• Source_Name
  Name of the function we will call.

Once the above 3 are written correctly, we can move to the next section.

FEATURES

The features in the subprogram map to the input and output of the function.
Note: They are order dependent.

The syntax for declaring parameters is as follows.

<name> : [in|out] parameter <datatype>

We already have names for our features, which are the same as the ones in the function signature. And the data types (int, float) are available from the Data_Type package. (Data_Type::Int, Data_Type::Float)

Note: AADL is case insensitive. So, the following are all the same (but try to be consistent)

current_distance
Current_Distance
CURRENT_DISTANCE
cuRrEnT_DiStANcE   // please do not use Tumblr-case.

Once all the features (parameters) are written, all the errors should disappear (on save).

Code Generation

Now we can start generating some code (without LLMs).

In the outline view (on the right side of the editor), select the system implementation named Cruise_Control.basic. 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.

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

Upload the code and have fun

Now, you can upload the executable binary file on the robot to run the cruise control application.

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:

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. (May take some time to show up on connection ~1 minute)
4. Open a terminal and run:

   $ cd <path-to-cruise-control-folder>/output/
   $ scp ./generated-code/ev3dev/EV3_Cpu/Distance_Control/Distance_Control robot@<ip-address>:~/CruiseControl 
   
   (password is: maker)
   

5. It should take about 4 seconds to upload the code. Any errors during uploading will be shown.
6. You can run the program by executing
   File Browser > runCruiseControlSudo.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.

1. 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.
2. File >> Load.
3. Go to the AADL project folder.
4. Find the TutorialCruiseControl.aic file.
5. 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

1. Click on the Cheese icon (Simulation Timelines)
   You will see the timelines of the tasks of your threads.
   Black part is execution, orange is waiting and the grey blocks show the total use.
2. Click on the Cheese icon with the THE on it (Theoretical Tests). This opens the diagnostics to understand what doesn’t work.
   

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…

Once the analysis results from AADL Inspector are correct, regenerate the code with RAMSES and redeploy to the robot. That should get you to a new, hopefully, working system.

PresentERS

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

Yara Hallak (yara.hallak@telecom-paris.fr)