Mahmoud Abas, Full-Stack Software Engineer & AI

ROS 2 Practical - Lab 04: Keyboard Teleop Control for Warehouse Robot

In the print dialog, choose "Save as PDF" as the destination.

Lab 04

Keyboard Teleop Control for Warehouse Robot

Building a custom velocity-control node

What is Teleop?

Teleoperation: Remote operation of a robot by a human operator.

Keypress

ROS node

Twist message

/cmd_vel

Robot moves in Gazebo

Why write a custom node instead of using a stock package?

Customization: tailor controls to our specific needs
Learning: understand how ROS nodes work
Features: add custom functionality, such as speed limits and an emergency stop
Integration: tighter integration with warehouse_simulation

Control Scheme: Incremental Velocity

text

w : +0.1 m/s forward       x : -0.1 m/s (backward)
a : +0.2 rad/s left turn   d : -0.2 rad/s right turn
s : Stop                    SPACE : Emergency stop
q : Quit

Incremental, not hold-to-move: each key press adds to the current velocity
The robot keeps moving at that velocity until it is changed
Safety limits: max linear 1.0 m/s, max angular 2.0 rad/s

Node Skeleton and Publisher

python

class TeleopKeyNode(Node):
    def __init__(self):
        super().__init__('teleop_key')
        self.publisher = self.create_publisher(Twist, '/cmd_vel', 10)
        self.linear_velocity = 0.0
        self.angular_velocity = 0.0
        self.linear_step = 0.1
        self.angular_step = 0.2
        self.max_linear = 1.0
        self.max_angular = 2.0

The publisher and the safety limits are set up in __init__.

Reading Raw Keypresses

Terminal must be switched to raw mode to capture a single keypress, no Enter needed
Settings are always restored in finally

python

def get_key(self):
    fd = sys.stdin.fileno()
    old_settings = termios.tcgetattr(fd)
    try:
        tty.setraw(fd)
        ch = sys.stdin.read(1)
    finally:
        termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
    return ch

termios settings are saved before tty.setraw and restored no matter what happens.

Incremental Update with Clamping

python

def update_velocity(self, linear_change, angular_change):
    self.linear_velocity += linear_change
    self.angular_velocity += angular_change
    self.linear_velocity = max(-self.max_linear,
                                min(self.max_linear, self.linear_velocity))
    self.angular_velocity = max(-self.max_angular,
                                 min(self.max_angular, self.angular_velocity))

Clamping prevents runaway or dangerous speeds from repeated key presses

Publishing the Twist

python

def publish_velocity(self):
    msg = Twist()
    msg.linear.x = self.linear_velocity
    msg.angular.z = self.angular_velocity
    self.publisher.publish(msg)

Ground robots only need linear.x (forward and back) and angular.z (yaw): no y/z motion or roll/pitch

Main Loop and Emergency Stop

The loop reads a key, dispatches it to the matching handler, then publishes
s or SPACE zero out both velocities immediately
The finally block always stops the robot before the node exits

python

elif key == 's' or key == ' ':
    self.linear_velocity = 0.0
    self.angular_velocity = 0.0
    self.publish_velocity()

SPACE and s share the same stop handler.

Wire It Up and Build

Make the script executable
Register the entry point in setup.py
Rebuild the package and source the workspace

bash

chmod +x warehouse_simulation/teleop_key.py

python

entry_points={
    'console_scripts': [
        'teleop_key = warehouse_simulation.teleop_key:main',
    ],
},

bash

colcon build --packages-select warehouse_simulation
source install/setup.bash

Running and Testing

Terminal 1 launches the simulation, Terminal 2 runs teleop

bash

ros2 launch warehouse_simulation warehouse_simulation.launch.py
ros2 run warehouse_simulation teleop_key

Press w three times to accelerate forward
Press a twice to turn left
Press s to stop
Press x twice to reverse
Press d three times to turn right
Press SPACE for an emergency stop
Press q to quit

Monitoring and Debugging

bash

ros2 topic echo /cmd_vel
ros2 node list
ros2 node info /teleop_key
ros2 run rqt_graph rqt_graph

/teleop_key

/cmd_vel

/parameter_bridge

Gazebo

Common Issues

Alternatives and Extensions

Standard hold-to-move teleop: ros2 run teleop_twist_keyboard teleop_twist_keyboard (i/j/k/l layout)
Gamepad control: joy_node plus teleop_twist_joy
Extension ideas: speed presets, odometry position display, laser-scan collision warnings

Key Takeaways

Teleop = keypress to Twist message to /cmd_vel to robot motion
Incremental control (accumulate and clamp) gives smooth, safety-bounded movement
Ground robots only use linear.x and angular.z on a Twist message
Raw terminal mode is required to read single keypresses without Enter
Always verify with ros2 topic echo, ros2 node info, and rqt_graph before trusting behavior
A crashed or duplicate publisher on /cmd_vel is the most common cause of a robot behaving oddly

Open this lesson

Mahmoud AbasLab 04: Keyboard Teleop Control for Warehouse Robot

class TeleopKeyNode(Node): def __init__(self): super().__init__('teleop_key') self.publisher = self.create_publisher(Twist, '/cmd_vel', 10) self.linear_velocity = 0.0 self.angular_velocity = 0.0 self.linear_step = 0.1 self.angular_step = 0.2 self.max_linear = 1.0 self.max_angular = 2.0

def get_key(self): fd = sys.stdin.fileno() old_settings = termios.tcgetattr(fd) try: tty.setraw(fd) ch = sys.stdin.read(1) finally: termios.tcsetattr(fd, termios.TCSADRAIN, old_settings) return ch

def update_velocity(self, linear_change, angular_change): self.linear_velocity += linear_change self.angular_velocity += angular_change self.linear_velocity = max(-self.max_linear, min(self.max_linear, self.linear_velocity)) self.angular_velocity = max(-self.max_angular, min(self.max_angular, self.angular_velocity))