Kuka master updates

README.md

@@ -0,0 +1,89 @@
+# Package for commisioning and testing of b»Controlled Box
+
+**Your realtime ROS 2 gateway for 24/7 applications!**
+
+**b»Controlled Box** is a software module for industrial controllers like the **Bosch Rexroth ctrlX CORE**, enabling real-time robot control using **ROS 2.** This package contains instructions to set up and commission your system.
+
+## Table of Contents
+
+- [System Overview](#system-overview)
+- [Compatibility](#compatibility)
+- [Getting started](#getting-started)
+- [How It Works](#how-it-works-a-typical-data-flow)
+
+
+# System Overview
+
+This system provides a seamless and robust bridge between the high-level ROS 2 ecosystem and the real-time world of industrial automation.
+
+By leveraging the **Bosch Rexroth ctrlX AUTOMATION** platform, developers can use standard **ROS 2** tools like MoveIt2 and RViz to control industrial robots that require real-time, low-latency communication. This architecture combines the flexibility of open-source robotics with the reliability of industrial hardware.
+
+![system architecture](docs/assets/architecture.png)
+
+The architecture consists of physical devices: the PC with ROS 2 high-level application (without control), the ctrlX CORE industrial controller, and the physical robot.
+
+1. **The PC with ROS 2:** A standard PC for application development using the full suite of ROS 2 packages (MoveIt2, RViz, etc.). It communicates with the ctrlX CORE over a standard ROS 2 DDS network.
+
+2. **The Industrial Bridge (ctrlX CORE):** An industrial-grade controller running ctrlX OS. It uses a real-time Data Layer and our custom Control Bundle (a `ros2_control` controller manager) to translate ROS 2 commands into real-timesignals for the robot.
+
+3. **The Robot:** An industrial robot that supports a real-time streaming interface (e.g., EtherCAT, UDP/IP) and is physically connected to the ctrlX CORE.
+
+
+# Compatibility
+
+### `b»controlled box` compatibility
+
+| `b»controlled box`         |  ROS 2 Version         |  `CtrlX RT SDK`         |
+| :------------------------- | :--------------------: | :---------------------: |
+| **1.5.8 (Latest)**         |         Jazzy          |         3.6.3           |
+
+
+### Supported hardware
+
+| Hardware                          |  Type       |  Status   |
+| :-------------------------------- | :---------: | :-------: |
+| **UR**                            | Robot       | ✅ | 
+| **KUKA**                          | Robot       | ✅ | 
+| **KASSOW**                        | Robot       | ✅ |
+| **FRANKA**                        | Robot       | ✅ | 
+| **DOBOT**                         | Robot       | ✅ | 
+| **Pssbl**                         | Robot       | ✅ |
+| **Fanuc**                         | Robot       | 🔬 | 
+| **Yaskawa**                       | Robot       | 🚧 | 
+| **Ethercat Master (CtrlX App)**   | Robot       | ✅ |
+| **OPCUA client**                  | Robot       | ✅ | 
+| **Beckhoff ADS client**           | Robot       | 🔬 | 
+| **Modbus server**                 | Robot       | 🔬 |
+
+#### Legend:
+* **✅ Tested:** Fully tested and supported in production.
+* **🔬 Preliminary:** In development; basic functionality is confirmed in the lab.
+* **🚧 To Be Tested:** Planned for testing in this version but not yet validated.
+* **❌ Not Supported:** No support is available or planned for this version.
+
+# Getting started
+
+Ready to begin? Follow our step-by-step guides to get your system up and running.
+The process is divided into three main parts:
+
+1. setting up [**ctrlX CORE device**](docs/SETUP_CTRLX.md)
+2. setting up the robot itself - refer to **manufacturer-specific instruction**
+     * [**KUKA**](docs/supported_robots/KUKA.md)
+     * [**UR**](docs/supported_robots/UR.md)
+     * [**KASSOW**](docs/supported_robots/KASSOW.md)
+     * [**FRANKA**](docs/supported_robots/FRANKA.md)
+     * [**Pssbl**](docs/supported_robots/PSSBL.md)
+     * [**FANUC**](docs/supported_robots/FANUC.md)
+     * [**DOBOT**](docs/supported_robots/DOBOT.md)
+3. setting up [**b»Controlled Box commissioning environment**](docs/SETUP_COMMMISSIONING.md)
+
+## How It Works: A Typical Data Flow
+
+Here is the step-by-step journey of a command from your computer to the robot's movement on example of EtherCAT communication:
+
+1.  **Command Generation:** On the development PC, a tool like MoveIt2 or a custom node publishes a command to a ROS 2 topic.
+2.  **Network Transmission:** The command travels over the ROS 2 DDS network to our **b»controlled box** App running on the ctrlX CORE.
+3.  **Controller Management:** The `ros2_control` controller manager inside the b»controlled box receives the command and forwards it to the appropriate controller
+4.  **Data Layer Write:** Our custom hardware interface transports the command (e.g., target joint positions) into the **ctrlX Data Layer** in a real-time-safe context.
+5.  **Real-Time Read & Stream:** The **EtherCAT Master** app, running in a deterministic loop, reads these values from the Data Layer.
+6.  **Robot Movement:** The EtherCAT Master streams the commands over the physical bus to the robot, which executes the motion precisely. The robot's feedback (actual position, velocity) travels back through the same path.

comissioning.env.example

@@ -0,0 +1,17 @@
+IMAGE_REGISTRY_URL=code.b-robotized.com:5050/b-controlled-box/releases
+
+ROBOT_TYPE=kuka
+IMAGE_NAME=${ROBOT_TYPE}-commission
+IMAGE_TAG=1.0.0
+
+IMAGE_TAG_FULL=${IMAGE_REGISTRY_URL}/${IMAGE_NAME}:${IMAGE_TAG}
+
+CONTAINER_NAME=${IMAGE_NAME}
+
+# The network interface on your computer that is connected to the 192.168.28.x network.
+# Run 'ip addr' in your terminal to find this. Look for an interface with an IP in that range.
+HOST_NETWORK_INTERFACE=
+
+# The static IP address you want to assign to the container on the macvlan network.
+# ROS_STATIC_PEERS on CtlrX CORE sees only 192.168.28.201 and 192.168.28.202 in the ROS network. Container and PC should use one of these addresses if they wish to participate.
+CONTAINER_MACVLAN_IP=192.168.28.202

docker-compose.yml

@@ -0,0 +1,50 @@
+# Docker Compose file for the ROS 2 commissioning environment.
+# This setup uses a macvlan network to allow the container to communicate
+# directly with the ctrlX CORE device on the local network.
+
+services:
+  ros-container:
+    image: ${IMAGE_TAG_FULL}
+    container_name: ${CONTAINER_NAME}
+    hostname: ${CONTAINER_NAME}
+    restart: "no"
+    networks:
+      ctrlx_bridge:
+      ctrlx_macvtap:
+        ipv4_address: ${CONTAINER_MACVLAN_IP}
+
+    # --- X11 Forwarding for GUI Applications (e.g., RViz) ---
+    devices:
+      - /dev/dri:/dev/dri
+    environment:
+      - DISPLAY=$DISPLAY
+      - QT_X11_NO_MITSHM=1
+    volumes:
+      - /tmp/.X11-unix:/tmp/.X11-unix:rw
+      # Note: You may need to configure xauth on your host for this to work.
+      # xhost +local:docker
+      - /tmp/.docker.xauth:/tmp/.docker.xauth:rw
+
+    # allow access to kernel clock services
+    cap_add:
+    - SYS_TIME
+
+    # allow container to be interactive
+    stdin_open: true
+    tty: true
+
+networks:
+  # This accesses host's network, necessary for NTP
+  ctrlx_bridge:
+    name: ${CONTAINER_NAME}-bridge
+    driver: bridge
+
+  # This taps into the host's physical network interface.
+  ctrlx_macvtap:
+    driver: macvlan
+    name: ${CONTAINER_NAME}-macvtap
+    driver_opts:
+      parent: ${HOST_NETWORK_INTERFACE}
+    ipam:
+      config:
+        - subnet: 192.168.28.0/24

docs/SETUP_COMMMISSIONING.md

@@ -0,0 +1,130 @@
+# PC setup with ROS 2
+
+The commissioning PC host runs a Dockerized ROS 2 environment to communicate with the ctrlX CORE.
+
+## 1. Prerequisites
+
+### 1.1 Clone this repository
+
+  ```
+  git clone https://github.com/b-robotized/b_ctrldbox_commissioning.git
+  cd b_ctrldbox_commissioning
+  ```
+### 1.2 Install Docker Desktop
+
+  Docker desktop is required to run the container and set up networking via `docker compose` command.
+  Refer to [this documentation](https://rtw.b-robotized.com/master/docker/general_information_docker/general_information_docker.html#installation-of-docker) for instructions.
+
+### 1.3 Network Configuration:
+
+#### Zenoh:
+---
+b»controlled box uses **zenoh** as the middleware of choice due problems which DDS introduces with UDP multicast for discovery and transport, as well as its opaque and arcane configuration options.
+
+We encourage you to try out zenoh for your workspace. 
+To easily transition to zenoh, check out our [zenoh setup guide](./SETUP_ZENOH.md).
+
+
+#### FastRTPS:
+---
+
+  Configure a static IP address **on your PC's port** connected to CtrlX XF10 port to `192.168.28.201` with netmask `255.255.255.0`.
+
+  ***IMPORTANT: ROS 2 DDS on the b»controlled box is configured to see only IP addresses `192.168.28.201` (for the dev PC) and `192.168.28.202` (for the commissioning Docker container).***
+
+  #### for example, if these are the default and recommended IPs in the system:
+
+  - **CtrlX CORE:** `192.168.28.7`
+  - **ROS2 PC:** `192.168.28.201`
+  - **commissioning Docker container:** `192.168.28.202`
+
+  .. then these are `ROS_STATIC_PEERS` env variables:
+  - **CtrlX CORE:** `192.168.28.201, 192.168.28.202`
+  - **commissioning Docker container:** `192.168.28.7`
+
+  depending on which participant the actor expects to see.
+
+  Verify you can ping the ctrlX controller at its IP address from the docker container.
+
+### 1.4 Set up date-and-time NTP server
+To make sure the Date and Time are synchronized between the commissioning container and the CtrlX, navigate to `Settings -> Date and Time` and connect to the NTP server.
+
+***IMPORTANT: The commissioning container must be running for NTP server connection to succeed.***
+
+Enter the IP address of the commissioning container (`192.168.28.202`) and test the connection. If it succeeds, click "Save"
+
+If encountering NTP connection issues, refer to [NTP server setup](/docs/SETUP_NTP_SERVER.md) instructions for more details.
+
+![date-and-time](assets/ctrlx_date_and_time.png)
+
+### 1.5 Environment Configuration:
+
+  The repo contains an example `.env` file called `comissionning.env.example` which must be configured with your host information for the container to properly run
+
+  ```
+  cp comissioning.env.example commissioning.env
+  ```
+  * `ROBOT_TYPE`: Set to your robot model (e.g., kuka).
+
+  * `HOST_NETWORK_INTERFACE`: The name of the network interface on your PC connected to the ctrlX device (e.g., `eth0`). Use `ip addr` or `ifconfig` to find it.
+
+  * `CONTAINER_MACVLAN_IP`: The static IP for the Docker container. Set it to `192.168.28.202`.
+
+### 1.6 Make scripts executable:
+
+  Make the `start/enter/stop` bash scripts executable:
+  ```
+  chmod +x start.sh enter.sh stop.sh
+  ```
+
+# 2. Usage
+
+These are the commands for using the container
+
+### 2.1 Start the container: `start.sh`
+
+Upon first start, the container will be downloaded from our container repository. **It will require a login into our container registry!**
+#### Registry login:
+```
+echo "YOUR_REGISTRY_ACCESS_TOKEN" | docker login code.b-robotized.com:5050 -u ctrlx --password-stdin
+```
+The container also creates the necessary network configuration on the host PC
+```
+./start.sh
+```
+
+### 2.2 Access the container shell: `enter.sh`
+
+To access the container from other terminals, run:
+```
+./enter.sh
+```
+When entering the container, the ros environment will automatically be sourced. You can immediatelly run ros2 commands.
+
+
+### 2.3 Verify container network:
+
+Inside the container, run a quick ping to make sure it can see the ctrlX CORE:
+
+```
+ping 192.168.28.7
+```
+
+### 2.4 Launch the robot commands
+
+To run scenario commands from the container, refer to `LAUNCH.md` for commands specific to your robot type.
+
+Robot commands for a specific manufacturer can be found in this repo, [on the corresponding branch](https://github.com/b-robotized/b_ctrldbox_commissioning/branches) (e.g. `kuka-master` for [kuka](https://github.com/b-robotized/b_ctrldbox_commissioning/tree/kuka-master))
+
+
+### 2.5 Stop the container: `stop.sh`
+
+When you are finished, run this command from **host machine**, not the container.
+```
+./stop.sh
+```
+
+
+# Troubleshooting
+
+TBA

docs/SETUP_CTRLX.md

@@ -0,0 +1,97 @@
+# ctrlX CORE device setup
+
+For help with issues, refer to [Troubleshooting](#troubleshooting) at the end of this file.
+
+## 1. Network Connection
+
+1. Power on the ctrlX CORE device.
+
+2. Connect your PC to the device's commissioning port (typically `XF10`) via an Ethernet cable.
+
+3. **Device from b»robotized** If you have got the device with setup from b»robotized than the following steps are not relevant for you, still you can check them to better understand the configuration. Then check the documentation that you have got with the device for the IP address for ROS and engineering access through XF10 port.
+
+4. **Your device** The device has a default static IP address: `192.168.1.1`. Open a web browser and navigate to this address. You should see the ctrlX CORE login screen.```
+
+
+![login-screen](assets/login.png)
+
+Tip: For a general introduction to the ctrlX OS interface, see the official [Rexroth ctrlX OS Getting Started Playlist.](https://www.youtube.com/watch?v=kV8TtBNVecM&list=PLRO3LeFQeLyN8HlLG8VZzgoCLqTUcTPUx)
+
+
+
+### 1.1 Configure ROS 2 Network Interface
+***IMPORTANT:*** Section is only applicable if you did not get the device directly from b»robotized.
+
+1. In the ctrlX UI, navigate to `Settings > Network Interfaces.`
+![network-interface10](assets/network_interface_XF10.png)
+2. Select the X10 Ethernet port.
+3. Go to the `IPv4` tab and add as additional IP address `192.168.28.28` with subnet mask `255.255.255.0`.
+4. To validate the connection, navigate to `Settings > Network Diagnostics` and ping your robot.
+
+### 1.2 Configure Robot Network Interface
+***IMPORTANT:*** Section is only applicable if you did not get the device directly from b»robotized.
+
+Ensure the robot is powered on and connected. Then:
+
+1. In the ctrlX UI, navigate to `Settings > Network Interfaces.`
+![network-interface12](assets/network_interface_XF12.png)
+2. Select the Ethernet port connected to your robot. (Recommended: `XF12`)
+3. Go to the `IPv4` tab and set a static IP address that is on the same subnet as your robot.
+
+Recommened and default address is `10.23.23.28` with subnet mask `255.255.255.0`. _Note that if you got the device from b»robotized, there is a dedicated IP address for it - check the manual for more informations._
+
+### 1.3 Validate connections
+To validate either robot or PC connection, navigate to `Settings > Network Diagnostics` and ping your robot.
+![ping](assets/ctrlx_ping_robot.png)
+
+## 3. Install the b»controlled box App
+
+1. Obtain the b»controlled box Snap application file.
+
+2. Ensure the device is in **SERVICE** mode. This mode allows for app installation but does not provide real-time guarantees.
+
+3. Navigate to `Settings > Apps.`
+
+4. Upload the Snap file and click `Install`. The app will start automatically.
+
+## 4. Understanding Operation Modes
+
+The ctrlX OS has three key modes that manage the lifecycle of real-time applications.
+
+b»Controlled Box controller manager responds to these modes to ensure safe operation. For example, switch **OPERATIONAL** -> **SETUP** will automatically deactivate controllers that send motion commands.
+
+![modes](assets/modes.png)
+
+* **SERVICE**: The default mode for system configuration. You can install, update, or remove apps. Real-time execution is disabled.
+  * controller manager waits for robot description
+
+* **SETUP**: A real-time guaranteed mode for setting up the robot scenario.
+  * all hardware interfaces can be active. Controllers that do not claim command interfaces can be active
+
+* **OPERATIONAL**: The full real-time production mode. 
+  * all hardware interfaces and controllers can be active and the system is ready to control the robot.
+
+
+
+## 5. Configure the Real-Time Scheduler
+
+**The scheduler** is the heart of the ctrlX CORE's real-time system. It executes tasks from applications, called "callables," on a deterministic, real-time thread. b»Controlled Box ROS 2 controller manager's `read/update/write` loop is executed within such a callable.
+
+You can configure the cycle time of this callable to match your robot's communication and control requirements.
+
+1. Navigate to `Settings -> Scheduler -> Configuration` and select the **Edit** action in the Action column (the pencil icon)
+2. Adjust the cycle time and save.
+
+![scheduler](assets/scheduler.png)
+
+***Important: Any changes made to the scheduler settings will only be applied to the control bundle after the device transitions from SERVICE mode to SETUP mode.***
+
+
+## 6. Add app License - TBA
+
+For now, official licensing is to be implemented
+
+# Troubleshooting
+
+### Restarting the ctrlX CORE
+To restart the device, navigate to `Settings -> Shutdown` and select **Restart**