2.2. Config Files

The ${VORAUS_CONFIG_DIR} folder contains the following elements:

Table 1 Voraus Config Directory Overview

Name	File/Folder	Description	Section
config.json	File	Main configuration file containing general settings for voraus Robot Control	Main Configuration File
robots/	Folder	Contains robot description files	Robot Configs
tools/	Folder	Contains factory versions of supported tools	Tool Configs
rtSettings/	Folder	Realtime settings	rt Settings Configs
kuka/	Folder	KUKA specific configs (RSI (KUKA.RobotSensorInterface) & T1)	KUKA Configs
compliantBehaviour/	Folder	Impedance control parameter	Compliant Behaviour Configs
Yu/	Folder	Yu Industrial robot specific parameter (part numbers)	Yu Configs

In addition to the directories defined in the table above, some robot drivers might define additional subdirectories, which are not explicitly listed here. These subdirectories will be explained in the corresponding robot integration sections in future versions of this documentation. If you have any questions in the meantime, please contact the voraus support.

2.2.1. Main Configuration File

The main configuration file, the config.json, contains basic system settings.

Table 2 Main Configuration File

Parameter	Type	Description	Required/Optional
CheckBoundaryPlanes	bool	Checks the Collision Model of the Robot and Collision Model of the Tool against defined non-safe boundary planes, which can be set by the user	required
CheckCartesianConstraints	bool	Check the Collision Model of the Robot and Collision Model of the Tool against a defined Cartesian workspace cuboid, which is defined in Cartesian Constraints	required
CheckForbiddenVolumes	bool	Check the Collision Model of the Robot and Collision Model of the Tool against defined non-safe forbidden volumes which can be set by the user	required
CheckSelfCollision	bool	Check the Collision Model of the Robot and Collision Model of the Tool against self collisions	required
WatchDogToleranceSeconds	double	The cycle time may exceed this value without an error being set. If the cycle time is exceeded but the tolerance is not, a warning is written to the log. The cycle time is robot specific and configured in Robot Configs. The value is defined in \([\mathrm{s}]\).	optional, default value: 0.001
SystemParameter	struct	Basic system settings, see Table System Parameter File	required

System Parameter

The system parameters are a struct in the main configuration file and define the basic system settings.

Table 3 System Parameter File

Parameter	Type	Description	Required/Optional
lookahead_horizon	unsigned long	Defines the maximum number of motion objects that can be prepared at the same time	required
IPOfilter_cycles_1	unsigned long	Number of cycles for the internal interpolator filter, used for smoothing the path except when transitioning into a brake ramp (see Axes Stop Rapid for more information)	required
IPOfilter_cycles_2	unsigned long	Number of cycles for the internal interpolator filter, used for smoothing the path except when transitioning into a brake ramp (see Axes Stop Rapid for more information)	required
ManualMode_cycles	unsigned long	Number of cycles to maintain a manually controlled movement command before a keep alive signal is expected	required
Number_of_preview_points	unsigned long	Number of path-preview points of each motion command	required
VerboseOPCUADebugInformation	bool	Print received OPC UA commands JSON string to console and log file	required
FieldbusParameter	struct	See Fieldbus Parameter	required
transitionTimeAxesStop	double	Transition time for axis-based stops, which defines the time required to enter the braking ramp by transitioning from the current acceleration to deceleration, and to exit the braking ramp by transitioning from deceleration to zero acceleration. It is specified in seconds \([\mathrm{s}]\). The value must be at least twice the cycle time. If it is not an integer multiple of twice the cycle time, it is rounded accordingly. The higher the value, the longer rapid stops will take, or the higher the deceleration will be during a time-based axis stop. For time-based axis stops, the value must not exceed half of the stop duration.	optional, default value: 0.1 s

Fieldbus Parameter

The fieldbus parameters MissingFrameTolerance and TimeOut are only used by the Yu Industrial robot. Those are optional parameters for other robot types.

Table 4 Fieldbus Parameter

Parameter	Type	Description	Required/Optional
MissingFrameTolerance	int	Tolerance of missing frames in a row (only used by Yu Industrial robot)	optional
InterfaceName	string	Name of the Ethernet device to be used, which can be overwritten by CLI or ENV variables	required
TimeOut	string	Receive process data timeout in \([\mathrm{µs}]\) (only used by Yu Industrial robot)	optional, default value: 500 µs

2.2.2. Robot Configs

Robot configuration files must use the same name as the corresponding ${VORAUS__robot__robotType} to ensure correct linkage between configuration and runtime components. For example, if you specified VORAUS__robot__robotType="VORAUS_INDUSTRIAL_ROBOT", the corresponding robot configuration file must be located at ${VORAUS_DATA_DIR}/robots/VORAUS_INDUSTRIAL_ROBOT.json.

Fieldbus Configs

Some robot types additionally require dedicated fieldbus configurations from an additional subfolder ${VORAUS__robot__robotType}_FieldbusConfig. These consist of an ENI (EtherCAT Network Information) file, an EtherCAT mapping, and a specific fieldbus configuration, which together define the communication structure and device parameters for the robot’s fieldbus network.

Table 5 Fieldbus Config Files

File	Description
config.json	Conversion of SI units (used by voraus) to fieldbus units, including consideration of couplings and offsets
ethercat_eni.xml	ENI (EtherCAT Network Information) file
ethercat_mapping.json	Mapping of ENI file variables to internal variables

Robot Config File

The robot configuration file contains robot settings, as defined in the following table.

Table 6 Robot Configuration File

Parameter	Type	Description	Required/Optional
Axes	Vector of structs	Axes specific data	required
CollisionModel	struct	Representation of the robot structure using multiple collision volumes, defining possible collision modules that may collide with each other (see Collision Model of the Robot)	required
FieldbusType	string	Fieldbus type	required
KinematicsType	string	Description of the robot kinematics	required
MaxCartesianVelocity	double	Velocity limit in \([\mathrm{m/s}]\) for TCP (Tool Center Point) and elbow (if configured in Elbow monitoring)	required
Number_of_modules	unsigned int	Number of axes (must currently always be 6)	required
RobotConfigVersion	unsigned long	Version of this config file	required
Name	string	Robot name: will be published via OPC UA	required
elbow	struct	Elbow monitoring definitions	required
CycleTime	double	Cycle time of the main thread, which must correspond to the fieldbus cycle time \([\mathrm{s}]\)	required
Manufacturer	string	Manufacturer name: will be published via OPC UA	optional, default value: unknown
MSC	struct	Only used by Yu Industrial robot	optional, default value: none
MediaFlange	struct	Only used by Yu Industrial robot	optional, default value: none
monitorMeasuredValues	struct	Monitor Measured Values of TCP velocity and force	optional
AxesPositionLimitsRelative	Vector of structs	Relative position limits between two axes	optional, default value: no relative limits
PoseRobotCSToCS0	Vector of doubles	Transformation between Robot CS (Coordinate System) and the first DH coordinate system Defined by a Cartesian vector {x, y, z, A, B, C}. x,y,z: in \([\mathrm{m}]\), A,B,C: KARDAN angles in \([\mathrm{°}]\) Not tested on all robots yet!	optional, default value: {0.0, 0.0, 0.0, 0.0, 0.0, 0.0}
ioInterfaces	struct	Definition of available IO Interfaces	optional, default value: no IO interfaces
partnumber	string	Part number of the robot: will be published via OPC UA	optional, default value: unknown

Axes

Each axis is specified by several structs:

• Axes.DriveParameter contain general settings such as axis type and mounting direction.

• Axes.Limits contain manufacturer specifications such as position or speed limits.

• Axes.DH specify the kinematic structure of the robot structure.

• Axes.LinkDynamics are used as the basis for torque calculations in the dynamic model.

Table 7 Axes

Parameter	Type	Description	Required/Optional
DriveParameters	struct	Set of parameter of a robot drive	required
Limits	struct	Set of limitations of a robot drive	required
DH	struct	Set of DH parameters	required
LinkDynamics	struct	Set of link dynamic parameters	required

Axes.DriveParameters

Drive parameters specify the general specifications of the axis. These include the axis type, mounting parameters, gearbox and friction coefficients.

Table 8 Axes.DriveParameter

Parameter	Type	Description	Required/Optional
Partnumber	string	Only used by Yu Industrial robot	optional
MountingDirection	int	Only used by Yu Industrial robot	optional
RotationDirection	int	Definition of the rotation direction, where the value must be 1 or -1: Rotational axes: 1: around z-axis of corresponding DH-CS using the right-hand rule -1: opposite direction Prismatic axes: 1: in direction of the z-axis of corresponding DH-CS -1: opposite direction	optional, default value: 1
AxisType	string	Definition of the axis type, with supported values ROTATIONAL and PRISMATIC	optional, default value: ROTATIONAL
GearRatio	double	Gear ratio as decimal value	optional, default value: 1.0
FrictionViscous	double	Viscous friction coefficients The units can vary depending on the used friction model. This value is calculated at the output side of the gearbox.	optional, default value: {0.0}
FrictionCoulomb	double	Coulomb friction coefficient The units can vary depending on the used friction model. This value is calculated at the output side of the gearbox.	optional, default value: {0.0}
MotorInertia	double	Combined inertia of motor and gearbox in \([\mathrm{kg*m^2}]\) This value is calculated at the output side of the gearbox.	optional, default value: {0.0}
ratedMotorTorque	double	Rated motor torque in \([\mathrm{Nm}]\) The value must be positive and greater than zero. It should match the motor parameters given by the manufacturer. This value is given at the motor side, without consideration of the gearbox.	optional

Note

GearRatio, FrictionViscous, FrictionCoulomb, and MotorInertia are supported by a few robots. ratedMotorTorque depends on the configuration of the fieldbus and the robot. If you have any questions, please contact the voraus support.

Axes.Limits

This struct is used to specify the manufacturer limits of the drives. Most of this limits will be used within the MACHINE limit set which is explained at Limit Set. Further information about limits in voraus Robot Control can be found at Overview of the Configurable Limitations.

All axes limits are defined on the load side, with:

• Limits of rotational axes are defined in \([\mathrm{°}], [\mathrm{°/s}], [\mathrm{°/s^2}]\) or \([\mathrm{Nm}]\).

• Limit of prismatic axes are defined in \([\mathrm{m}], [\mathrm{m/s}], [\mathrm{m/s^2}]\) or \([\mathrm{N}]\).

Table 9 Axes.Limits

Parameter	Type	Description	Required/Optional
MaxVelocity	double	Maximum velocity of the drives in \([\mathrm{°/s}]\) or \([\mathrm{m/s}]\)	required
MaxAcceleration	double	Maximum acceleration of the drives in \([\mathrm{°/s^2}]\) or \([\mathrm{m/s^2}]\)	required
MaxFollowingError	double	Maximum following error of the drives in \([\mathrm{°}]\) or \([\mathrm{m}]\)	required
PositionLimitationPositive	double	Maximum position limit of the drives in \([\mathrm{°}]\) or \([\mathrm{m}]\)	required
PositionLimitationNegative	double	Minimum position limit of the drives in \([\mathrm{°}]\) or \([\mathrm{m}]\)	required
MaxTorque	double	Maximum torque/force of the drives in \([\mathrm{Nm}]\) or \([\mathrm{N}]\)	optional, default value: numeric max value

Axes.DH

The position and orientation of the robot axes is described using the Denavit-Hartenberg (DH) convention. In the following section, the coordinate system fixed to each robot link is called DH coordinate system (DH-CS). The DH parameters of the table below correspond to the classic DH convention.xis.

Table 10 Axes.DH

Parameter	Type	Description	Required/Optional
a	double	Distance to the next DH coordinate system measured perpendicular to the joints axes \([\mathrm{m}]\)	required
d	double	Distance to the next DH coordinate system measured along the joint axis \([\mathrm{m}]\)	required
alpha	double	Rotation angle to the next DH coordinate system measured about a line perpendicular to the joints axes \([\mathrm{°}]\)	required
theta	double	Twist angle to the next DH coordinate system measured about the joint axis \([\mathrm{°}]\)	optional, default value: 0.0

Axes.LinkDynamics

The inertia tensor is measured with respect to a coordinate system located on the center of mass and is parallel to the DH coordinate system.

Table 11 Axes.LinkDynamics

Parameter	Type	Description	Required/Optional
m	double	Mass of this axis \([\mathrm{kg}]\)	required
Ixx	double	Element of the inertia tensor of each axis \([\mathrm{kg * m^2}]\)	required
Iyy	double	Element of the inertia tensor of each axis \([\mathrm{kg * m^2}]\)	required
Izz	double	Element of the inertia tensor of each axis \([\mathrm{kg * m^2}]\)	required
Ixy	double	Element of the inertia tensor of each axis \([\mathrm{kg * m^2}]\)	required
Ixz	double	Element of the inertia tensor of each axis \([\mathrm{kg * m^2}]\)	required
Iyz	double	Element of the inertia tensor of each axis \([\mathrm{kg * m^2}]\)	required
XC	double	Center of mass in x direction with respect to the DH coordinate system \([\mathrm{m}]\)	required
YC	double	Center of mass in y direction with respect to the DH coordinate system \([\mathrm{m}]\)	required
ZC	double	Center of mass in z direction with respect to the DH coordinate system \([\mathrm{m}]\)	required

Collision Model of the Robot

Representation of the robot structure using multiple collision volumes.

Collision modules that may collide with each other can be monitored as collision pairs to detect and prevent self collisions or violations of Cartesian workspaces, see also Collision Model.

Table 12 Robot Collision Model

Parameter	Type	Description	Required/Optional
CollisionPairs	Vector of structs	Definition of possible collision volumes, that may collide with each other	required
Capsules	Vector of structs	Representation of the robot structure with geometric capsule volumes	optional, default value: No volumes
Cylinders	Vector of structs	Representation of the robot structure with geometric cylindrical volumes	optional, default value: No volumes
Spheres	Vector of structs	Representation of the robot structure with geometric sphere volumes	optional, default value: No volumes

CollisionModel.CollisionPairs

Collision pairs are used to monitor and prevent self-collisions. The distance between the defined collision volumes is monitored cyclically and within the path pre-interpolation. A collision pair can consist of different volume types.

Table 13 CollisionModel.CollisionPairs

Parameter	Type	Description	Required/Optional
Pair	Vector of stings	Must contain two strings that match the names of the collision volumes that may collide	required
MinDistance	double	Minimum permitted distance between both collision volumes in \([\mathrm{m}]\). If the distance is violated during operation or path planning, an error is set	required
ReduceDistance	double	Distance in \([\mathrm{m}]\) between both collision volumes at which the robot starts to slow down when jogging to prevent self collisions	required

CollisionModel.Capsules and CollisionModel.Cylinders

Representation of a robot structure part using a cylinder or capsule volume. A capsule is a 3D geometric shape consisting of a cylinder with hemispherical caps on each end.

Cylinders and capsules are defined by a radius, a cap, and a bottom point.

Table 14 CollisionModel.Capsules and CollisionModel.Cylinders

Parameter	Type	Description	Required/Optional
Name	string	Unique volume name	required
RefCS	unsigned int	Reference coordinate system to define the cap and the bottom point: 0: Robot CS, Values > 0 depend on CoordinateSystemGroup: DH: Value means the n-th DH Coordinate System (T0n), Passive: Index of CS fixed to passive joint/segments	required
CheckAgainstCartesianConstraint	bool	Check this volume against cartesian workspace constraints	required
CoordinateSystemGroup	int	0 (DH_CS): The CS in the DH group are based on the DH convention for serial kinematics 1 (Passive_CS): The CS in the passive group are defined using joint coordinates of passive joints, as in the case of parallelogram kinematics	optional, default value: 0 (DH_CS)
Radius	double	Object radius \([\mathrm{m}]\)	required
CapPoint	Vector of doubles	Position of the cap point, defined in the Reference CS {x,y,z} all in \([\mathrm{m}]\)	required
BottomPoint	Vector of doubles	Position of the bottom point, defined in the Reference CS {x,y,z} all in \([\mathrm{m}]\)	required

CollisionModel.Spheres

Representation of a robot structure part using a spherical volume.

A sphere is defined by a radius and a center point.

Table 15 CollisionModel.Spheres

Parameter	Type	Description	Required/Optional
Name	string	Unique volume name	required
RefCS	unsigned int	Reference coordinate system to define the center point: 0: Robot CS, Values > 0 depend on CoordinateSystemGroup: DH: Value means the n-th DH Coordinate System (T0n), Passive: Index of CS fixed to passive joint/segments	required
CheckAgainstCartesianConstraints	bool	Check this volume against cartesian workspace constraints	required
CoordinateSystemGroup	int	0 (DH_CS ): The CS in the DH group is based on the DH convention for serial kinematics 1 (Passive_CS): The CS in the passive group is defined using joint coordinates of passive joints, as in the case of parallelogram kinematics	optional, default value: 0 (DH_CS)
Radius	double	Object radius \([\mathrm{m}]\)	required
CenterPoint	Vector of doubles	Position of the center point, defined in the Reference CS {x,y,z} all in \([\mathrm{m}]\)	required

Elbow

Elbow monitoring can be switched on and off depending on the robot. The location of the elbow is defined within the kinematic type.

Table 16 Elbow

Parameter	Type	Description	Required/Optional
monitorPosition	bool	Monitor elbow position	required
monitorVelocity	bool	Monitor elbow velocity	required

MSC and Media Flange

Only used by Yu Industrial robot! It will be used to compare with the actual robot setup.

Table 17 MSC and MediaFlange

Parameter	Type	Description	Required/Optional
Partnumber	string	Configuration of the expected partnumber	required

Monitor Measured Values

Depending on the robot system and the quality of the measurement data, it may or may not be advisable to use MonitorMeasuredValues to monitor the data.

Table 18 MonitorMeasuredValues

Parameter	Type	Description	Required/Optional
tcpVelocity	bool	Monitoring of the measured TCP velocity	optional, default value: true
tcpForce	bool	Monitoring of the measured TCP force	optional, default value: false

Axes Position Limits Relative

Depending on the robot type, it can be useful to use AxesPositionLimitsRelative to define relative position limits between two axes. These can be used, for example, to prevent self-collisions.

Table 19 AxesPositionLimitsRelative

Parameter	Type	Description	Required/Optional
Axes	Vector of unsigned int	Must contain two values to define the relevant axes. Both axes must be from the same type (ROTATIONAL or PRISMATIC). Starts counting at 1 for axis 1. The second axis will be subtracted from the first axis. Example: [3, 1] -> A3 - A1 (limit between A3 and A1)	required
Limit	string	Defines the limit type: Lower: Difference must be greater or equal to value Upper: Difference must be smaller or equal to value	required
Value	double	Limit value between both axes, in \([\mathrm{m}]\) or \([\mathrm{°}]\) (depending on axis type)	required

IO Interfaces

The ioInterfaces is the basic definition of how many IOs are supported by the robot interfaces. Depending on the integration, the IOs must be aligned with the fieldbus configuration.

Note

The tool interface is not used yet.

Table 20 ioInterfaces

Parameter	Type	Description	Required/Optional
tool	struct	Definition of IOs at the tool flange	optional, default value: No IOs
controlCabinet	struct	Definition of IOs at the control cabinet	optional, default value: No IOs

Defines the number of digital and analog IOs at this interface.

Table 21 IOs

Parameter	Type	Description	Required/Optional
digitalInputs	unsigned int	Number of digital inputs	required
digitalOutputs	unsigned int	Number of digital outputs	required
analogInputs	unsigned int	Number of analog inputs	required
analogOutputs	unsigned int	Number of analog outputs	required

2.2.3. Tool Configs

Tool files are stored in both the config and data directories. The config directory contains officially supported tools that are not editable by the user. These files serve as a backup source in case an original tool is accidentally deleted. The data directory, (data_dir/tools/) on the other hand, contains all tools that have been created or modified by the user. If a tool exists in both the config and data directories, the system automatically prioritizes and loads the version from the data directory.

The tool configuration file contains the following settings:

Table 22 Tool Configuration File

Parameter	Type	Description	Required/Optional
Name	string	Unique tool name	required
ToolTransformation	struct	Transformation from Flange CS into Tool CS	required
Mass	double	Tool mass in \([\mathrm{kg}]\)	required
CenterOfMass	struct	Center of tool mass defined in Flange CS	required
Inertia	struct	Tool inertia	required
CollisionModel	struct	Representation of the tool structure using multiple collision volumes, defining possible volumes that may collide with the robot structure	required

The tool config has a number of parameters that can only be used by Yu. An overview can be found in the following table.

Note

Since commands and states refer to tool IOs that are only used by the Yu Industrial, they are provisionally classified as Yu-specific.

Table 23 Yu Industrial Parameter

Parameter	Type	Description	Required/Optional
InitOutputs	Vector of bool	Outputs which will be set after selecting the tool	required
States	Vector of structs	Tool state definition	required
Commands	Vector of structs	Tool command definition	required
Powered	uint8	Definition of power supply source 0: no power, 1: spring probe, 2: M8, 3: both	optional
SpringProbeAnalogMode	uint8	Definition of analog mode of AI1 and AI2: 0: current/voltage depending on analog input definition 1: Modbus	optional, default value: 0
SpringProbeDigitalMode	uint8	Defines Pin8 of the spring probe: 0: Digital Out (DO2) 1: Digital In (DI3) 2: IOLink (IOL0)	optional, default value: 0
M8_8AnalogMode	uint8	Definition of analog mode of AI3 and AI4: 0: current/voltage depending on analog input definition 1: Modbus	optional, default value: 0
M8_8DigitalMode	uint8	Defines Pin 6 (M8_8): 0: Digital Out (DO5) 1: Digital In (DI6) 2: IOLink (IOL1)	optional, default value: 0

Tool Transformation

ToolTransformation defines the transformation from Flange CS into Tool CS:

Table 24 ToolTransformation

Parameter	Type	Description	Required/Optional
x	double	x-coordinate \([\mathrm{m}]\) of transformation from Flange CS into Tool CS	required
y	double	y-coordinate \([\mathrm{m}]\) of transformation from Flange CS into Tool CS	required
z	double	z-coordinate \([\mathrm{m}]\) of transformation from Flange CS into Tool CS	required
A	double	x-rotation (KARDAN) \([\mathrm{°}]\) of transformation from Flange CS into Tool CS	required
B	double	y-rotation (KARDAN) \([\mathrm{°}]\) of transformation from Flange CS into Tool CS	required
C	double	z-rotation (KARDAN) \([\mathrm{°}]\) of transformation from Flange CS into Tool CS	required

For more information on the Tool CS and other coordinate systems, see the section Coordinate Systems Overview in the documentation.

Center Of Mass

CenterOfMass is the definition of the tool center of mass.

Table 25 CenterOfMass

Parameter	Type	Description	Required/Optional
x	double	Tool center of mass in x-direction of the Flange CS \([\mathrm{m}]\)	required
y	double	Tool center of mass in y-direction of the Flange CS \([\mathrm{m}]\)	required
z	double	Tool center of mass in z-direction of the Flange CS \([\mathrm{m}]\)	required

Inertia

Definition of the tool inertia.

Table 26 Inertia

Parameter	Type	Description	Required/Optional
Ixx	double	Tool inertia in \([\mathrm{kg * m^2}]\)	required
Iyy	double	Tool inertia in \([\mathrm{kg * m^2}]\)	required
Izz	double	Tool inertia in \([\mathrm{kg * m^2}]\)	required
Ixy	double	Tool inertia in \([\mathrm{kg * m^2}]\)	required
Ixz	double	Tool inertia in \([\mathrm{kg * m^2}]\)	required
Izz	double	Tool inertia in \([\mathrm{kg * m^2}]\)	required

Collision Model of the Tool

The Tool Collision Model section defines the collision model specific to the tool. While the configuration and parameters are defined independently, they are chosen to be comparable to those used in the robot collision model described in section Collision Model of the Robot.

The only extension is that collision pairs can contain volumes from both the robot and tool collision models.

States

States is a configuration that is currently specific to the Yu Industrial robot and will be revised in the future to support a more general setup.

Note

Digital/Analog outputs are the Tool IOs.

Table 27 States

Parameter	Type	Description	Required/Optional
Name	string	Unique state name	required
Dout	Vector of int	Digital outputs: 1: high 0: low else: ignored	required
Din	Vector of int	Digital inputs: 1: high 0: low else: ignored	required
Ain	Vector of struct	Analog input definitions. If defined it must contain 4 entries for the Yu Industrial robot	optional, default value: No analog input

Analog Input Definition

Table 28 Ain

Parameter	Type	Description	Required/Optional
Mode	int	-1: Disabled 0: Voltage 1: Current	required
MinValue	double	Minimal value in \([\mathrm{V}]\) or \([\mathrm{mA}]\) depending on Mode	required
MaxValue	double	Maximal value in \([\mathrm{V}]\) or \([\mathrm{mA}]\) depending on Mode	required

Command

Command is a configuration that is currently specific to the Yu Industrial robot and will be revised in the future to support a more general setup.

Note

Digital/Analog outputs are the Tool IOs.

Table 29 States

Parameter	Type	Description	Required/Optional
Name	string	Unique command name	required
Dout	Vector of int	Digital outputs which should be set: -1: set to low 1: set to high 0: no change	required

2.2.4. rt Settings Configs

The rtSettings.json config file contains the available realtime configurations. It provides options for memory management, thread configuration and CPU related properties. An example for the config file is given in Example for rtSettings.json.

Note

The realtime settings are only applied if the environment variable VRC_USE_REALTIME_ENVIRONMENT is set to True. Otherwise, all realtime settings are deactivated, the rtSettings.json config file will not be read, and the voraus Robot Control runs in a non-realtime environment. See the environment variable section Realtime and Performance Settings for more details.

Table 30 Realtime Settings

Parameter	Type	Description	Required/Optional
IRQSettings	struct	Adjusts the realtime priorities for all irq (interrupt request) processes of the used interface and can be overwritten by CLI or ENV variables.	required
lockMemory	bool	Locks all current and future memory of the process into RAM, preventing it from being swapped out. This ensures predictable, low-latency performance by eliminating page faults during critical operations and can be overwritten by CLI or ENV variables.	required
checkForRealtimeKernel	bool	Checks that the system is running with a realtime enabled kernel and terminates if this check fails. This setting can be overwritten by CLI or ENV variables.	required
preventSleepStates	bool	Prevents the CPU from entering deep sleep states and can be overwritten by CLI or ENV variables.	required
threadSettings	struct	Thread specific settings	required

IRQ Settings

Adjusts the RT priorities for all irq (interrupt request) processes of the configured fieldbus network interface.

Table 31 IRQSettings

Parameter	Type	Description	Required/Optional
adjustIRQSettings	bool	No priority modification if false	required
priority	unsigned int	New priority [0, 99]	required

Thread Settings

Specifies thread settings for all spawned threads. Each thread setting is specified by a threadSettings struct.

Table 32 threadSettings

Parameter	Type	Description	Required/Optional
main	struct	Main thread Note: Due to the frequent need to pin this thread, the environment variable VRC_CPUAFFINITY_MAIN offers the possibility to set the CPU affinity to a specific CPU id and automatically mark it as isolated.	optional, default value: 49
sdo	struct	SDO communication	optional, default value: 47
motionplanner	struct	Motion planning	optional, default value: 39
opcua	struct	OPC UA communication	optional, default value: 21
filewriter	struct	Create and delete files	optional, default value: 21
logDataToFile	struct	Live data logging	optional, default value: 21
crashlogger	struct	Crash logs after error or shutdown	optional, default value: 0
ibvEcatMonitor	struct	ibv ecat monitoring	optional, default value: 0
ibvEcatDiagnostics	struct	ibv diagnostics	optional, default value: 0
fileLogger	struct	Log file	optional, default value: 20
rcEcatAcyclic	struct	ecat acyclic	optional, default value: 0

ThreadSettings Struct

Define basic thread settings like scheduling priority or CPU affinity of a specific thread.

Table 33 threadSettings struct

Parameter	Type	Description	Required/Optional
priority	unsigned int	Thread priority must be in range [0, 99]. But we highly recommend to be as low as possible and always be <= 49. 0: no realtime [1, 99]: realtime, implies the change of the scheduling policy to SCHED_FIFO	optional, default value: 0
cpuAffinity	int	Pin your thread to a certain CPU (starting from 0). -1 means no pinning to a specific CPU.	optional, default value: No affinity
isIsolated	bool	Treat this thread as isolated from other threads. All other threads will be prevented from running on the same CPU by disabling their CPU affinity on this CPU. Is activated by default when cpuAffinity is defined as a single CPU (int) and must be explicitly disabled if not wanted. This flag will be ignored when cpuAffinity is defined as a CPU mask (list of bools) or configured as default (-1).	optional, default value: false, except when cpuAffinity is defined as a single CPU (int)

Example for rt Setting Configuration File

The following code block exemplary shows a valid rtSettings.json file.

Listing 1 Example for rtSettings.json

{
  "IRQSettings": {
      "adjustIRQSettings": true,
      "priority": 84
  },
  "checkForRealtimeKernel": true,
  "lockMemory": true,
  "preventSleepStates": true,
  "threadSettings": {
      "crashlogger": {
          "cpuAffinity": -1,
          "priority": 0
      },
      "filewriter": {
          "cpuAffinity": -1,
          "priority": 21
      },
      "logDataToFile": {
          "cpuAffinity": -1,
          "priority": 21
      },
      "main": {
          "cpuAffinity": -1,
          "priority": 49
      },
      "motionplanner": {
          "cpuAffinity": -1,
          "priority": 39
      },
      "opcua": {
          "cpuAffinity": -1,
          "priority": 21
      },
      "sdo": {
          "cpuAffinity": -1,
          "priority": 47
      },
      "ibvEcatMonitor": {
          "cpuAffinity": -1,
          "priority": 0
      },
      "ibvEcatDiagnostics": {
          "cpuAffinity": -1,
          "priority": 0
      },
      "fileLogger": {
          "cpuAffinity": -1,
          "priority": 20
      },
      "rcEcatAcyclic": {
          "cpuAffinity": -1,
          "priority": 0
      }
  }
}

2.2.5. KUKA Configs

For the KUKA configuration a separate config file, kuka/config.json exists. In this the RSI connection and limitations for the T1 mode are defined. An example for the config file is given in Example for kuka/config.json.

Table 34 KUKA config

Parameter	Type	Description	Required/Optional
address	struct	RSI connection (IP address + port)	required
limitsT1	struct	T1 limits	required

Address

Configuration of the RSI connection

Table 35 KUKA address

Parameter	Type	Description	Required/Optional
serverIp	string	Server IP as string	required
port	unsigned short int	RSI port	required

Limits T1

The T1 limits will be used within a KukaT1Limits limit set which will be created at startup. voraus Robot Control automatically enables or disables the limit set based on the received kuka T1 mode. Further information about limits in voraus Robot Control can be found at Overview of the Configurable Limitations.

Table 36 KUKA limitsT1

Parameter	Type	Description	Required/Optional
axesVelocityLimits	double	General axes velocity limit (applied to all axes) in \([\mathrm{°}]\)	required
cartesianTranslationVelocity	double	Cartesian translational velocity limit \([\mathrm{m/s}]\)	required
cartesianRotationVelocity	double	Cartesian rotational velocity limit \([\mathrm{°/s}]\)	required

Example for KUKA Configuration File

Listing 2 Example for kuka/config.json

{
    "address": {
         "serverIp": "0.0.0.0",
         "port": 59152
    },
    "limitsT1": {
         "axesVelocityLimits" : 25.0,
         "cartesianTranslationVelocity" : 0.10,
         "cartesianRotationVelocity" : 20.0
    }
}

2.2.6. Compliant Behaviour Configs

compliantBehaviour is a configuration that is currently specific to the Yu Industrial robot and will be revised in the future to support a more general setup. Please be aware, that especial self collision and tool collision are still Yu Industrial-related. For the Yu Industrial robot, this configuration is also used for additional torque calculation for the gravitation compensation and the collision reaction.

Note

All compliantBehaviour configs are optional. Therefore, it is possible that the folder is empty or does not exist.

Compliant Behaviour Near Axis Limits

The compliantBehaviourNearAxisLimits is defined in the following table. An exemplary application is shown in the Example for compliantBehaviourNearAxisLimits.json.

Table 37 compliantBehaviourNearAxisLimits

Parameter	Type	Description	Required/Optional
ResistanceGains	Vector of doubles	Stiffness of the robot at the axes limits \([\mathrm{Nm/rad}]\)	required
AllowableAngleDistanceToLimits	Vector of doubles	Axes limits for the activation of the compliant behaviour in \([\mathrm{rad}]\)	required
IsEnabled	bool	Enables additional torque calculation in Handguiding/Collision-Reaction to avoid violation of axes limits	required

Listing 3 Example for compliantBehaviourNearAxisLimits.json

{
    "ResistanceGains" : [1000, 1000, 1000, 500, 200, 200],
    "AllowableAngleDistanceToLimits" : [0.087, 0.087, 0.087, 0.087, 0.122, 0.122],
    "IsEnabled" : true
}

Compliant Behaviour Near Self Collision

The compliantBehaviourNearSelfCollision is defined in the following table. An exemplary application is shown in the Example for compliantBehaviourNearSelfCollision.json.

Table 38 compliantBehaviourNearSelfCollision

Parameter	Type	Description	Required/Optional
IsEnabled	bool	Enables additional torque calculation in Handguiding/Collision-Reaction to avoid self collision	required
PairName	string	Unique name: must be implemented in source code	required
AllowablePairDistance	double	Allowed collision pair distance in \([\mathrm{m}]\)	required
ResistanceGain	double	Resistance gain to avoid self collision in \([\mathrm{N/m}]\)	required

Listing 4 Example for compliantBehaviourNearSelfCollision.json

    {
        "IsEnabled": true,
        "CompliantBehaviourNearSelfCollisionParameters": [
            {
                "PairName": "Base1Wrist8",
                "AllowablePairDistance": 0.1,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "Base1Hand10",
                "AllowablePairDistance": 0.1,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "Base1MediaFlange",
                "AllowablePairDistance": 0.08,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "Base1MediaFlange11",
                "AllowablePairDistance": 0.07,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "Base1MediaFlange12",
                "AllowablePairDistance": 0.07,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "Base2Wrist8",
                "AllowablePairDistance": 0.1,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "Base2Hand10",
                "AllowablePairDistance": 0.1,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "Base2MediaFlange",
                "AllowablePairDistance": 0.08,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "Base2MediaFlange11",
                "AllowablePairDistance": 0.07,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "Base2MediaFlange12",
                "AllowablePairDistance": 0.07,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "Wrist8MediaFlange11",
                "AllowablePairDistance": 0.13,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "Wrist8MediaFlange12",
                "AllowablePairDistance": 0.13,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "LowerArm7MediaFlange11",
                "AllowablePairDistance": 0.125,
                "ResistanceGain": 3000.0
            },
            {
                "PairName": "LowerArm7MediaFlange12",
                "AllowablePairDistance": 0.125,
                "ResistanceGain": 3000.0
            }
        ]
    }

Compliant Behaviour Near Tool Self Collision

The compliantBehaviourNearToolSelfCollision is defined in the following table. An exemplary application is shown in the Example for compliantBehaviourNearToolSelfCollision.json.

Table 39 compliantBehaviourNearToolSelfCollision

Parameter	Type	Description	Required/Optional
PairName	string	Unique name: must be implemented in source code	required
AllowablePairDistance	double	Allowed collision pair distance in \([\mathrm{m}]\)	required
ResistanceGain	double	Resistance gain to avoid self collision in \([\mathrm{N/m}]\)	required

Listing 5 Example for compliantBehaviourNearToolSelfCollision.json

    {
        "CompliantBehaviourNearSelfCollisionParameters": [
            {
                "PairName": "ToolBase1",
                "AllowablePairDistance": 0.07,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "ToolBase2",
                "AllowablePairDistance": 0.07,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "ToolShoulder3",
                "AllowablePairDistance": 0.07,
                "ResistanceGain": 2000.0
            },
            {
                "PairName": "ToolLowerArm7",
                "AllowablePairDistance": 0.07,
                "ResistanceGain": 2000.0
            }
        ]
    }

2.2.7. Yu Configs

This configuration are only for the YU Industrial robot and therefore optional. The JSON file is named partnumbers.json, and this config file can be used to overwrite the defined part numbers from the robot config file, see section Robot Configuration File for more information.

An example for the config file is given in Example for partnumbers.json.

Table 40 Robot Part Numbers

Parameter	Type	Description	Required/Optional
axes	Vector of strings	Part numbers for all axes	required
mediaflange	string	Part number of the media flange	required
msc	string	Part number of the main safety controller	required
robotVersion	string	Name of the used Yu Industrial robot, which must match the name from the robot config file	required

Example for Part Numbers Configuration File

Listing 6 Example for partnumbers.json

{
    "axes": [
        "123456",
        "234567",
        "345678",
        "456789",
        "567890",
        "678901",
    ],
    "mediaflange": "789012",
    "msc": "890123",
    "robotVersion": "Yu5Industrial1.3"
}

2.2.8. Port Connections Config

The port connections config file contains settings for the different port connections. It is only required if an external robot driver is used as a robot communication interface instead of the integrated fieldbus drivers. This is currently enabled by setting the environment variable VRC_USE_ROBOT_DRIVER to true. See the section Overview of the Environment Variables for more details.

The port connections config file must be located at ${VORAUS_CONFIG_DIR}/port_connections.json and contains settings defined in the following table.

Table 41 Port Connections Configuration File

Parameter	Type	Description	Required/Optional
robot_driver_port	RobotDriverPortConfig struct	Contains all configuration parameters related to the robot driver port connection.	required

Robot Driver Port Config

The RobotDriverPortConfig struct contains all configuration parameters related to the robot driver port connection, as defined in the following table.

Table 42 Robot Driver Port Configuration

Parameter	Type	Description	Required/Optional
portNames	struct	The names of the robot driver ports. See Table RobotDriverPortConfig.PortNames for details.	optional, default value: Same as default port names defined in RobotDriverPortConfig.PortNames.
realtimeCommunication	bool	If false, timeouts in the communication will not lead an error, instead indefinitely wait for the next notification of the robot driver.	optional, default value: true
timingKDriver	double	Configured overbooking factor of the robot driver.	optional, default value: 0.1
timingTDriver PreNominalMicroseconds	integer	Nominal time in \(\mathrm{µs}\) between the start of the cycle and the robot driver notifying the motion.	optional, default value: \(\mathrm{500 µs}\)
missedEventLimit	integer	Number of consecutive notification timeouts until the port is considered disconnected and the motion has to enter a non-operational state.	optional, default value: 3
portConnection TimeoutSeconds	integer	Timeout in \(\mathrm{s}\) for connecting to the port during initialization.	optional, default value: \(\mathrm{30 s}\)
handshakeTimeoutSeconds	integer	Timeout in \(\mathrm{s}\) for the handshake protocol.	optional, default value: \(\mathrm{10 s}\)

RobotDriverPortConfig.PortNames

The PortNames struct contains the names of the robot driver ports, as defined in the following table.

Table 43 RobotDriverPortConfig.PortNames

Parameter	Type	Description	Required/Optional
cyclicDataPortName	string	The name of the cyclic data port	optional, default value: "robot_driver/cyclic"
statusPortName	string	The name of the status port	optional, default value: "robot_driver/status"
commandPortName	string	The name of the command port	optional, default value: "robot_driver/command"
managementPortName	string	The name of the management port	optional, default value: "robot_driver/management"