The Reporting Component

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation, with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of this license can be found at http://www.fsf.org/copyleft/fdl.html.

Table of Contents

1. Introduction

1.1. Principle

2. Setup Procedure

2.1. Property Configuration File
2.2. Reporting Configuration File
2.3. Reading the configuration files
2.4. Scripting commands

1. Introduction

This document describes the Orocos OCL::ReportingComponent for monitoring and capturing data exchanged between Orocos components.

1.1. Principle

Each Orocos component can have one or more data ports. One can configure the reporting components such that one or more ports are captured of one or more peer components. The sample rate and the file format can be selected.

A common usage scenario of the OCL::ReportingComponent goes as follows. An Orocos application is created which contains a reporting component and various other components. The reporting component is peer-connected to all components which must be monitored. An XML file or script command defines which data ports to log. When the reporting component is started, it reads the ports and writes the exchanged data to a file at a given sample rate.

Figure 1. Component Reporting Example

One can not use the OCL::ReportingComponent directly but must use a derived component which implements the method of writing out the data. There exists two variants: OCL::FileReporting for writing data to a file and OCL::ConsoleReporting which prints the data directly to the screen. These two examples can aid you in writing your own data format or to transfer data over a network connection.

2. Setup Procedure

The OCL::ReportingComponent is configured using two XML files:

One for setting the component's properties
One for describing which components and ports to monitor

In order to report data of other components, they must be added as a Peer to the reporting component. The following C++ setup code does this for the example above (Figure 1, “Component Reporting Example”):

  #include <ocl/FileReporting.hpp>

  // ...
  OCL::FileReporting reporter("Reporter");
  Controller controller("Controller");
  Plant      plant("Plant");
  Camera     cam0("Camera");

  reporter.addPeer( &controller );
  reporter.addPeer( &camera );
  controller.addPeer( &plant );

2.1. Property Configuration File

This is an example property file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "cpf.dtd">
<properties>

  <simple name="AutoTrigger" type="boolean"><description>When set to 1, the data is taken upon each update(), otherwise, the data is only taken when the user invokes 'snapshot()'.</description><value>1</value></simple>

  <simple name="Configuration" type="string"><description>The name of the property file which lists what is to be reported.</description><value>configuration.cpf</value></simple>

  <simple name="WriteHeader" type="boolean"><description>Set to true to start each report with a header.</description><value>1</value></simple>

</properties>

The AutoTrigger property toggles if the data is captured at the time a new line is written to file or at a user determined time. If AutoTrigger is set to false, a data snapshot is taken when the user invokes the snapshot() method of the ReportingComponent.

The Configuration property contains the location of the configuration XML file for reporting data ports.

If WriteHeader is set to true, a header will be written describing the file format layout.

2.2. Reporting Configuration File

This is an example configuration.cpf file for reporting data of peer components:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "cpf.dtd">
<properties>
  <simple name="Component" type="string"><value>Camera</value></simple>

  <simple name="Port" type="string"><value>Controller.SensorValues</value></simple>
  <simple name="Port" type="string"><value>Controller.SteeringSignals</value></simple>
</properties>

As the example shows (see also Figure 1, “Component Reporting Example”), a complete component can be monitored (Camera) or specific ports of a peer component can be monitored. The reporting component can monitor any data type as long as it is known in the Orocos type system. Extending the type system is explained in the manuals of the Real-Time Toolkit.

2.3. Reading the configuration files

The property file of the reporting component can be read with the script method:

  marshalling.readProperties("reporting.cpf")

This file tells the reporter where it can find the configuration file and sets the options shown above.

The reporting configuration file can be read with the script method:

  load()

The load method will look up the Configuration property and load the contents of that file. There is also a

  store()

method for writing the current configuration to that file.

2.4. Scripting commands

The scripting commands of the reporting components can be listed using the this command on the TaskBrowser. Below is a snippet of the output:

  Method     : bool load( )
   Read the Configuration file.
  Method     : bool reportComponent( string const& Component )
   Add a Component for reporting. Only works if Component is connected.
   Component : Name of the Component
  Method     : bool reportData( string const& Component, string const& DataObject )
   Add a Component's DataSource for reporting. Only works if DataObject exists and Component is connected.
   Component : Name of the Component
   DataObject : Name of the DataObject. For example, a property or attribute.
  Method     : bool reportPort( string const& Component, string const& Port )
   Add a Component's Connection or Port for reporting.
   Component : Name of the Component
   Port : Name of the Port to the connection.
  Method     : bool screenComponent( string const& Component )
   Display the variables and ports of a Component.
   Component : Name of the Component
  Method     : void snapshot( )
   Take a new shapshot of the data and set the timestamp.
  Method     : bool store( )
   Write the Configuration file.
  Method     : bool unreportComponent( string const& Component )
   Remove a Component from reporting.
   Component : Name of the Component
  Method     : bool unreportData( string const& Component, string const& DataObject )
   Remove a DataObject from reporting.
   Component : Name of the Component
   DataObject : Name of the DataObject.
  Method     : bool unreportPort( string const& Component, string const& Port )
   Remove a Connection for reporting.
   Component : Name of the Component
   Port : Name of the Port to the connection.