Skip to main content

Getting Started C++

caution

C++ Language support in eTrice is a 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​

Open template project​

Download the eTrice C++ template project from the eTrice releases page (in the Quellcode archive under examples/org.eclipse.etrice.template.cpp). Open a new empty workspace folder and copy the extracted folder into your new workspace folder. Open workspace the folder in VSCode using File → Open Folder.

note

You will also need the runtime.cpp and modellib.cpp projects found in the runtime folder. Copy them into your workspace folder.

Now open TemplateModel.room in the model folder of the template.cpp project.

VSCode with TemplateModel.room open

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 within 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, use the Open Behavior Diagram code lens above the TopActor class definition.

CodeLensActorClass

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.

Generate source code​

Now we are ready to translate the model into source files using the standalone eTrice C++ generator (see Standalone Generators).

First, generate the model library. This only needs to be done once after downloading the template project:

etrice-cpp -genDir org.eclipse.etrice.modellib.cpp/src-gen \
  -modelpath org.eclipse.etrice.modellib.cpp/model \
  org.eclipse.etrice.modellib.cpp/model/etrice/api/*.room

Then, generate the application:

etrice-cpp -genDir org.eclipse.etrice.template.cpp/src-gen \
  -modelpath "org.eclipse.etrice.modellib.cpp/model;org.eclipse.etrice.template.cpp/model" \
  org.eclipse.etrice.template.cpp/model/TemplateMapping.etmap \
  org.eclipse.etrice.template.cpp/model/TemplateModel.room \
  org.eclipse.etrice.template.cpp/model/TemplatePhysical.etphys

Build and run application​

After generating, build the project using your C++ toolchain.

The output of the application is logged to the console and shows "Hello World". By typing "quit" on the prompt and pressing enter the application terminates regularly.

image

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 the folder log).

note

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.

image