Embedded UML Target Debugger - Usage Example

The Embedded UML Target Debugger is a product developed by Willert Software Tools GmbH. It allows you to analyze the software behavior on your target using UML Diagrams. This is similar to a conventional high level language debugger, but on UML level. Basically, the UML Target Debugger will write Sequence Diagrams and Timing Diagrams from the information that the RXF Framework on your target provides.
Care has been taken to ensure that the influence on the real-time behavior of the RXF is as minimal as possible. 

To create the diagrams, the Target Debugger needs information. This information is in the model and also in the generated source code. Minimizing the influence on real-time behavior means: sending as little information as possible from the target to the host.

The Target debugger will read most of the symbolic information it needs from an XML file that was generated during code generation. The user does not have to do anything to do this, the RXF code generation will do that automatically for you. The symbols used in the generated diagrams are coded so that only small pieces of information must be sent physically via the Target Debugger Communication channel.

This communication channel is something that must be implemented when adapting the Target Debugger to the user's environment. It can be anything that can be used on target and host. Serial, TCP/IP, CAN, JTAG or something proprietary. 

This page will guide you through the first steps how to use the Embedded UML Target Debugger.

To be able to work with the Embedded UML Target Debugger and view the target animation,  please first go through the GettingStarted example. We will extend this example to explain the target Debugger.

Basic Functionality - Getting Started with the Embedded UML Target Debugger

For the first steps with our Embedded UML Target Debugger, it is highly recommended to use our example model instead of your own model. 

Basically, there are two things you need to configure: animation details (what info is needed) and the Target Debugger Communication channel (how is physically communicated). For this, you'll need some stereotypes which have tags used for configuration. These stereotypes are located in the package RXFMonitor.

We will use Blinky.rpyx, which is a good starting point.


In your Rhapsody Model make sure that the RXFAnimation stereotype is set on your active component or Configuration. This will trigger the code generator to generate the needed XML file and also the necessary extra code.

Additional you need to set an RXFMonitorIO_* Stereotype to select the communication channel you want to use to transmit Data between the Target and the UML Target Debugger. In this example the ITM channel is selected by using the Stereotype RXFMonitorIO_CortexITM. If no applicable Communication Stereotype is available for which supports your device, please contact Willert Support: support@willert.de

After setting these Stereotypes  some additional Tags will be added to your Component / Configuration.
This is shown in the picture below.


The Subject "RXFAnimation" contains general settings for the Monitor. The Subject "RXFMonitorIO_*" contains settings for the selected communication channel between Target and UML Target Debugger. It can contain additional settings depending on the communication type selected. For example port number for a TCP/IP connection or message ID for a CAN connection. Here are some of the used tags with a description:


Make sure you have an empty GettingStarted IDE project you can deploy to. (If the GettingStarted is not empty, there is a IDETemplateProject that should be empty, just copy and rename it).
You can now perform a Generate/Make/Run in Rhapsody. This will generate code, generate the RXF files and start the deployer. Select the GettingStarted Project (Or the project you just copied) and the deployer will deploy the Rhapsody generated files to your IDE, and build the GettingStarted example.

You may encounter an error message at link time, ... Symbol ITM_RxBuffer multiply defined

In this case you must deselect ITM being used for STDOUT as ITM is used by the monitor:

After a successful build in your IDE, flash the executable to the target but do not start program execution yet! The target program must be reset and stopped. Otherwise, the Embedded UML Target Debugger will miss important information about dynamically created objects the target sends.

Now start the Embedded UML Target Debugger on the PC. Launch the batch file located under <RXF installation Path>\RXF\Tools\TargetDebugger\Embedded_Uml_Target_Debugger.bat.

The Embedded UML Target Debugger first need to read the XML file which has been generated using a simplifier helper during Rhapsody's code generation. This file is called <Component>_<Configuration>.xml and created next to your model. You can open the XML file using File | Open XML File or via button on the toolbar.

Note: Instead of launching the Target Debugger via batch file you can alternatively open it from Rhapsody's "Tools" menu. That gives you the advantage that it also automatically loads the XML file for the active configuration in the Target Debugger.

After the <Component>_<Configuration>.xml file was opened, you have to select the target communication plugin you want to use from the drop-down list by clicking on the IO plug-in selection button:

After selecting a plugin a configuration window will pop up to config the communication with the target.

Important for this plugin before press OK:

After confirming the plugin with "OK" a console message should appear that the plug-in is initialized successfully.

In retrospect it is always possible to change the communication plugin and settings by using the toolbar buttons.

Now switch back to your IDE. Build the deployed sources and start program execution on target, as the Embedded UML Target Debugger now listens for commands sent from target. In the tree view on the left you can now also see values of attributes and states.
You will see something like this:


Explaining the GUI

The Menu

This area contains short cuts to the most common functions of the UML Target Debugger.
The same functions can be found in the tools menu.

The Browser Area

The browser Area is split into three parts:

Objects:
After the Target Debugger is started, the XML file is loaded and the communication channel was setup and started, the target can start sending information.

Views:
The view tab manages your recorded / loaded sessions.
You can generate / edit views on your recorded data.
This means you can filter your recorded data by event information (sender / receiver / event type )
Additional you can save and load such filter views.
Open a selected view in a separate window to compare it with another view.
You can save a selected view to your computer to share it with colleges.
You can save a selected view as *.csv file.

Target:
This tab give you control about the target filter.
This means you can select while runtime which events and instances are send from your Target to the UML Target Debugger.
This can be very important when your model becomes very big and you have to separate which information is send to the UML Target Debugger to avoid a buffer overflow on target side.

The Diagram Area

This area shows your selected view as sequence or timing diagram.

Console

The Console window shows information on actions you perform to get a feedback of what you did.


This is the "normal" functionality of the Target Debugger. There is much more, the following chapters explain (briefly) some of the more advanced features.

Advanced Features


You can also click on an attribute / state: at that moment in runtime, the Embedded UML Target Debugger on the PC will query the target to send the actual value - such information is sent only on request by the PC in order to reduce the I/O traffic as much as possible. The information shown on events is actually transferred in a compact way and not as the strings you see, again to reduce traffic and thus runtime disturbance. The Request for the attribute value / state is send to the target when you collapse the item in the tree view.

Timing Diagrams

The Embedded UML Target Debugger is able to switch from the default sequence diagram view to a timing diagram view. It is a useful diagram similar to the timing diagrams known from technical data sheets to visualize state changes proportional to the time axis.

Zooming in and out is possible using the mouse wheel, if available. You can change the start tick by dragging inside the diagram with mouse or by using the Zoom control below the timing diagram.

Event Injection

It is also possible to inject events by the Embedded UML Target Debugger to stimulate a specific behavior on the target side.



Clicking this button will activate another Window:

To inject an event, you just select the event name, a destination object an press on Inject Event. Alternatively, you can add an event to a sequence to inject more than one event at the same time.

Events may also have standard type parameters, which are supported by the Embedded UML Target Debugger. Parameters / arguments of events will be displayed as integer values inside the animated diagrams. Also, event injection with arguments is possible. If you have selected to inject an event which has parameters (defined in the UML model), a window will pop up and ask for each argument. The value for each argument will be insert as unsigned int value and cast internally to the real data type of the event parameter.

Filtering

On a larger model, showing all events and attributes is confusing, because it will not fit in a window and will lead to overhead. Therefore, we have implemented a filter mechanism on the target side which can be controlled at runtime / compile time.
Change filter while runtime:
Please select the Target tab. Here you find a list of all reactive Objects. By enable / disable the depending instance the filter will be switched on / off on the target side.

Setup Filter while compile time:
If you want to activate the filter while compile time, please use following properties: (hint: select the desired element like a class and inspect its Properties using the Filter: Send)

Please use RXFMonitor::Class::SendEventsToTargetDebugger for classes. This means that all instances of this class will be filtered on target side.
Please use RXFMonitor::Relation::SendEventsToTargetDebugger for Parts or Compositions. This is usefull if you have more than one instance of a class and only want to see the behavior of special instance.

If you set both values on "unchecked" for your active configuration, all instances are filtered on the target.

Communication Buffer Overflows

When an event is consumed by the user application, event information is sent to the UML Target Debugger. This information is stored inside a buffer which is send to the UML Target Debugger inside a monitor task. If the user application takes too much execution time and the monitor task has no chance to send the content of the buffer to the UML Target Debugger the buffer will overflow at some point. If this happen event information is lost and a buffer overflow command is send to the UML Target Debugger to indicate the user that data has been lost. 

More Information

To make it easier to navigate to your recent used XML files, you can select them in the file menu:

FAQ

If you have any questions, please have a look at the Animation FAQ page or contact our support team.

Model Driven Automatic Tests execution on a Realtime Target

You can also use TestConductor in combination with Animation.