# KUKA Controller Setup Guide

Getting RSIPI talking to a real robot: installing the config files on a KRC4
controller, configuring the network, and troubleshooting the common failure
modes.

Primary source: the official **KUKA.RobotSensorInterface 3.3 manual**
(KST RSI 3.3 V5, issued 2016-10-17, for KSS 8.3/8.4), available from KUKA
via [my.kuka.com](https://my.kuka.com) or your KUKA support contact (it is
KUKA-copyrighted, so it is not redistributed with this repo). Section/page
references below (e.g. "manual §8.1.1, p. 56") point into that document. Claims not covered by the
manual are marked *(practical experience)* and sourced at the bottom.

## Prerequisites

- **KRC4 controller** with **KSS 8.3 or 8.4** and the
  **KUKA.RobotSensorInterface 3.x** option package installed
  (manual §4.1, p. 25). Check **Help > Info > Options** on the pendant.
  RSI provides `RSI_CREATE`, `RSI_ON`, `RSI_MOVECORR`, `RSI_OFF`,
  `RSI_DELETE` (manual §7.1, p. 39).
- RSI must **not** be installed together with KUKA.ConveyorTech or
  KUKA.ServoGun TC (manual §4.1, p. 25).
- For corrections in `#IPO` sensor mode, **function generator 1 must be
  free** (manual §4.1, p. 25; configurable via `RSITECHIDX` in
  `KRC:\R1\TP\RSI\RSI.DAT`, manual §5.2, p. 30).
- PC side: Python 3.10+ with RSIPI installed (`pip install -e .`), on a
  network interface reachable from the controller. KUKA specifies a
  "real-time-capable operating system and real-time-capable network card
  with 100 Mbit in full duplex mode" (manual §4.1, p. 25) — a normal
  Windows/Linux PC works for testing but is not real-time capable, so
  expect occasional late packets (see [Timing](#timing-requirements)).

## 1. Install the files

The files in `rsi_config/` go to **two different places**. This split is
specified in manual §8.1.1, p. 56:

> 2. Copy KRL programs into the directory `C:\KRC\ROBOTER\KRC\R1\Program`
>    of the robot controller.
> 3. Copy the sample configurations and the XML file for the Ethernet
>    connection to the directory
>    `C:\KRC\ROBOTER\Config\User\Common\SensorInterface` of the robot
>    controller.

| File | Destination on controller |
|---|---|
| `RSIPI_Full.rsi` | `C:\KRC\ROBOTER\Config\User\Common\SensorInterface\` |
| `RSIPI_Full.rsi.diagram` | `C:\KRC\ROBOTER\Config\User\Common\SensorInterface\` |
| `RSIPI_Full.rsi.xml` | `C:\KRC\ROBOTER\Config\User\Common\SensorInterface\` |
| `RSI_EthernetConfig_Full.xml` | `C:\KRC\ROBOTER\Config\User\Common\SensorInterface\` |
| `RSIPI_Minimal.src` | `C:\KRC\ROBOTER\KRC\R1\Program\` (= `KRC:\R1\Program` in the Navigator) |
| `RSIPI_Test.src` | `C:\KRC\ROBOTER\KRC\R1\Program\` (= `KRC:\R1\Program` in the Navigator) |

Watch the paths carefully — they are confusingly similar:

- KRL programs go under `...\ROBOTER\KRC\R1\Program` (**with** `\KRC\`).
- SensorInterface files go under `...\ROBOTER\Config\User\Common\...`
  (**without** a second `\KRC\`). Putting them in
  `C:\KRC\ROBOTER\KRC\Config\User\Common\SensorInterface` is a common
  mistake; `RSI_CREATE` will not find them there.
- A `.src` file placed in the SensorInterface folder never appears as a
  program, and a program that isn't loaded through `KRC:\R1\Program` throws
  "variable not defined" on every RSI keyword.

Notes:

- The RSI, DIAGRAM and XML files "form a unit and must be transferred to
  the robot controller together" (manual §8.1, p. 55).
- **Do not rename the files.** `RSIPI_Full.rsi` references
  `RSI_EthernetConfig_Full.xml` by name in its ETHERNET object, and the
  `.src` programs load `"RSIPI_Full.rsi"` by name in `RSI_CREATE`.
- Copy `.src` files as the **Expert** user group (log on via
  Configuration > User group).

## 2. Configure the network

RSI needs "its own Ethernet sensor network which is independent of other
KLI subnetworks", physically connected via the KLI ports X66 or X67.1-3 on
the controller cabinet (manual §5.1, p. 29).

### Controller side

Two documented ways to set the robot's RSI IP address (manual §5.1.1 and
§5.1.2, pp. 29–30):

**A. KLI network configuration on the pendant** (requires KSS 8.3.15+,
Expert group, T1/T2, no program selected):

1. Main menu > **Start-up > Network configuration** > **Advanced...**
2. **Add interface**; name it (e.g. "Ethernet sensor network").
3. Set **Address type: Mixed IP address** — this auto-creates the
   real-time UDP receiving tasks RSI needs.
4. Enter the robot's IP and subnet mask, **Save**, and **reboot the
   controller**.

**B. RSI-Network tool in Windows** (Expert group): minimize the HMI
(Start-up > Service > Minimize HMI), run **All Programs > RSI-Network**,
select the entry **New** under *RSI Ethernet* in the tree, press **Edit**,
enter the robot controller's IP, confirm, then **cold restart** the
controller.

IP address rules (manual §5.1.1, p. 29):

- PC and controller must be "located in the same network segment", i.e.
  only the last of the 4 octets may differ.
- "The IP address range **192.168.0.x is blocked**" and the address "must
  not be in the address range of another KLI subnet". The manual's example
  uses robot `192.168.1.2` / mask `255.255.255.0` with the sensor (PC) at
  `192.168.1.1`. This repo's default config uses `10.10.10.x`, which
  safely avoids all KUKA-internal ranges *(practical experience — see
  Sources)*.

### "Address already in use" when adding the interface

This error is not documented in the manual *(practical experience)*: it
appears when the address you enter collides with an interface entry that
already exists — a leftover RSI Ethernet entry, or another KLI subnet
containing the same address. Fix: in the interface tree, **edit or delete
the existing entry instead of adding a second one** (note the documented
RSI-Network procedure edits the existing "New" entry rather than creating
another), and make sure the subnet doesn't overlap any other configured
interface. Reboot (cold restart) afterwards — network changes only take
effect after a reboot (manual §5.1.1 step 8 / §5.1.2 step 5, p. 30).

### PC side

Give the PC a **static IP** on the RSI link and put that address in
`RSI_EthernetConfig_Full.xml` (both the copy on the controller and the copy
the Python side loads — they must match):

```xml
<CONFIG>
   <IP_NUMBER>10.10.10.10</IP_NUMBER>   <!-- your PC's IP -->
   <PORT>64000</PORT>
   <SENTYPE>ImFree</SENTYPE>
   <ONLYSEND>FALSE</ONLYSEND>
</CONFIG>
```

Pick a free UDP port "not assigned a standard service" (manual §8.1.2.1,
p. 58). Allow that UDP port through the PC firewall, or disable the
firewall on the dedicated RSI interface *(practical experience)* — a
blocked firewall shows up as "Python receives nothing" while a packet
capture still sees traffic arriving.

### Timing requirements

The robot controller initiates the exchange and sends a packet every
sensor cycle; "a data packet received by the sensor system must be
answered within the sensor cycle rate. Packets that arrive too late are
rejected. When the maximum number of data packets for which a response has
been sent too late has been exceeded, the robot stops." (manual §2.3.2,
p. 15). The sensor cycle is **4 ms** in `#IPO_FAST` (default) or **12 ms**
in `#IPO` mode (manual §7.1.4, p. 41). The allowed number of late packets
is the `Timeout` parameter of the ETHERNET object — set to 100 in
`RSIPI_Full.rsi`.

## 3. First run: minimal test

`RSIPI_Minimal.src` mirrors KUKA's official `RSI_Ethernet.src` example
(manual §8.1.3, p. 59: `RSI_CREATE` → `RSI_ON(#RELATIVE)` →
`RSI_MOVECORR()` → `RSI_OFF`) and uses no `$TECH` variables, no I/O and no
`$SEN_PREA` — so it isolates "does RSI work at all" from everything else.

1. On the pendant (T1 mode, low override): select `RSIPI_Minimal` and start
   it. It does a BCO run to the current position, activates RSI, and reports
   *"RSI active - start the Python sender now"*. The robot holds position,
   waiting for corrections.
2. On the PC, from the repo root:

   ```python
   from RSIPI import RSIAPI

   api = RSIAPI("RSI_EthernetConfig_Full.xml")
   api.start()
   if not api.wait_for_connection(timeout=30.0):
       raise SystemExit("No packets from robot - see troubleshooting table")

   print("Connected:", api.motion.get_current_pose())
   api.motion.update_cartesian(X=5.0)   # small 5mm correction
   input("Press Enter to stop...")
   api.stop()
   ```

3. Stop by cancelling the program on the pendant. Stopping the Python side
   instead also works: after `Timeout` late packets the robot stops and
   reports an RSI communication error — expected and safe (manual §2.3.2,
   p. 15). (A clean stop signal would require a STOP object in the signal
   flow, manual §7.1.6, p. 42 — `RSIPI_Full.rsi` doesn't include one.)

Keep first corrections small. The signal flow limits Cartesian corrections
to ±500 mm (`POSCORR1` in `RSIPI_Full.rsi`), which is generous — tighten it
in RSI Visual and/or set software limits on the Python side via
`api.safety.set_limit()` before doing anything real.

Independent cross-check: KUKA ships a Windows test server (`TestServer.exe`)
with the RSI option package for exactly this purpose (manual §8.1.2, p. 56)
— find it on the controller under
`D:\KUKA_OPT\RSI\DOC\Examples\Ethernet\Server` (manual §8.1, p. 55). If the
robot exchanges packets with TestServer but not with RSIPI, the problem is
on the Python/firewall side, not the robot.

## 4. Full test

`RSIPI_Test.src` + `rsi_config/rsipi_test.py` exercise the whole feature
set: corrections, `$SEN_PREA` (via MAP2SEN_PREA objects, manual §11.2.10,
p. 81), digital I/O, and a handshake over the `Tech.C` / `Tech.T` channels.
Those channels are "technology parameters in the main run / advance run
(function generators 1 to 6)" (manual §7.4.5–7.4.6, pp. 52–53): on the
wire, `DEF_Tech.C1` carries the ten parameters of function generator 1 as
attributes `C11…C110`.

On the KRL side the test program reads/writes these as `$TECH.C[11]` etc.
On at least one user's KSS 8.3.38 installation these `$TECH` references
fail to load with "variable not defined"
([issue #1](https://github.com/otherworld-dev/rsi-pi/issues/1)) — the
variables appear tied to a technology-package installation, and the exact
availability conditions haven't been pinned down yet. **If only the
`$TECH.…` lines error, run `RSIPI_Minimal.src` instead** — everything
except the Tech handshake works without them.

## 5. Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| "Variable not defined" on **every** line / `RSI_CREATE`, `RSI_ON`, `RSIOK` unknown | `.src` file not in `KRC:\R1\Program`, or RSI option not installed | Move the `.src` (see §1); check RSI appears under Help > Info > Options |
| "Variable not defined" only on `$TECH.…` lines | `$TECH` technology parameters not available on this installation | Use `RSIPI_Minimal.src` (see §4) |
| "Address already in use" when creating the RSI Ethernet entry | An interface entry with that address/subnet already exists | Edit or delete the existing entry instead of adding a new one; reboot (see §2) |
| `RSI_CREATE` returns `RSIFILENOTFOUND` / `RSIINVFILE` | Config files missing from `Config\User\Common\SensorInterface` (check for the extra-`\KRC\` path mistake), renamed, or `.rsi`/`.rsi.xml`/`.diagram` set incomplete | Re-copy all four config files together, keep original names (manual §7.1.2, p. 40 for return codes) |
| `RSI_ON` fails / RSI communication error immediately | IP in `RSI_EthernetConfig_Full.xml` doesn't match the PC, or subnet mismatch (only last octet may differ), or PC in `192.168.0.x` | Fix `<IP_NUMBER>`; follow the IP rules in §2 |
| Robot program runs but Python sees no packets | PC firewall blocking the UDP port, or RSIPI bound to the wrong interface | Allow the port / disable firewall on the RSI interface; verify with KUKA's `TestServer.exe` (see §3) |
| Robot stops mid-motion with RSI error after running fine | Response packets late: Python loop blocked, or non-dedicated network | Keep the correction loop free of blocking work; use a dedicated interface; watch the `Delay` variable (count of late packets, manual §7.4.5, p. 52) |
| Corrections apply but motion is jerky | Late/rejected packets | Same as above — dedicated network, faster loop |

Still stuck? Open an issue with your KSS version, RSI version (Help > Info >
Options), and the exact pendant error message.

## Sources

- **KUKA.RobotSensorInterface 3.3** manual, KST RSI 3.3 V5, KUKA Roboter
  GmbH, 2016-10-17 — from KUKA ([my.kuka.com](https://my.kuka.com)).
  All "manual §…" references above.
- [Michael Sobrepera, "KUKA Setup Guide"](https://michaelsobrepera.com/guides/kuka.html)
  — practical KRC4 + RSI walkthrough (network interface creation, firewall,
  file copying).
- Robot-Forum: [KRC4 RSI Ethernet](https://www.robot-forum.com/robotforum/thread/12240-krc4-rsi-ethernet/)
  and [IP addresses in network configuration of KRC4](https://www.robot-forum.com/robotforum/thread/16990-ip-addresses-in-network-configuration-of-krc4/)
  — reserved KRC4 subnets (`192.168.0.x` shared-memory driver) and RSI
  network setup experience.