Quick Start¶

To teleoperate with an Xbox controller, with Perseus-Lite powered up you will need to run

Terminal 1¶

nix shell
ros2 launch perseus_lite perseus_lite.launch.py cmd_vel_topic:=/joy_vel

Terminal 2¶

nix run .#generic_controller

Basic Operation¶

This guide covers the basic teleoperation of Perseus-Lite using keyboard control. Perseus-Lite is a simplified version of Perseus that provides essential rover functionality with streamlined hardware and software requirements.

Prerequisites¶

The following conditions must be met before beginning:

• The laptop runs a Linux distribution with the latest code from the perseus-v2 Github repository:

  git checkout main
  git pull
  

• Perseus-Lite hardware is connected via USB (typically /dev/ttyACM0)

• Perseus-Lite has sufficient battery charge or is powered by a 12V power supply

Summary¶

1. Connect Perseus-Lite hardware

2. Build the software using Nix

3. Launch Perseus-Lite system

4. Launch control software

5. Operate Perseus-Lite safely

Hardware Connection¶

1. Connect Perseus-Lite’s USB cable to your laptop

2. Verify the connection:

   ls /dev/ttyACM*
   

   You should see /dev/ttyACM0 or similar device listed

Software Setup¶

Build the Software¶

Build the Perseus-Lite software using Nix:

cd perseus-v2
nix build

Launch Perseus-Lite System¶

Launch the Perseus-Lite ROS2 system:

export LC_ALL=C && export LANG=C
nix develop --command bash -c "cd software/ros_ws && colcon build --packages-up-to perseus_lite && source install/setup.bash && ros2 launch perseus_lite perseus_lite.launch.py"

Verify System Status¶

Open a new terminal and verify the system is running:

export LC_ALL=C && export LANG=C
nix develop --command bash -c "source software/ros_ws/install/setup.bash && ros2 topic list"

You should see topics including:

• /cmd_vel - Command velocity input

• /joint_states - Real-time servo positions and velocities

• /diff_drive_base_controller/odom - Odometry data

Check joint states to verify servo feedback:

export LC_ALL=C && export LANG=C
nix develop --command bash -c "source software/ros_ws/install/setup.bash && ros2 topic echo /joint_states --once"

You should see output similar to this (values will vary based on wheel positions):

header:
  stamp:
    sec: 1234567890
    nanosec: 123456789
  frame_id: ""
name:
  - front_left_wheel_joint
  - front_right_wheel_joint
  - rear_left_wheel_joint
  - rear_right_wheel_joint
position:
  - 0.0
  - 0.0
  - 0.0
  - 0.0
velocity:
  - 0.0
  - 0.0
  - 0.0
  - 0.0
effort:
  - 0.0
  - 0.0
  - 0.0
  - 0.0
---

Control Software Launch¶

Keyboard Control¶

In a new terminal, launch keyboard teleoperation:

cd perseus-v2
export LC_ALL=C && export LANG=C
nix develop --command bash -c "source software/ros_ws/install/setup.bash && ros2 run teleop_twist_keyboard teleop_twist_keyboard --ros-args -p stamped:=true -r cmd_vel:=key_vel"

Keyboard Controls¶

The keyboard control interface provides the following commands:

• Movement Controls:

  • i - Move forward

  • k - Stop

  • , - Move backward

  • j - Turn left

  • l - Turn right

  • u - Forward + left

  • o - Forward + right

  • m - Backward + left

  • . - Backward + right

• Speed Controls:

  • q/z - Increase/decrease linear speed by 10%

  • w/x - Increase/decrease angular speed by 10%

Xbox Controller (Alternative)¶

If you prefer Xbox controller input:

cd perseus-v2
export LC_ALL=C && export LANG=C
nix develop --command bash -c "source software/ros_ws/install/setup.bash && ros2 launch input_devices xbox_controller.launch.py"

Safe Operation¶

Safety Protocol¶

Before operating Perseus-Lite:

1. Ensure the operating area is clear of obstacles

2. Keep the Perseus-Lite system within sight

3. Be ready to stop operation immediately if needed

4. Monitor the terminal for any error messages

Initial Testing¶

Test Perseus-Lite’s movement systematically:

1. Begin with slow speeds

2. Test forward and backward motion separately from turning

3. Verify movement matches expected directions

4. Check that the stop command (k) works immediately

Stopping Operation¶

To stop Perseus-Lite operation:

1. Press k in the keyboard control terminal to stop movement

2. Press Ctrl+C in the keyboard control terminal to exit

3. Press Ctrl+C in the Perseus-Lite system terminal to shutdown

Troubleshooting¶

If Perseus-Lite is not responding:

1. Check that the USB connection is secure

2. Verify /dev/ttyACM0 is accessible

3. Check the Perseus-Lite system terminal for error messages

4. Restart the Perseus-Lite system if necessary

Common issues:

• No servo response: Check USB connection and power

• Permission denied on /dev/ttyACM0: Add user to dialout group or use sudo

• Locale warnings: Use export LC_ALL=C && export LANG=C before commands

System Shutdown¶

To properly shutdown Perseus-Lite:

1. Stop all movement commands

2. Press Ctrl+C in the keyboard control terminal

3. Press Ctrl+C in the Perseus-Lite system terminal

4. Disconnect the USB cable

5. Power down Perseus-Lite hardware