Provides logging/oscilloscope/data recording functionality for the KUKA Fast Research Interface. More...

#include <DataLogging.h>

Public Member Functions
	DataLogging (const char RobotName, const char LoggingPath, const char *LoggingFileName, const unsigned int &MaxNumberOfEntries)
	Constructor.
	~DataLogging (void)
	Destructor.
int	PrepareLogging (const unsigned int &ControlScheme, const char *FileIdentifier=NULL)
	Creates the output file and initializes all required class attributes.
void	AddEntry (const tFriMsrData &ReceivedFRIData, const tFriCmdData &SentFRIData)
	Writes control data data to the heap memory.
int	WriteToFile (void)
	Writes the logged data from the heap memory to the output file and closes the file.
Protected Types
enum	ObjectState { PrepareLoggingCalled = 1, WriteToFileCalled = 2 }
	Describes the state of the object (i.e., whether a file is currently opened and in use) More...
Protected Attributes
ObjectState	CurrentObjectState
	Stores the current state of the object.
char *	MachineName
	A pointer to an array of `char` values containing the name of the machine.
char *	OutputPath
	A pointer to an array of `char` values containing the output directory.
char *	OutputFileName
	A pointer to an array of `char` values containing the output file name and its extension.
char *	CompleteOutputFileString
	A pointer to an array of `char` values containing the complete current output file (incl. date and time) name and its directory.
unsigned int	MaximumNumberOfEntries
	Specifies the maximum number of entries to be stored in DataLogging::LoggingMemory.
unsigned int	OutputCounter
	Specifies the total number of calls of DataLogging::AddEntry()
unsigned int	CurrentControlScheme
	Specifies the current control scheme.
float **	LoggingMemory
	A pointer to an array of pointers to arrays of `float` values containing the logged data.
FILE *	OutputFileHandler
	A pointer to the file handler of the output file described by DataLogging::CompleteOutputFileString.

Detailed Description

Provides logging/oscilloscope/data recording functionality for the KUKA Fast Research Interface.

The class has been designed for the Fast Research Interface of the KUKA KUKA Light-Weight Robot IV. It offers the possibility of writing all relevant control data, which is exchanged between the KRC unit and the remote host, into a file that can be read by Matlab, Microsoft Excel, or other software programs.

The constructor DataLogging::DataLogging() allocates a (rather huge) amount of heap memory, to which all the data can be written in each communication (i.e., control) control cycle under real-time conditions. The user can specify the maximum number of entries that will logged. Before the scope functionality can be used, the method DataLogging::PrepareLogging() has to be called. If running with a period of one millisecond, and a maximum number of 60,000, up to one minute can be recorded by calling the method DataLogging::AddEntry() after each data exchange between the remote host and the KRC unit. DataLogging::AddEntry() is real-time capable. At a later time instant (e.g., when the robot was shut down or needs not to be controlled by the remote host anymore), the method DataLogging::WriteToFile() may be called. This method does not work in real-time and writes all entries that were stored in the heap memory into a file. This method can also be used in multi-robot robot environments as each robot arm may be addressed by a name (cf. DataLogging::MachineName).

The actual output file name is unambiguously generated as follows: Path/Date-Time-OptionalUserDefinedString-RobotName-FileName (e.g., /home/lwrcontrol/output/100729-104452-Test-980039-LWRScope.dat).

*Depending on the chosen controller, different control values are written to the log file:

Joint position controller

Cycle number
Time stamp of the KRC node
Time stamp of the remote host
Measured joint torque vector: ActFJ[1,...,7]
Joint position set-point vector (specified by the application running on the remote host): UDesJ[1,...,7]
Measured joint position vector: ActJ[1,...,7]
Commanded joint position vector by the KRC unit: KDesJ[1,...,7]

Cartesian impedance controller

Cycle number
Time stamp of the KRC node
Time stamp of the remote host
Desired stiffness vector (specified by the application running on the remote host): DesK[x,y,z,a,b,c]
Desired damping vector (specified by the application running on the remote host): DesD[x,y,z,a,b,c]
Desired force/torque offset vector (specified by the application running on the remote host): UDesF[x,y,z,a,b,c]

Joint impedance controller

Cycle number
Time stamp of the KRC node
Time stamp of the remote host
Measured joint torque vector: ActFJ[1,...,7]
Joint position set-point vector (specified by the application running on the remote host): UDesJ[1,...,7]
Measured joint position vector: ActJ[1,...,7]
Commanded joint position vector by the KRC unit: KDesJ[1,...,7]
Desired joint stiffness vector (specified by the application running on the remote host): DesKJ[1,...,7]
Desired joint damping vector (specified by the application running on the remote host): DesDJ[1,...,7]
Desired joint torque offset vector (specified by the application running on the remote host): UDesFJ[1,...,7]
Commanded joint position offset vector by the KRC unit: KOffP[1,...,7]

Joint torque controller

Cycle number
Time stamp of the KRC node
Time stamp of the remote host
Measured joint torque vector: ActFJ[1,...,7]
Measured joint position vector: ActJ[1,...,7]
Desired joint torque vector (specified by the application running on the remote host): UDesFJ[1,...,7]

This real-time logging/scope functionality on this low level may be an important tool for debugging and control prototyping purposes as they commonly are done by research and development institutions.

Definition at line 147 of file DataLogging.h.

Member Enumeration Documentation

enum DataLogging::ObjectState [protected]

Describes the state of the object (i.e., whether a file is currently opened and in use)

Enumerator:

PrepareLoggingCalled
WriteToFileCalled

Definition at line 319 of file DataLogging.h.

Constructor & Destructor Documentation

DataLogging::DataLogging	(	const char *	RobotName,
		const char *	LoggingPath,
		const char *	LoggingFileName,
		const unsigned int &	MaxNumberOfEntries
	)

Constructor.

The constructor initializes all class attributes and allocates the required amount of heap memory.

Parameters:

RobotName	A pointer to an array of `char` containing the name of the robot (e.g., its serial number). This value will be used as part of the name of the file, in which the logged data is stored.
LoggingPath	A pointer to an array of `char` containing the directory, in which the logging file will be created (e.g. `"/home/lwrcontrol/output"`).
LoggingFileName	A pointer to an array of `char` containing the final part of the file name as well as the file extension (e.g. `"-LWR-Scope.dat"`).
MaxNumberOfEntries	The maximum number entries that are stored in the heap memory. One entry is required for each message received by the remote host from the KRC unit. To log control data for an amount of time of one minute, the values has to be `60000` if the the controllers run at rate of 1 KHz.

Attention:: The implementation of the constructor does not feature real-time behavior.

See also:: Class DataLogging

Definition at line 88 of file DataLogging.cpp.

DataLogging::~DataLogging ( void )

Destructor.

The destructor free the memory that was allocated by the constructor DataLogging::DataLogging(). If DataLogging::PrepareLogging() was was called, and if DataLogging::WriteToFile() has not been called yet, the destructor calls DataLogging::WriteToFile() first in order to prevent the user from data loss.

Attention:: The implementation of the destructor does not feature real-time behavior.

Definition at line 127 of file DataLogging.cpp.

Member Function Documentation

void DataLogging::AddEntry	(	const tFriMsrData &	ReceivedFRIData,
		const tFriCmdData &	SentFRIData
	)

Writes control data data to the heap memory.

Depending on the chosen controller (specified by DataLogging::CurrentControlScheme) respective data is extracted from ReceivedFRIData and SentFRIData. This data is copied to the heap memory DataLogging::LoggingMemory.

Parameters:

ReceivedFRIData	The complete data package received by the remote host from the KRC unit.
SentFRIData	The complete data package sent by the remote host to the KRC unit.

Remarks:: If the required memory capacity specified by DataLogging::MaximumNumberOfEntries in the constructor DataLogging::DataLogging() is exceeded, the heap memory is used as a ring buffer in order to keep the most recent data stored.

Note:: The implementation of this method is real-time capable.

See also:: Class DataLogging

Todo:: Add further values for the case of FastResearchInterface::CART_IMPEDANCE_CONTROL (in particular pose values).

Definition at line 253 of file DataLogging.cpp.

int DataLogging::PrepareLogging	(	const unsigned int &	ControlScheme,
		const char *	FileIdentifier = `NULL`
	)

Creates the output file and initializes all required class attributes.

The file name for the logging file is generated, the file is opened (i.e., created) using the file handler DataLogging::OutputFileHandler, and all required class attributes are initializes, such that in the following, the DataLogging::AddEntry() can be called after each data exchange between the remote host and the KRC unit in order to perform the actual logging function.

Parameters:

ControlScheme This value has to equal one of the following set:

FastResearchInterface::JOINT_POSITION_CONTROL
- FastResearchInterface::CART_IMPEDANCE_CONTROL
- FastResearchInterface::JOINT_IMPEDANCE_CONTROL

Depending on this value, the logged control data is chosen (see also DataLogging).

Parameters:

FileIdentifier A pointer to an array of char values containing a string to identify the written log file. This parameter is optional.

Returns:

EBADF if the file could not be created.
EINVAL if the parameter ControlScheme is invalid.
EOK otherwise.

Attention:: The implementation of this method does not feature real-time behavior.

See also:: Class DataLogging; FastResearchInterface::LWRControlModes

Definition at line 149 of file DataLogging.cpp.

int DataLogging::WriteToFile ( void )

Writes the logged data from the heap memory to the output file and closes the file.

The data stored in the heap memory at DataLogging::LoggingMemory by the method DataLogging::AddEntry() is written to the file DataLogging::CompleteOutputFileString created and opened by DataLogging::PrepareLogging() and pointed to by the file handler DataLogging::OutputFileHandler.

Only necessary data is written to the output file, that is, if the number of entries in DataLogging::LoggingMemory, is less than DataLogging::MaximumNumberOfEntries, only DataLogging::OutputCounter entries are written to the output file.

Returns: