Skip to content

Assignment 1. Manual Controller with m2_joy

Info

To complete this assignment, you should have completed:

  • Lab 3.1. ROS 2 Topics in C++
  • Lab 3.2. ROS 2 Services in C++
  • Lab 3.3. ROS 2 Package, msg, srv

Motivation

Objective: Control a simulated robot on your computer with a joystick

  • In M2, one of the programmer tasks each year is to write a PS4 controller node that can allow us to drive the robot and give commands to tell it to perform different tasks.
  • In this assignment, you will write a node to control the movement of a simple simulated robot (the turtle) using a PS4 controller connected to your machine.
  • You will also learn how to use our m2_joy library.

Background. What is the turtle?

turtle_key

The "turtle" is the name for the simulated robot. This simulator is maintained by the ROS organization, the documentation is here: https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Introducing-Turtlesim/Introducing-Turtlesim.html

The above interface is running inside a simulator node called turtlesim_node.

Important

If you are trying to play with turtlesim on a remote machine (e.g. standalone Raspberry Pi) that are incapable of displaying GUI contents, you can use X11-Forwarding method to visualize the GUI contents on your local machine.

You can set up X11-Forwarding in your mac or windows according to the following guide:

  1. Download and install MobaXterm from here.
  2. Launch MobaXterm, and create a new session by clicking "Session" at the menu bar. Select "SSH" as Session Type. Then, enter remote machine's IP address and username. No need to change the port value.
  3. Select the "Advanced SSH settings" tab and then make sure the "X11-Forwarding" box is checked. Leave the rest of the settings at their defaults. Select OK.
  4. You have just logged into the remote machine, you can run command: rqt in the terminal, to verify if GUI content can be displayed on your windows.
  1. Download and install XQuartz from here.
  2. Remote access into the remote machine by using SSH with this command: ssh -X <username>@<hostname>. Note that, you need to replace the <username> and <hostname> with the actual username and hostname of remote machine. You can ask our team member about it. The -X option here enables X11-forwarding.
  3. Run command: rqt to launch rqt GUI application, and check if the GUI can be display on your mac.

Running the turtle

To run the turtlesim_node, run ros2 run turtlesim turtlesim_node, and the above window should pop up.

The turtlesim package also includes a keyboard-based controller. To run it, in a new terminal, run ros2 run turtlesim turtle_teleop_key.

In summary, you have to run the following two commands in separate terminals.

# on a separate terminal
$ ros2 run turtlesim turtlesim_node

# on a separate terminal
$ ros2 run turtlesim turtle_teleop_key

...(omitted)
Reading from keyboard
---------------------------
Use arrow keys to move the turtle.
  • Now you can use the arrow keys of the keyboard to drive the turtle around. If you cannot drive the turtle, select the terminal window of the turtle_teleop_key to make sure that the keys that you type are recorded.

Topics provided by turtlesim

The turtlesim_node receives velocity instructions via the topic /turtle1/cmd_vel. Try to use ros2 topic echo on a new terminal to see how the messages are interpreted when you are using the keyboard controller.

$ ros2 topic echo /turtle1/cmd_vel
linear:
  x: 2.0
  y: 0.0
  z: 0.0
angular:
  x: 0.0
  y: 0.0
  z: 0.0
---
linear:
  x: 2.0
  y: 0.0
  z: 0.0
angular:
  x: 0.0
  y: 0.0
  z: 0.0
---
  • The topic type can be obtained via ros2 topic type [topic] or ros2 topic info [topic].
$ ros2 topic type /turtle1/cmd_vel
geometry_msgs/msg/Twist

However, in this assignment, we will not be using the keyboard controller which only provides discrete driving controls. We will make our own PS4 controller node that has much more features!

m2_joy Dualshock 4 ROS driver

Dualshock 4

We often use the DS4 (DualShock 4, the model of the PS4 controller) for manual input.

To use the DS4 in ROS, we usually use the m2_joy package.

Installation instructions

Go into your ROS 2 workspace, and then git clone m2_joy package. 

$ cd ~/ros2_ws
$ git clone [email protected]:m2robocon/m2_joy src/m2_joy
$ python3 src/m2_joy/setup.py
$ colcon build --packages-up-to m2_joy

The python3 src/m2_joy/setup.py command installs our PS4 config files to your system, which requires root privilege. You may be prompted to type your sudo password.

Connect the DS4 to your computer

You can connect the DS4 to your computer with these 2 methods, depending on whether you connect DS4 to a remote machine (e.g. Raspberry Pi) or your local VM:

Firstly, install necessary bluetooth utilies packages by running sudo apt update && sudo apt install bluez in the Pi's terminal.

Press and hold the "ps" button of DS4 controller for a few seconds, until the led of panel start blinking with blue color. DS4 is now entering paring mode. Then, from the Raspberry Pi terminal, run command bluetoothctl. Search online on your own about how to use bluetoothctl to pair and connect to controller.

Plug a USB cable from your computer to the DS4. If you are on a virtual machine, you might need to add the USB device to your virtual machine:

Dualshock 4

After you connect the DS4, you should see the device name under the /dev directory by:

$ ls /dev | grep ds
ds4red
ds4red_tpad
ds4red_ff

The word red may be changed to other names depending on the controller you chose.

Topics provided by m2_joy

There are many features in the m2_joy package, but the most important thing you should note is how to launch the ROS nodes to get the DS4 input published:

  • After the DS4 is connected, on a new terminal, run ros2 launch m2_joy joy_msg.launch.xml joy:=/dev/ds4red
    • Replace ds4red with the device name in the previous step.
    • ros2 launch allows us to run a few nodes at once with one single command.
  • By default, DS4 data is published on the /input/joy_data topic. Try to use ros2 topic echo on a new terminal to see the message format when you are pressing buttons or moving input joysticks on the DS4.
$ ros2 topic echo /input/joy_data
hat_lx: 0.0
hat_ly: 0.347806990147
l2_analog: 0.0
hat_rx: 0.0
hat_ry: 0.0
r2_analog: 0.0
dpad_x: 0.0
dpad_y: 0.0
cross: True
circle: True
triangle: False
square: False
l1: True
r1: False
l2: False
r2: False
share: False
options: False
ps: False
l3: False
r3: False
tpad_click: False
  • The topic type can be obtained via ros2 topic type [topic] or ros2 topic info [topic], similar to the previous section.
$ ros2 topic type /input/joy_data
m2_interfaces/msg/JoyData

If you can display the message contents for both components (turtlesim, DS4), then you can start doing the actual assignment!

Required functionalities of your controller

Refer to the PS4 User's Guide for the names of different buttons: (https://manuals.playstation.net/document/en/ps4/basic/pn_controller.html) You should write a controller node, which provides the following functions:

  • Basic driving

    • Your controller should be able to complete the basic functionality of the vanilla keyboard controller. In other words, your controller can be used to make the turtle: go forwards, backwards, turn left, turn right.
    • Requirement: When the left stick is pushed up/down, the turtle should move forwards/backwards with variable speed based on the magnitude of push.
    • Requirement: When the right stick is pushed left/right, the turtle should turn anticlockwise/clockwise with variable speed based on the magnitude of push.

  • Velocity scale modification

    • The relative velocity magnitude from the sticks should be able to be changed.
    • This means, if your mapping from the magnitude of the left stick (let it be \(x\)) and the velocity of the turtle (let it be \(v\)) is \(v = x \cdot k\), where \(k\) is some constant, then the value of \(k\) should be able to be changed via controller input.
    • Requirement: When the "up"/"down" directional button is pressed, the controller should be more/less "aggressive" such that pushing the stick gives higher/lower velocity than before (in the example, \(k\) increase/decrease).
    • There should be exactly 5 discrete levels of "aggressiveness".

  • Clear background

    • Notice that when the turtle is moving, it leaves a pen trail.
    • Requirement: When the "ps" key is pressed, the trail should be cleared.
    • Refer to the turtlesim documentation (http://wiki.ros.org/turtlesim?distro=noetic) to see which service is to be called. Although this documentation is for ROS 1, but it can still give you some ideas about what each service does.

  • Change pen color

    • The pen trail color can actually be changed to different RGB color.
    • Requirement: When the △/○/×/□ button is pressed, the trail color should change to green/red/blue/purple respectively.
    • Refer to the turtlesim documentation (http://wiki.ros.org/turtlesim?distro=noetic) to see which service is to be called. Although this documentation is for ROS 1, but it can still give you some ideas about what each service does.

Template package

Where do I get even started with this assignment… there are so many tasks…

To help you, we have provided you with a template package, and you can work on the controller node directly!

  • Inside m2cs_ros_tutorial, you should see a package named turtle_ps4.
  • The node that you should be working on is turtle_ps4/src/ps4_controller.cpp. You do not need to modify the contents in turtlesim, m2_joy or other files in turtle_ps4!
  • If you are lost, there are some "blanks" and hints in the file that you can fill in to complete the assignment.

Assignment evaluation/testing procedures

This part describes how your assignment submission will be evaluated by the trainers, which also gives hints on how you can test your program while developing it.

  1. The trainer's machine will have m2_joy, turtlesim and the turtle_ps4 template installed as described at the background part of this assignment. A physical DS4 will be connected.
  2. The trainers will replace ps4_controller.cpp in turtle_ps4/src with your submitted version.
  3. The trainers will run the command ros2 launch turtle_ps4 test.launch.xml. ds4red in turtle_ps4/launch/test.launch.xml will be replaced accordingly. This command runs turtlesim_node, launches joy_msg.launch.xml, and runs your file ps4_controller.cpp.
  4. The trainers will test the features stated in "Required functionalities of your controller" one by one.
  5. The trainers will read your source code to check your implementation skills and coding style. You are encouraged (but not required) to discuss with other trainees, but we require you to write your own code (no plagiarism!).

Submission instructions

Please refer to the submission instructions on the teaching PPT slides.

Warning

We will start marking your assignments after the deadline, so make sure it is pushed!