Getting Started C++
C++ Language support in eTrice is prototype feature. It is provided in a preliminary state and is subject to breaking changes!
In this tutorial you will have a first look at a very simple eTrice model. The goal is to learn the work flow of eTrice and to understand a few basic features of ROOM.
Preconditions:
Working C++ development environment with Eclipse CDT
- C++ compiler: MinGW/GCC (Windows) or Posix/GCC (Linux)
- Installed C/C++ Development Tools (CDT) in Eclipse
Activated Build Automatically option in Eclipse: Project -> Build Automatically
Recommended: Activate automatic resource refresh in Eclipse: Window -> Preferences -> General -> Workspace
- Refresh using native hooks or polling
- Refresh on access
Optional: Install Trace2UML, an Open Source MSC viewer
Create template project
After installation of eTrice in Eclipse, we can use the wizard to create the template.cpp project, which is a good starting point for new ROOM applications. Select the menu File -> New -> Other (Ctrl+N) and choose eTrice C++ Template Project. To complete the wizard press Next and on the next page Finish.
This will add four projects into your workspace:
- the library projects runtime.c, runtime.cpp and modellib.cpp
- our application project template.cpp.
Now open the TemplateModel.room in the model folder of template.cpp.
In this step we are introduced to the concept of Actors, a fundamental building block in ROOM, and how they are used in eTrice. In essence, an Actor is a representation of an object as a logical machine with defined behavior. Its structure, behavior and protocols are all defined with in an element called an ActorClass. See the documentation on Actors for further information.
The model contains an ActorClass TopActor, which is currently the only active actor. TopActor has a state machine that is intended to output a simple HelloWorld statement. To inspect its behavior graphically, we can open the behavior diagram by right click on Outline View -> TopActor -> Edit Behavior. Alternatively we can place the cursor within the textual notation and press Alt+B.
The state machine has an initial transition that leads to helloState. The state defines an entry code, which is executed during the transition. We can view the details by hovering over the state and edit the code with a double-click or right click and Edit State.
Generate and run application
Now we are ready to translate the model into an executable application. The first step is to generate source files from the model. There are two model projects present in the workspace: the eTrice model library (org.eclipse.etrice.modellib.cpp), and the application project itself (org.eclipse.etrice.template.cpp). Initially we need to run the eTrice model generator for both projects. For subsequent model changes, only the affected project needs to be regenerated (the eTrice model library typically does not change unless there is an update to the library between eTrice versions). Run the eTrice model generator by right clicking on file
org.eclipse.etrice.modellib.cpp/generate_modellib_cpp.launch → Run As → generate_modellib_cpp
and then by doing the same for the file
org.eclipse.etrice.template.cpp/generate_Template.launch → Run As → generate_Template
After that we can build and run the application by right click on file (depending on your operating system, here we chose Windows).
Using MinGW it is necessary to have <MinGW installation dir>\bin in the system PATH.
Your CDT preferences might not enforce a build before launch. In this case you have to invoke the build before launching.
org.eclipse.etrice.template.cpp/run_Template_Windows.launch → Run As → run_Template_Windows
This will trigger the build process, carried out by Eclipse CDT and then subsequently start our application.
 |  |  |
The output of our application is logged in the Console View and it shows the "Hello World". By typing "quit" on the prompt and pressing enter the application terminates regularly.
Open the Message Sequence Chart
After termination, we can inspect the behavior of our application. It is recorded in the form of a MSC (Message Sequence Chart) and can now be used for debugging or documentation purposes. Open subSystemRef_Async.seq in the folder log using the tool Trace2UML (if the file is not present, try to refresh (F5) the folder log).
The Trace2UML (Open Source tool) download links can be found in the Preconditions section of this page.
Yet the MSC is nearly empty having not recorded any interaction between actors. It shows that topActor (full instance path /LogSys/subSystemRef/topActor) has assumed helloState. In the next PingPong tutorial we are going to create a more sophisticated and vivid eTrice application introducing actor building blocks and message protocols.
