Rover Zero - Tutorial 2 Computer Setup

These instructions will help you set up your ROS workspace and start working with the Rover Zero.  


Flash Your RPI 3B+

If you are using a Raspberry Pi 3 B+ for your project you have the option of flashing your microSD card with our custom image. The base OS is Lubuntu 16.04 and comes with ROS Kinetic, rr_openrover_stack, all the suggested udev rules, and a systemd unit that starts the rr_rover_zero_driver on boot to work with configurations matching our Starter Kit components. If you want to set everything up with an existing system or on a non-RPI system continue to the next section "Create Your Catkin Workspace".

1. Download the Rover Robotics RPI 3B+ OS image. Link

2. Download Balena Etcher. Link

3. Insert your microSD card (recommended 16GB+).

4. Unzip Etcher, and start the Etcher application.

5. Press "Select Images", and select the RPI image from the download location.

6. If your microSD card is not automatically select by the "Select target" phase, click "Change" and select you microSD card.

7. Press "Flash!" and wait a few minutes while the image is written the microSD card.

8. Unmount you microSD card and insert the card into your RPI.

9. Power your RPI and wait for a minute or so for the system to fully boot.

If you are using our Starter Kit or have your own Xbox 360 Wireless Controller plugged into your RPI then you should be able to drive your Rover Zero. All the ROS code for this behavior is located in the ~/catkin_ws directory.  

However, if you would like to suspend this behavior you can log into your RPI and deactivate the behaviour. There are several ways to connect to the RPI: attaching a monitor and key board, ethernet, or over wifi. If the RPI is not connected to a wifi network it will broadcast its own wifi. We will use this method for connecting the RPI. The default username and password are both 'ubuntu', we recommend changing these defaults.

10. Connect to the RPI wifi network
ssid: roverrobotics****
password: robotseverywhere

11. Create a remote connection to the RPI.
ssh ubuntu@10.42.0.1

12. Disable the systemd unit.
sudo systemctl disable rover-robotics.service

Create Your Catkin Workspace

The first step for any any ROS project is to create your catkin workspace. The following will walk you through setting up your workspace with the Rover Robotics' Open Rover Stack. This gives you all the code you need to get started and then some.

1. Create your workspace.
$ mkdir -p ~/zero_ws/src && cd ~/zero_ws/src

2. Clone the rr_openrover_stack repository with Git.
$ git clone https://github.com/RoverRobotics/rr_openrover_stack.git

3. Build your ROS code with Catkin.
$ cd ..
$ catkin_make

4. Source your workspace, this will allow you to run your code using ROS.
$ source devel/setup.bash

5. If you want to source the workspace when opening a new terminal you can add this to your .bashrc file.
$ echo "source $HOME/zero_ws/devel/setup.bash" >> ~/.bashrc

There you go! You should be ready to start developing with your Rover Zero. rr_rover_zero_driver containers the driver node in rover_zero.py, and the rest of the stack contains utility packages for controller mapping, control message management, robot body descriptor models. The next section will walk through setting up UDEV rules for your rover, this will make development easier and help avoid some potential serial communication issues.

Setting Up UDEV Rules

Let us start by identifying the device file path for the Rover Zero USB connection. Start with the Rover Zero powered on with the USB unplugged. Then run dmesg --follow, once the output is stabilized plug in your Rover Zero USB and then you should see an output that looks like the following.

$ dmesg --follow
[14003.088689] usb 1-1: new full-speed USB device number 11 using xhci_hcd
[14003.239215] usb 1-1: New USB device found, idVendor=03eb, idProduct=2404, bcdDevice= 1.00
[14003.239218] usb 1-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[14003.239220] usb 1-1: Product: USB Roboclaw 2x15A
[14003.242425] cdc_acm 1-1:1.0: ttyACM0: USB ACM device

What you are seeing is you kernel identifying the serial connection with the Rover Zero's motor controller, the Roboclow 2x15A. The last line tells us that the controller's serial device file enumerated to /dev/ttyACM0. Yours may come up as /dev/ttyACM1 or some other enumeration, but this should not be a problem. Just change any commands below to match your device name from the dmesg logs.

Now lets launch the Rover Zero driver node. The launch file example.launch in rr_rover_zero_driver initiates a single Rover Zero driver node. By default it tried to open serial communication through /dev/ttyACM0. You may need to change this based on your dmesg results by editing the dev parameter in the launch file.

$ roslaunch rr_rover_zero_driver example.launch
... logging to /home/ubuntu/.ros/log/ceb62ccc-5ca2-11ea-baf4-9cb6d0c4c4cf/roslaunch-ubuntu-2942.log
Checking log directory for disk usage. This may take awhile.
Press Ctrl-C to interrupt
WARNING: disk usage in log directory [/home/ubuntu/.ros/log] is over 1GB.
It's recommended that you use the 'rosclean' command.

started roslaunch server http://ubuntu:45813/

SUMMARY
========

PARAMETERS
* /rosdistro: melodic
* /rosversion: 1.14.3
* /rover_zero_driver_node/dev: /dev/rover-zero

NODES
/
rover_zero_driver_node (rr_rover_zero_driver/rover_zero.py)

auto-starting new master
process[master]: started with pid [2954]
ROS_MASTER_URI=http://localhost:11311

setting /run_id to ceb62ccc-5ca2-11ea-baf4-9cb6d0c4c4cf
process[rosout-1]: started with pid [2965]
started core service [/rosout]
process[rover_zero_driver_node-2]: started with pid [2968]
[FATAL] [1583166492.129595]: Could not open serial at /dev/ttyACM0

The execution of the node failed. If we look at the last line of the output we see that /dev/ttyACM0 was not able to be opened. This is because the driver node did not have permissions to open the file. A fast but temporary solution is to use chmod to change the permissions the Rover Zero device file.

$ sudo chmod 666 /dev/ttyACM0

When we launch the Rover Zero node again we see that it executes correctly. However, this stills leaves us with a couple of problems. Firstly, this solution is only temporarily. If we reboot our computer the permissions changes will be lost. Secondly, if we have other USB devices plugged in the device file path may change. Thankfully, one UDEV rule can fix both of these issues. The below commands will create a UDEV rule that sets the proper permissions and creates a uniquely named device file at /dev/rover-zero.

# Creates the UDEV rule at /etc/udev/rules.d/rover-zero.rules
$ sudo sh -c "echo 'KERNEL==\"ttyACM[0-9]\", ATTRS{idVendor}==\"03eb\", ATTRS{idProduct}==\"2404\", MODE:=\"0666\", SYMLINK+=\"rover-zero\"
' > /etc/udev/rules.d/rover-zero.rules"

# This will cause your computer to start using the new rule
$ sudo udevadm control --reload-rules && sudo udevadm trigger

Now use the command ls -l /dev/rover-zero , if you see the rover-zero file listed then you know that your UDEV rule is working properly.

Running Example Code

Now that everything is installed lets try get the rover wheels spinning. The first thing you will want to do is to put the Rover Zero on a box so that the wheels are not touching the ground. Second, plug in your Rover Zero into your computer you will be running ROS from. Once you have done these two things you are ready to move onto using ROS to drive the Rover.

Open a new terminal on your work machine, navigate to your Rover Zero workspace, and source your workspace if you have not done so in your .bashrc file, and launch the Rover Zero node.

$ cd ~/zero_ws
$ source /devel/setup.bash
$ roslaunch rr_rover_zero_driver example.launch

If the node does not launch properly make sure that you followed the instructions in the "Setting Up UDEV Rules" section. Now open a second terminal and navigate to your workspace again. This time we are going to be sending twist commands to drive the robot.

# Forward at 0.3 meters per second
$ rostopic pub -r 1 /cmd_vel geometry_msgs/Twist '{linear: {x: 0.3, y: 0.0, z: 0.0}, angular: {x: 0.0,y: 0.0,z: 0.0}}'
# Stop the robot
$ rostopic pub -r 1 /cmd_vel geometry_msgs/Twist '{linear: {x: 0.0, y: 0.0, z: 0.0}, angular: {x: 0.0,y: 0.0,z: 0.0}}'

The first command publishes a ROS Twist message to the topic /cmd_vel with a forward speed of 0.3 meters per second. The Rover Zero driver node listens for velocity commands on the /cmd_vel topic, and then translates them into motor commands for the motor controllers. You should see the wheels start to spin forward. The second command tells the motors to move at speed zero, stopping the Rover. If you are able to start and stop the Rover with these commands you know that your Rover is entirely set up and ready to start developing on. We wish you the best of luck, and can not wait to see what you accomplish with your Rover Zero!