Skip to content

🦾 KER Exoskeleton Teleoperation Tutorial

This tutorial uses the openarmx_teleop_ker ROS 2 package to map the KER's 16 angle channels to OpenArm 1.0, OpenArm 2.0, or OpenArmX. For the first integration, use simulated hardware; verify directions, ranges, gripper behavior, and loss-of-link behavior before switching to a real robot.

🧰 Environment and build

The package targets Ubuntu 22.04 with ROS 2 Humble, Python 3, NumPy, PyYAML, and pyusb. In your ROS 2 workspace:

cd ~/openarmx_ws
colcon build --packages-select openarmx_teleop_ker --symlink-install
source install/setup.bash

If USB permissions are required, add the user to dialout and log in again:

sudo usermod -a -G dialout $USER

🚀 Startup order

Open three terminals:

  1. Start the robot controller, initially with fake hardware.
  2. Start the KER teleoperation node.
  3. Observe topics, joint states, and logs while gradually increasing motion amplitude.
ros2 launch openarmx_bringup openarmx.bimanual.launch.py \
  control_mode:=mit robot_controller:=forward_position_controller \
  use_fake_hardware:=true

ros2 launch openarm_bringup openarm.bimanual.launch.py \
  arm_type:=openarm_v2.0 robot_controller:=forward_position_controller \
  use_fake_hardware:=true

ros2 launch openarm_bringup openarm.bimanual.launch.py \
  arm_type:=openarm_v1.0 robot_controller:=forward_position_controller \
  use_fake_hardware:=true

🔌 Connect the KER

Choose the robot value matching the robot started above: openarmx for OpenArmX, openarm_2.0 for OpenArm 2.0, and openarm_1.0 for OpenArm 1.0. The examples below default to OpenArmX; replace robot for another platform.

Connect the KER to the computer with a USB cable, then run:

ros2 launch openarmx_teleop_ker teleop_ker.launch.py \
  robot:=openarmx connection:=usb

The node reads poses through the USB Vendor interface while KER Manager uses USB CDC for device management. Do not let two teleoperation nodes claim the same USB Vendor interface.

Configure Wi-Fi and switch the data transport in KER Manager. Put the computer and KER on the same network, then replace the example IP with the actual device address:

ros2 launch openarmx_teleop_ker teleop_ker.launch.py \
  robot:=openarmx connection:=wifi \
  wifi_host:=192.168.3.112 wifi_port:=19090

When mDNS is available, wifi_host can be openarm-ker.local. Wi-Fi uses UDP, keeps only the newest pose, sends a heartbeat every second, and re-handshakes after a device restart or network recovery.

The node reads the device schema and publishes commands at 500 Hz by default.

🔍 Check data and controllers

ros2 topic list | grep -E 'forward_position|joint_trajectory'
ros2 topic echo /left_forward_position_controller/commands
ros2 topic echo /joint_states

OpenArmX publishes to the two forward_position_controller topics. Each topic contains 7 joints and 1 gripper. The controller joint count, names, and order must exactly match the YAML configuration.

🛡️ Safety verification checklist

  • Confirm every joint direction in simulation and make sure the arms are not swapped.
  • Confirm that startup from the neutral pose does not jump; increase startup.ramp_sec if needed.
  • Confirm gripper direction and travel.
  • Confirm that unplugging USB, interrupting Wi-Fi, or stopping KER data does not leave the robot executing dangerous motion.
  • Keep the emergency stop available for real-robot operation, with the operator and safety person ready to release control.

❓ Troubleshooting

  • No data: check USB permissions and interface ownership, or check Wi-Fi address, port, and network segment.
  • Controller update error: check output type, topic/action, joint count, and order.
  • Wrong direction: swap the two values in that joint's output_range in YAML.
  • Gripper does not move: check trigger index, input range, output_unit, and controller interface.
  • Startup jump: confirm /joint_states is published and increase startup.ramp_sec.
  • Jerky motion: use appropriate jump_reject and max_step; do not enable Hampel blindly for normal fast motion.