KUKA Ethernet KRL Interface

The rc_reason_stack provides an Ethernet KRL Interface (EKI Bridge), which allows communicating with the rc_reason_stack from KUKA KRL via KUKA.EthernetKRL XML.

Note

The component is optional and requires a separate Roboception’s EKIBridge license to be purchased.

Note

The KUKA.EthernetKRL add-on software package version 2.2 up to version 5.x must be activated on the robot controller to use this component.

The EKI Bridge can be used to programmatically to

• do service calls, e.g. to start and stop individual computational nodes, or to use offered services such as the hand-eye calibration or the computation of grasp poses;
• set and get run-time parameters of computation nodes, e.g. of the camera, or disparity calculation.

Note

A known limitation of the EKI Bridge is that strings representing valid numbers will be converted to int/float. Hence user-defined names (like ROI IDs, etc.) should always contain at least one letter so they can be used in service call arguments.

Ethernet connection configuration

The EKI Bridge listens on port 7000 for EKI XML messages and transparently bridges the rc_reason_stack’s REST-API v2. The received EKI messages are transformed to JSON and forwarded to the rc_reason_stack’s REST-API. The response from the REST-API is transformed back to EKI XML.

The EKI Bridge gives access to run-time parameters and offered services of all computational nodes described in Software modules.

The Ethernet connection to the rc_reason_stack on the robot controller is configured using XML configuration files. The EKI XML configuration files of all nodes running on the rc_reason_stack are listed at EKI XML configuration files.

Each node offering run-time parameters has an XML configuration file for setting and getting its parameters. These are named following the scheme <node_name>-parameters.xml. Each node’s service has its own XML configuration file. These are named following the scheme <node_name>-<service_name>.xml.

The IP of the host PC running the rc_reason_stack needs to be filled into the XML file.

The port is already set to 7000, which corresponds to pipeline 0. This needs to be adjusted if a different pipeline should be used. The port number is 7000 + pipeline number, so 7001 for pipeline 1, etc.

These files must be stored in the directory C:\KRC\ROBOTER\Config\User\Common\EthernetKRL of the robot controller and they are read in when a connection is initialized.

As an example, an Ethernet connection to configure the rc_stereomatching parameters is established with the following KRL code.

DECL EKI_Status RET
RET = EKI_INIT("rc_stereomatching-parameters")
RET = EKI_Open("rc_stereomatching-parameters")

; ----------- Desired operation -----------

RET = EKI_Close("rc_stereomatching-parameters")

Note

The EKI Bridge automatically terminates the connection to the client if the received XML telegram is invalid.

Generic XML structure

For data transmission, the EKI Bridge uses <req> as root XML element (short for request).

The root tag always includes the following elements.

• <node>. This includes a child XML element used by the EKI Bridge to identify the target node. The node name is already included in the XML configuration file.
• <end_of_request>. End of request flag that triggers the request.

The following listing shows the generic XML structure for data transmission.

<SEND>
  <XML>
    <ELEMENT Tag="req/node/<node_name>" Type="STRING"/>
    <ELEMENT Tag="req/end_of_request" Type="BOOL"/>
  </XML>
</SEND>

For data reception, the EKI Bridge uses <res> as root XML element (short for response). The root tag always includes a <return_code> child element.

<RECEIVE>
  <XML>
    <ELEMENT Tag="res/return_code/@value" Type="INT"/>
    <ELEMENT Tag="res/return_code/@message" Type="STRING"/>
    <ELEMENT Tag="res" Set_Flag="998"/>
  </XML>
</RECEIVE>

Note

By default the XML configuration files uses 998 as flag to notify KRL that the response data record has been received. If this value is already in use, it should be changed in the corresponding XML configuration file.

Return code

The <return_code> element consists of a value and a message attribute.

As for all other components, a successful request returns with a res/return_code/@value of 0. Negative values indicate that the request failed. The error message is contained in res/return_code/@message. Positive values indicate that the request succeeded with additional information, contained in res/return_code/@message as well.

The following codes can be issued by the EKI Bridge component.

Table 74 Return codes of the EKI Bridge component

Code	Description
0	Success
-1	Parsing error in the conversion from XML to JSON
-2	Internal error
-5	Connection error from the REST-API
-9	Missing or invalid license for EKI Bridge component

Note

The EKI Bridge can also return return code values specific to individual nodes. They are documented in the respective software module.

Note

Due to limitations in KRL, the maximum length of a string returned by the EKI Bridge is 512 characters. All messages larger than this value are truncated.

Services

For the nodes’ services, the XML schema is generated from the service’s arguments and response in JavaScript Object Notation (JSON) described in Software modules. The conversion is done transparently, except for the conversion rules described below.

Conversions of poses:

A pose is a JSON object that includes position and orientation keys.

{
  "pose": {
    "position": {
      "x": "float64",
      "y": "float64",
      "z": "float64",
    },
    "orientation": {
      "x": "float64",
      "y": "float64",
      "z": "float64",
      "w": "float64",
    }
  }
}

This JSON object is converted to a KRL FRAME in the XML message.

<pose X="..." Y="..." Z="..." A="..." B="..." C="..."></pose>

Positions are converted from meters to millimeters and orientations are converted from quaternions to KUKA ABC (in degrees).

Note

No other unit conversions are included in the EKI Bridge. All dimensions and 3D coordinates that don’t belong to a pose are expected and returned in meters.

Arrays:

Arrays are identified by adding the child element <le> (short for list element) to the list name. As an example, the JSON object

{
  "rectangles": [
    {
      "x": "float64",
      "y": "float64"
    }
  ]
}

is converted to the XML fragment

<rectangles>
  <le>
    <x>...</x>
    <y>...</y>
  </le>
</rectangles>

Use of XML attributes:

All JSON keys whose values are a primitive data type and don’t belong to an array are stored in attributes. As an example, the JSON object

{
  "item": {
    "uuid": "string",
    "confidence": "float64",
    "rectangle": {
      "x": "float64",
      "y": "float64"
    }
  }
}

is converted to the XML fragment

<item uuid="..." confidence="...">
  <rectangle x="..." y="...">
  </rectangle>
</item>

Request XML structure

The <SEND> element in the XML configuration file for a generic service follows the specification below.

<SEND>
  <XML>
    <ELEMENT Tag="req/node/<node_name>" Type="STRING"/>
    <ELEMENT Tag="req/service/<service_name>" Type="STRING"/>
    <ELEMENT Tag="req/args/<argX>" Type="<argX_type>"/>
    <ELEMENT Tag="req/end_of_request" Type="BOOL"/>
  </XML>
</SEND>

The <service> element includes a child XML element that is used by the EKI Bridge to identify the target service from the XML telegram. The service name is already included in the configuration file.

The <args> element includes the service arguments and should be configured with EKI_Set<Type> KRL instructions.

As an example, the <SEND> element of the rc_load_carrier_db’s get_load_carriers service (see LoadCarrierDB) is:

<SEND>
  <XML>
    <ELEMENT Tag="req/node/rc_load_carrier_db" Type="STRING"/>
    <ELEMENT Tag="req/service/get_load_carriers" Type="STRING"/>
    <ELEMENT Tag="req/args/load_carrier_ids/le" Type="STRING"/>
    <ELEMENT Tag="req/end_of_request" Type="BOOL"/>
  </XML>
</SEND>

The <end_of_request> element allows to have arrays in the request. For configuring an array, the request is split into as many packages as the size of the array. The last telegram contains all tags, including the <end_of_request> flag, while all other telegrams contain one array element each.

As an example, for requesting two load carrier models to the rc_load_carrier_db’s get_load_carriers service, the user needs to send two XML messages. The first XML telegram is:

<req>
  <args>
    <load_carrier_ids>
      <le>load_carrier1</le>
    </load_carrier_ids>
  </args>
</req>

This telegram can be sent from KRL with the EKI_Send command, by specifying the list element as path:

DECL EKI_STATUS RET
RET = EKI_SetString("rc_load_carrier_db-get_load_carriers", "req/args/load_carrier_ids/le", "load_carrier1")
RET = EKI_Send("rc_load_carrier_db-get_load_carriers", "req/args/load_carrier_ids/le")

The second telegram includes all tags and triggers the request to the rc_load_carrier_db node:

<req>
  <node>
    <rc_load_carrier_db></rc_load_carrier_db>
  </node>
  <service>
    <get_load_carriers></get_load_carriers>
  </service>
  <args>
    <load_carrier_ids>
      <le>load_carrier2</le>
    </load_carrier_ids>
  </args>
  <end_of_request></end_of_request>
</req>

This telegram can be sent from KRL by specifying req as path for EKI_Send:

DECL EKI_STATUS RET
RET = EKI_SetString("rc_load_carrier_db-get_load_carriers", "req/args/load_carrier_ids/le", "load_carrier2")
RET = EKI_Send("rc_load_carrier_db-get_load_carriers", "req")

Response XML structure

The <RECEIVE> element in the XML configuration file for a generic service follows the specification below:

<RECEIVE>
  <XML>
    <ELEMENT Tag="res/<resX>" Type="<resX_type>"/>
    <ELEMENT Tag="res/return_code/@value" Type="INT"/>
    <ELEMENT Tag="res/return_code/@message" Type="STRING"/>
    <ELEMENT Tag="res" Set_Flag="998"/>
  </XML>
</RECEIVE>

As an example, the <RECEIVE> element of the rc_april_tag_detect’s detect service (see TagDetect) is:

<RECEIVE>
  <XML>
    <ELEMENT Tag="res/timestamp/@sec" Type="INT"/>
    <ELEMENT Tag="res/timestamp/@nsec" Type="INT"/>
    <ELEMENT Tag="res/return_code/@message" Type="STRING"/>
    <ELEMENT Tag="res/return_code/@value" Type="INT"/>
    <ELEMENT Tag="res/tags/le/pose_frame" Type="STRING"/>
    <ELEMENT Tag="res/tags/le/timestamp/@sec" Type="INT"/>
    <ELEMENT Tag="res/tags/le/timestamp/@nsec" Type="INT"/>
    <ELEMENT Tag="res/tags/le/pose/@X" Type="REAL"/>
    <ELEMENT Tag="res/tags/le/pose/@Y" Type="REAL"/>
    <ELEMENT Tag="res/tags/le/pose/@Z" Type="REAL"/>
    <ELEMENT Tag="res/tags/le/pose/@A" Type="REAL"/>
    <ELEMENT Tag="res/tags/le/pose/@B" Type="REAL"/>
    <ELEMENT Tag="res/tags/le/pose/@C" Type="REAL"/>
    <ELEMENT Tag="res/tags/le/instance_id" Type="STRING"/>
    <ELEMENT Tag="res/tags/le/id" Type="STRING"/>
    <ELEMENT Tag="res/tags/le/size" Type="REAL"/>
    <ELEMENT Tag="res" Set_Flag="998"/>
  </XML>
</RECEIVE>

For arrays, the response includes multiple instances of the same XML element. Each element is written into a separate buffer within EKI and can be read from the buffer with KRL instructions. The number of instances can be requested with EKI_CheckBuffer and each instance can then be read by calling EKI_Get<Type>.

As an example, the tag poses received after a call to the rc_april_tag_detect’s detect service can be read in KRL using the following code:

DECL EKI_STATUS RET
DECL INT i
DECL INT num_instances
DECL FRAME poses[32]

DECL FRAME pose = {X 0.0, Y 0.0, Z 0.0, A 0.0, B 0.0, C 0.0}

RET = EKI_CheckBuffer("rc_april_tag_detect-detect", "res/tags/le/pose")
num_instances = RET.Buff
for i=1 to num_instances
  RET = EKI_GetFrame("rc_april_tag_detect-detect", "res/tags/le/pose", pose)
  poses[i] = pose
endfor
RET = EKI_ClearBuffer("rc_april_tag_detect-detect", "res")

Note

Before each request from EKI to the rc_reason_stack, all buffers should be cleared in order to store only the current response in the EKI buffers.

Memory limits and array trimming

When returning large arrays, KUKA EKI enforces two main memory limits:

• BUFFERING limit (queue depth): The maximum number of elements that are stored in a single array bucket. A single response often contains multiple independent lists (e.g., res/grasps/le/... and res/matches/le/...), which are stored in entirely separate buckets inside the robot controller. No single bucket may exceed the configured BUFFERING limit, otherwise the connection drops.
• BUFFSIZE limit (message size): The maximum total byte size of a single XML telegram on the network. The absolute KUKA maximum is 65534 bytes (~64 kB).

Independent lists within the same response (e.g. grasps and matches) are conceptually different and naturally have different lengths. Furthermore, if a payload exceeds the 64kB BUFFSIZE limit, the EKI Bridge will automatically delete elements from the end of the response to fit it on the network. This means the bridge might truncate items from one list while leaving another untouched.

Note

All child elements of a list element (after le/*) belong to the same array of a REST-API response and are guaranteed to have the same lengths even after pruning.

Always use EKI_CheckBuffer on the specific array you are about to read to get its true length. Do not assume its length matches that of a different array.

Parameters

All nodes’ parameters can be set and queried from the EKI Bridge. The XML configuration file for a generic node follows the specification below:

<SEND>
  <XML>
    <ELEMENT Tag="req/node/<node_name>" Type="STRING"/>
    <ELEMENT Tag="req/parameters/<parameter_x>/@value" Type="INT"/>
    <ELEMENT Tag="req/parameters/<parameter_y>/@value" Type="STRING"/>
    <ELEMENT Tag="req/end_of_request" Type="BOOL"/>
  </XML>
</SEND>
<RECEIVE>
  <XML>
    <ELEMENT Tag="res/parameters/<parameter_x>/@value" Type="INT"/>
    <ELEMENT Tag="res/parameters/<parameter_x>/@default" Type="INT"/>
    <ELEMENT Tag="res/parameters/<parameter_x>/@min" Type="INT"/>
    <ELEMENT Tag="res/parameters/<parameter_x>/@max" Type="INT"/>
    <ELEMENT Tag="res/parameters/<parameter_y>/@value" Type="REAL"/>
    <ELEMENT Tag="res/parameters/<parameter_y>/@default" Type="REAL"/>
    <ELEMENT Tag="res/parameters/<parameter_y>/@min" Type="REAL"/>
    <ELEMENT Tag="res/parameters/<parameter_y>/@max" Type="REAL"/>
    <ELEMENT Tag="res/return_code/@value" Type="INT"/>
    <ELEMENT Tag="res/return_code/@message" Type="STRING"/>
    <ELEMENT Tag="res" Set_Flag="998"/>
  </XML>
</RECEIVE>

The request is interpreted as a get request if all parameter’s value attributes are empty. If any value attribute is non-empty, it is interpreted as set request of the non-empty parameters.

As an example, the current value of all parameters of rc_stereomatching can be queried using the XML telegram:

<req>
  <node>
    <rc_stereomatching></rc_stereomatching>
  </node>
  <parameters></parameters>
  <end_of_request></end_of_request>
</req>

This XML telegram can be sent out with Ethernet KRL using:

DECL EKI_STATUS RET
RET = EKI_Send("rc_stereomatching-parameters", "req")

The response from the EKI Bridge contains all parameters:

<res>
  <parameters>
    <acquisition_mode default="Continuous" max="" min="" value="Continuous"/>
    <quality default="High" max="" min="" value="High"/>
    <static_scene default="0" max="1" min="0" value="0"/>
    <seg default="200" max="4000" min="0" value="200"/>
    <smooth default="1" max="1" min="0" value="1"/>
    <fill default="3" max="4" min="0" value="3"/>
    <minconf default="0.5" max="1.0" min="0.5" value="0.5"/>
    <mindepth default="0.1" max="100.0" min="0.1" value="0.1"/>
    <maxdepth default="100.0" max="100.0" min="0.1" value="100.0"/>
    <maxdeptherr default="100.0" max="100.0" min="0.01" value="100.0"/>
  </parameters>
  <return_code message="" value="0"/>
</res>

The quality parameter of rc_stereomatching can be set to Low by the XML telegram:

<req>
    <node>
      <rc_stereomatching></rc_stereomatching>
    </node>
    <parameters>
      <quality value="Low"></quality>
    </parameters>
    <end_of_request></end_of_request>
</req>

This XML telegram can be sent out with Ethernet KRL using:

DECL EKI_STATUS RET
RET = EKI_SetString("rc_stereomatching-parameters", "req/parameters/quality/@value", "Low")
RET = EKI_Send("rc_stereomatching-parameters", "req")

In this case, only the applied value of quality is returned by the EKI Bridge:

<res>
  <parameters>
    <quality default="High" max="" min="" value="Low"/>
  </parameters>
  <return_code message="" value="0"/>
</res>

EKI XML configuration files

This section contains EKI XML configuration files for all nodes running on the rc_reason_stack. They are also available for download in this ZIP archive.

rc_april_tag_detect

• Parameters

• Services:

  • detect
  • reset_defaults
  • restart
  • start
  • stop
  • trigger_dump

rc_boxpick

• Parameters

• Services:

  • compute_grasps
  • compute_grasps_extended
  • detect_items
  • get_preferred_orientation
  • get_sorting_strategies
  • reset_defaults
  • set_preferred_orientation
  • set_sorting_strategies
  • set_view_name
  • start
  • stop
  • trigger_dump

rc_cadmatch

• Parameters

• Services:

  • delete_grasps
  • delete_pose_priors
  • detect_object
  • detect_object_extended
  • get_grasps
  • get_overlap_check_direction
  • get_pose_priors
  • get_preferred_orientation
  • get_sorting_strategies
  • get_symmetric_grasps
  • reset_defaults
  • set_all_grasps
  • set_all_pose_priors
  • set_grasp
  • set_overlap_check_direction
  • set_pose_prior
  • set_preferred_orientation
  • set_sorting_strategies
  • start
  • stop
  • trigger_dump
  • warmup_template

rc_camera

• Parameters

• Services:

  • acquisition_trigger
  • reset_defaults

rc_collision_check

• Parameters

• Services:

  • check_collisions
  • reset_defaults

rc_gripper_db

• Services:

  • delete_grippers
  • get_grippers
  • get_grippers_schmalz_vac
  • get_grippers_schunk
  • set_gripper
  • set_gripper_schmalz_vac
  • set_gripper_schunk
  • set_stroke_schunk

rc_hand_eye_calibration

• Parameters

• Services:

  • calibrate
  • delete_poses
  • estimate_robot_pose
  • get_calibration
  • get_poses
  • remove_calibration
  • reset_calibration
  • reset_defaults
  • save_calibration
  • set_calibration
  • set_pose

rc_iocontrol

• Parameters

• Services:

  • get_io_values
  • reset_defaults

rc_itempick

• Parameters

• Services:

  • compute_grasps
  • compute_grasps_extended
  • get_preferred_orientation
  • get_sorting_strategies
  • reset_defaults
  • set_preferred_orientation
  • set_sorting_strategies
  • start
  • stop
  • trigger_dump

rc_load_carrier

• Parameters

• Services:

  • detect_filling_level
  • detect_load_carriers
  • reset_defaults
  • trigger_dump

rc_load_carrier_db

• Services:

  • delete_load_carriers
  • get_load_carriers
  • set_load_carrier

rc_measure

• Services:

  • measure_depth
  • trigger_dump

rc_qr_code_detect

• Parameters

• Services:

  • detect
  • reset_defaults
  • restart
  • start
  • stop
  • trigger_dump

rc_roi_db

• Services:

  • delete_regions_of_interest
  • delete_regions_of_interest_2d
  • get_regions_of_interest
  • get_regions_of_interest_2d
  • set_region_of_interest
  • set_region_of_interest_2d

rc_silhouettematch

• Parameters

• Services:

  • calibrate_base_plane
  • delete_base_plane_calibration
  • delete_grasps
  • detect_object
  • detect_object_extended
  • get_base_plane_calibration
  • get_grasps
  • get_preferred_orientation
  • get_sorting_strategies
  • get_symmetric_grasps
  • reset_defaults
  • set_all_grasps
  • set_grasp
  • set_preferred_orientation
  • set_sorting_strategies
  • trigger_dump

rc_stereocalib

• Parameters

• Services:

  • change_state
  • reset_defaults

rc_stereomatching

• Parameters

• Services:

  • acquisition_trigger
  • reset_defaults

Example applications

More detailed robot application examples can be found at https://github.com/roboception/eki_examples.

Troubleshooting

SmartPad error message: Limit of element memory reached

This error occurs when the number of received elements in any array exceeds the configured BUFFERING limit in the EKI XML configuration file. The connection drops before the KRL program can read the data.

• Increase the BUFFERING limit in the EKI XML configuration file on the robot controller to match the maximum number of expected elements.
• Decrease the Maximum Matches (or similar) parameter in the rc_reason_stack detection module to ensure it returns fewer items.

The total memory available for storing EKI values on the robot is limited by default to 1MB across all connections. If you increase the limits too much or have too many parallel arrays, the robot may fail to initialize the connection. Please refer to the official KUKA documentation (KST_EthernetKRL) to increase this system memory pool.

SmartPad error message: Reading from empty buffer

This error occurs when the KRL program attempts to read an array element that was never received.

• Payload trimming: The EKI Bridge might have trimmed elements from the end of the response to fit within the 64kB BUFFSIZE limit, causing independent arrays to have different lengths (see Memory limits and array trimming). Check the EKI Bridge logs for warnings like “Trimmed XML tree” or “Pruned response items”.
• Mismatched loop counts: The KRL program loops further than the actual received elements. Ensure you are using EKI_CheckBuffer on the specific array you are reading.
• KRL array size: Ensure that the arrays defined in your KRL .dat and .src files are large enough to hold all incoming data.