# KUKA (Pro)

The **KUKA Interface** component provides TCP/IP communication with KUKA OfficeLite virtual controllers using the Y200 protocol through the OpenCommissioning OC\_Assistant\_OfficeLite server. This integration enables real-time exchange of robot axis values and digital I/O signals between Unity and KUKA virtual controllers for digital twin applications and virtual commissioning.

> **Big thanks to OpenCommissioning** for making the OC\_Assistant\_OfficeLite code available at <https://github.com/OpenCommissioning/OC_Assistant_OfficeLite>, enabling seamless KUKA robot integration with realvirtual.

**Important**: This interface is designed specifically for KUKA OfficeLite virtual controllers and requires the OC\_Assistant\_OfficeLite server to function.

> **Beta Notice**: This KUKA interface is currently in beta. If you experience any problems or need assistance, please feel free to get in direct contact with us for support.

## Overview

The KUKA interface implements the Y200 communication protocol specifically for KUKA OfficeLite virtual controllers, providing bidirectional data exchange over TCP/IP through the OC\_Assistant\_OfficeLite server. This interface enables creating digital twins of KUKA robot systems using virtual controllers, allowing for cost-effective simulation and virtual commissioning without requiring physical robot hardware.

Key capabilities include:

* Real-time robot axis position monitoring (6 axes)
* Digital I/O signal exchange (up to 8192 inputs/outputs)
* Automatic connection management with reconnection support
* Thread-safe communication for reliable data exchange
* Signal creation utilities for quick setup

The interface communicates using the KUKA Y200 Server protocol on port 54600 (default), exchanging 1144 bytes from the controller (outputs and axis data) and 1024 bytes to the controller (inputs). For virtual commissioning scenarios, the interface can connect to KUKA OfficeLite controllers running the OC\_Assistant\_OfficeLite Y200 server.

![KUKA Interface Inspector](https://260262196-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpYxFg97YnJX96UzNNTSd%2Fuploads%2Fgit-blob-eb97b8417e487fcee86b64b11b6c841d4f1a6a67%2Fkuka-interface-inspector.png?alt=media)

The KUKA interface provides comprehensive configuration options through the Unity Inspector, including connection settings, signal configuration, real-time axis monitoring, and status information.

## Properties

### Connection Settings

**Server IP** (string) specifies the IP address of the KUKA Y200 server. Default value is 127.0.0.1 for local connections with KUKA OfficeLite virtual controllers. For real robot controllers or external simulations, enter the controller's IP address on your network. When using OfficeLite with the OC\_Assistant\_OfficeLite server, this typically remains 127.0.0.1 for local development.

**Server Port** (integer) defines the TCP port for Y200 communication. The standard KUKA Y200 port is 54600. This rarely needs to be changed unless your controller is configured for a different port.

**Connection Timeout Ms** (integer) sets the maximum time in milliseconds to wait for a connection before failing. Default is 5000ms (5 seconds). Increase this value for connections over slower networks or when connecting to busy controllers.

### Signal Configuration

**Max Digital Signals** (integer) determines how many digital I/O signals to create and manage. The value can range from 1 to 8192 to match KUKA's $IN and $OUT arrays. Default is 100 for performance optimization. Only create the number of signals you actually need, as processing thousands of unused signals impacts performance.

### Status (Read-Only)

**Current Axis Values** (float array) displays real-time robot axis positions in degrees for axes 1-6. These values are continuously updated from the KUKA controller and can be used to drive robot visualization or monitor robot state.

**Active Inputs** (integer) shows the count of active input signals (InBool) currently configured and being monitored. This helps verify that signals are properly created and recognized.

**Active Outputs** (integer) indicates the number of active output signals (OutBool) currently configured and being monitored. Use this to confirm output signal configuration.

### State

**State** displays the current connection status (Disconnected, Connecting, Connected, or Error). Monitor this to ensure proper communication with the KUKA controller.

**Input Signals** shows the total number of input signals detected in the interface hierarchy.

**Output Signals** displays the total number of output signals found in the interface hierarchy.

**Comm Cycle Ms** indicates the communication cycle time in milliseconds, showing how frequently data is exchanged with the controller.

**Cycle Count** tracks the total number of successful communication cycles since connection was established.

### Configuration

**Update Cycle Ms** (integer) sets the communication update interval in milliseconds. Default is 10ms for smooth real-time updates. Increase this value to reduce network traffic or CPU usage.

**Only Transmit Changed Inputs** (boolean) when enabled, optimizes communication by only sending input values that have changed since the last cycle. This reduces processing overhead for systems with many signals.

**Auto Reconnect** (boolean) enables automatic reconnection attempts when the connection is lost. Recommended for production systems to maintain connectivity.

**Reconnect Interval Seconds** (integer) defines how long to wait between reconnection attempts. Default is 10 seconds to avoid overwhelming the controller with connection requests.

**Max Reconnect Attempts** (integer) limits the number of reconnection attempts before giving up. Set to -1 for unlimited attempts.

**Debug Mode** (boolean) enables detailed logging of communication activities for troubleshooting connection issues or protocol problems.

## Signal Naming Convention

The KUKA interface uses specific signal naming patterns that map to KUKA system variables:

### Robot Axes

* **Axis1** to **Axis6**: PLCOutputFloat signals representing robot joint positions in degrees
* These map directly to the robot's current axis positions

### Digital Inputs

* **InBool0** to **InBool8191**: PLCInputBool signals
* InBool0 maps to KUKA $IN\[1]
* InBool8191 maps to KUKA $IN\[8192]
* Note the offset: Unity uses 0-based indexing while KUKA uses 1-based

### Digital Outputs

* **OutBool0** to **OutBool8191**: PLCOutputBool signals
* OutBool0 maps to KUKA $OUT\[1]
* OutBool8191 maps to KUKA $OUT\[8192]
* Same offset applies as with inputs

## Usage

### Basic Setup

1. **Add the KUKA Interface component** to an empty GameObject in your scene
2. **Configure the connection** by setting the Server IP to your KUKA controller's address:
   * For OfficeLite virtual controllers: Use 127.0.0.1 (localhost)
   * For real controllers: Use the controller's network IP address
3. **Click "Create Standard Signals"** button to automatically generate the signal structure
4. **Enable the interface** by checking the Active checkbox
5. **Monitor the State** property to confirm successful connection

### Signal Structure

When you click "Create Standard Signals", the interface automatically creates a organized hierarchy:

```
KukaInterface
├── Axes
│   ├── Axis1 (PLCOutputFloat)
│   ├── Axis2 (PLCOutputFloat)
│   ├── Axis3 (PLCOutputFloat)
│   ├── Axis4 (PLCOutputFloat)
│   ├── Axis5 (PLCOutputFloat)
│   └── Axis6 (PLCOutputFloat)
├── Inputs
│   ├── InBool0 (PLCInputBool)
│   ├── InBool1 (PLCInputBool)
│   └── ... (up to MaxDigitalSignals)
└── Outputs
    ├── OutBool0 (PLCOutputBool)
    ├── OutBool1 (PLCOutputBool)
    └── ... (up to MaxDigitalSignals)
```

### Connecting to Robot Drives

To visualize robot movement in Unity:

1. Create or import your KUKA robot model in Unity
2. Add Drive components to each robot joint
3. **Enable Follow Position**: Set the Drive's **Follow Position** property to true so the drive follows external position commands
4. Connect the axis signals to your drives:
   * Select each Drive component
   * In the PLC Output Float field, drag the corresponding Axis signal (e.g., Axis1 for joint 1)
   * The drive will now follow the real robot's position in real-time

### Working with Digital I/O

Digital signals can be used for:

* **Safety interlocks**: Monitor safety gates, emergency stops
* **Process control**: Trigger grippers, tools, or other equipment
* **Status indication**: Show robot state, program status, error conditions

Example: Controlling a gripper through KUKA I/O:

1. In your KRL program, set $OUT\[10] to control the gripper
2. In Unity, OutBool9 (remember the offset) will reflect this state
3. Connect OutBool9 to your gripper component's activation signal

### Performance Optimization

For systems with many signals:

1. **Set Max Digital Signals** to only what you need (not the maximum 8192)
2. **Enable "Only Transmit Changed Inputs"** to reduce network traffic
3. **Increase Update Cycle Ms** if real-time response isn't critical
4. **Use the signal cache** by avoiding dynamic signal creation during runtime

### Network Configuration

Ensure proper network setup:

1. **Firewall rules**: Allow TCP port 54600 (or your configured port)
2. **Network isolation**: Keep robot networks separate from general IT networks
3. **Latency**: For best performance, keep Unity and KUKA controller on the same subnet
4. **Y200 Server**: Ensure the Y200 server is running:
   * For real controllers: Y200 server must be installed and running
   * For OfficeLite: Install and run the OC\_Assistant\_OfficeLite server

### KUKA OfficeLite Integration

For virtual commissioning without real hardware, you can use KUKA OfficeLite with the OpenCommissioning OC\_Assistant\_OfficeLite server:

#### Installing OfficeLite Server

1. **Download KUKA OfficeLite** from the KUKA website (requires KUKA account)
2. **Install OfficeLite** following KUKA's installation guide
3. **Get OC\_Assistant\_OfficeLite**:
   * Clone from GitHub: `git clone https://github.com/OpenCommissioning/OC_Assistant_OfficeLite.git`
   * Or download the latest release from the repository
4. **Install the Y200 server component**:
   * Navigate to the OC\_Assistant\_OfficeLite project folder
   * Follow the installation instructions in the project README
   * The server provides the Y200 protocol interface for OfficeLite

#### Configuring OfficeLite with realvirtual

1. **Start KUKA OfficeLite** with your robot project
2. **Launch OC\_Assistant\_OfficeLite**:
   * Run the server application
   * Verify it connects to your OfficeLite instance
   * Confirm the Y200 server is listening on port 54600
3. **Configure realvirtual KUKA interface**:
   * Set Server IP to 127.0.0.1 (localhost)
   * Keep default port 54600
   * Enable the interface
4. **Verify connection** by checking the State property shows "Connected"

#### Benefits of OfficeLite Integration

* **No hardware required**: Test and develop without physical robot controllers
* **Full KRL support**: Run actual robot programs in virtual environment
* **Safe testing**: Validate programs and sequences without safety risks
* **Cost-effective**: Develop and commission virtually before hardware arrives
* **Multi-robot support**: Run multiple virtual controllers simultaneously
* **Debugging capabilities**: Enhanced debugging compared to real controllers

### Troubleshooting

Common issues and solutions:

**Connection fails immediately**

* Verify the KUKA controller IP address is correct (127.0.0.1 for OfficeLite)
* Check that Y200 server is running:
  * For real controllers: Verify Y200 server installation
  * For OfficeLite: Ensure OC\_Assistant\_OfficeLite is running
* Ensure port 54600 is not blocked by firewalls
* Test network connectivity with ping command
* For OfficeLite: Verify the virtual controller is started and in RUN mode

**No axis values updating**

* Confirm the robot program is running on the controller
* Check that the Y200 server is configured to send axis data
* Verify signal names match exactly (Axis1, not Axis\_1)

**Digital I/O not working**

* Remember the indexing offset (InBool0 = $IN\[1])
* Ensure signals are created with correct names
* Check that I/O is not being overridden by KRL program
* Verify MaxDigitalSignals covers the I/O range you need

**Connection drops frequently**

* Check network stability and cable connections
* Increase Connection Timeout Ms for unreliable networks
* Enable Auto Reconnect for automatic recovery
* Review controller logs for Y200 server errors

## Protocol Details

The Y200 protocol exchanges fixed-size data packets:

**From KUKA Controller (1144 bytes)**:

* Bytes 0-1023: Digital outputs ($OUT array)
* Bytes 1024-1071: Robot axes (6 × 8-byte doubles)
* Bytes 1072-1143: Position/tool/base data (not currently used)

**To KUKA Controller (1024 bytes)**:

* Bytes 0-1023: Digital inputs ($IN array)

This fixed structure ensures predictable, real-time communication suitable for industrial applications.

## Integration with realvirtual Components

The KUKA interface works seamlessly with other realvirtual components:

### Robot Components

* **Drive**: Connect axis signals to drive components for robot visualization
* **Robot**: Use with the Robot component for complete kinematic simulation
* **IK (Inverse Kinematics)**: Combine with IK for path planning and validation

### Signal Processing

* **SignalManager**: Centrally manage all KUKA signals
* **PLCInputFloat/PLCOutputFloat**: Extend for analog value exchange
* **ValueMapping**: Transform signal values for different scaling needs

### Automation Logic

* **BehaviorGraph**: Create visual logic using KUKA I/O signals
* **Scripts**: Access signals programmatically for custom behaviors
* **Sequences**: Build complex automation sequences with robot coordination

## Best Practices

1. **Signal Organization**: Keep the auto-generated folder structure for clarity
2. **Naming Convention**: Follow the standard naming (Axis1-6, InBool, OutBool) for compatibility
3. **Performance**: Only create signals you actually use to minimize overhead
4. **Error Handling**: Implement proper error handling in automation logic for connection failures
5. **Documentation**: Document signal mappings between Unity and KRL programs
6. **Testing**: Test with simulated controllers before connecting to real robots:
   * Use KUKA OfficeLite with OC\_Assistant\_OfficeLite for comprehensive testing
   * Validate with KUKA WorkVisual simulation
   * Verify all signals and axes before deploying to real hardware
7. **Safety**: Never rely solely on simulation for safety-critical decisions

## External Resources

* [OpenCommissioning OC\_Assistant\_OfficeLite](https://github.com/OpenCommissioning/OC_Assistant_OfficeLite) - Y200 server for KUKA OfficeLite integration
* [KUKA OfficeLite Documentation](https://www.kuka.com) - Official KUKA virtual controller documentation
* [OpenCommissioning Initiative](https://opencommissioning.com) - Open-source virtual commissioning tools

## See Also

* [Drive](https://doc.realvirtual.io/components-and-scripts/motion/drive) - For connecting axis signals to robot joints
* [Signal Manager](https://doc.realvirtual.io/components-and-scripts/interfaces/interface-tools/signal-manager) - Managing interface signals
* [Signal Importer Exporter](https://doc.realvirtual.io/components-and-scripts/interfaces/signal-importer-exporter) - Import and export signal configurations
* [Custom Interfaces](https://doc.realvirtual.io/components-and-scripts/interfaces/custom-interfaces) - Creating custom interfaces