2.2.2. Communication Objects

Communication objects parameterize the communication patterns and are transmitted by value. The following sections describes how communication objects are modeled and implemented. Additionally, a screencast which demonstrates the modeling of communication objects is available in section 3.1.1.

2.2.2.1. Modeling Communication Objects

Communication objects are modeled in a SmartSoft communication/coordination repository project. The model has the file extension '*.comm' and is located in the folder model/commObject. An empty model is generated once, after you created the project.

Model Communication Objects

Figure 2.9. Model Communication Objects


The model consists of exactly one CommObjectRepository whose name must match the name of the project name. The CommObjectRepository of the project CommBasicObjects for example has to be defined as follows:

CommObjectRepository CommBasicObjects Version 1.0.0 {

}
					

Inside the CommObjectRepository an arbitrary number of communication objects, structs and enumerations can be defined.

A communication object is modeled as follows:

	CommObject <name> {
		<name> : <data type> = <value>
	}
					

The keyword CommObject is used to define a communication object. After the keyword the name of the communication object is given. This name should start with a capital letter. The elements of the communication objects are enclosed by curly braces. They consist of a name which should start with a small letter and a data type which can be optionally assigned with a default value. If no default value should be assigned, the assignment "= <value>" must be omitted. Possible data types are:

  • Boolean

  • CommObjectRef

  • Double

  • EnumRef

  • Float

  • Int8, Int16, Int32, Int64

  • String

  • StructRef

  • UInt8, UInt16, UInt32, UInt64

Furthermore it is possible to use lists of these data types. In order to do so, an opening and closing square bracket has to be written behind the data type. The square brackets enclose the number of elements of the list. If the size of the list should be variable the symbol '*' is used.

If, for example, the velocity and rotation angle of a robot should be transmitted, the corresponding communication object can be defined as follows:

 
	CommObject CommNavigationVelocity {
		vX: Double = .0
		vY: Double = .0
		omega: Double = .0
	}
					

This example can be found in the CommBasicObjects repository. The name of the communication object is CommNavigationVelocity and it contains the attributes vX, vY and omega. All these attributes are of the data type Double and have the default value 0.0. The attribute vX specifies the velocity towards x and the attribute vY specifies the velocity towards y. The attribute omega is used to specify the rotation angle of the robot.

Lists are defined as follows:

	CommObject CommPersonDetectionEventResult {
		environment_id: UInt32= 0
		person_id: UInt32[*]
	}
					

In this example the attribute person_id of the communication object CommPersonDetectionEventResult is a list of any number of UInt32 values.

Additionally to the simple data types it is possible to use EnumRef, StructRef and CommObjectRef. These are references to Enums, Structs or communication objects. To be able to use such a data type the referenced Enum, Struct or communication object has to be defined inside the model. If an Enum, Struct or communication object of another SmartSoft communication/coordination repository should be referenced, the repository has to be imported by using the keyword 'ImportUri'. To import for example the CommBasicObjects repository the following line has to be added at the beginning of the model:

	ImportUri "platform:/resource/CommBasicObjects/model/commObject/CommBasicObjects.comm"
					

Structs are defined with the keyword 'Struct'. After the keyword the name of the Struct is given. The attributes of the Struct are enclosed by curly braces. They consist of a name which should start with a small letter and a data type. Optionally a value can be assigned to the attribute. If no default value should be assigned, the assignment "= <value>" must be omitted. The data types are the same as in the communication object except of the data type CommObjectRef. This data type should not be used in Structs.

	Struct <name> {
		<name> : <data type> = <value>
	}
					

Enumerations are defined with the keyword 'Enum'. After the keyword the name of the enumeration is given. The elements of the enumeration are enclosed by curly braces and consist of a name.

	Enum <name> {
		<name>
	}
					

An attribute which references an Enum can be defined as follows:

	Enum ComparisonState {
		UNKNOWN
		GREATER
		LOWER
		INBETWEEN
	}

	CommObject CommBatteryEvent {
		chargeValue: Double = .0
		state: EnumRef(ComparisonState)
	}
					

This example can be found in the CommBasicObject repository. The enumeration contains four items which specify the used comparison state. Inside the communication object CommBatteryEvent this enumeration is referenced. This means that the attribute state is of the data type ComparisonState. For referencing, it makes no difference whether the enumeration is defined before or after the communication object.

An example for referencing communication objects can be found in the CommBasicObjects repository:

	CommObject CommTimeStamp {
		sec: UInt32 = 0
		usec: UInt32 = 0
	}

	CommObject CommDataFile {
		filename : String
		filesize : UInt32
		timestamp : CommObjectRef(CommTimeStamp)
		data : Int8[*]
		valid : Boolean
	}
					

The communication object CommDataFile contains an attribute timestamp which is of the data type CommTimeStamp.

2.2.2.2. Generated files

The code generator will start as soon as the model of the SmartSoft communication/coordination repository is saved. The code generator creates C++ code for all communication objects of the repository. If a communication object is deleted from the model, the corresponding files inside the src-folder have to be deleted manually. Otherwise the repository will not compile.

The following files are generated into the src-folder:

  • <commObj name>.cc

  • <commObj name>.hh

Standard getter and setter methods are generated automatically. If you need more advanced access methods, you can proceed as follows: In the <commObj name>.cc and <commObj name>.hh files methods of the communication object can be adjusted or added. For example the getter and setter methods of the communication object CommNavigationVelocity were adjusted as follows (CommBasicObjects/src/CommBasicObjects/CommNavigationVelocity.hh):

	inline double get_vX(const double unit = 0.001) const { return getVX() * (0.001 / unit); }
	inline double get_vY(const double unit = 0.001) const { return getVY() * (0.001 / unit); }

	inline void set_vX(double v, const double unit = 0.001) { setVX( v * (1000 * unit) ); }
	inline void set_vY(double v, const double unit = 0.001) { setVY( v * (1000 * unit) ); }
					

These methods are used to return and set the translation velocity in various units. The default unit is millimeters per second.

Add custom functions

Figure 2.10. Add custom functions