This repo contains the final project for SWENG-452W. I created a Remote Controlled (RC) car running on a Raspberry Pi 4 that can be controlled via a Ground Control Station (GCS) on another computer/Virtual Machine. The Robot Operating System (ROS) was selected as the main tool for interacting with the hardware - due to it being the industry standard.
There are two operating modes for this project/software: Simulation-Mode (sim-mode) and Real-Hardware-Mode (real-mode). This README will cover and provide resources on how to set-up and run both operations modes and how to operate the GCS.
The sim-mode allows for development and testing of the remote control system without having to mount the software to actual hardware. This allowed me to save time and money in final projects development cycle. Currently the project uses Gazebo as the simulator of choice and Windows System for Linux 2 (WSL2) to run ROS and Gazebo for simulator operations. This section will cover how to set-up a simulator environment and the GCS.
WSL2 was chosen over a standard virtual machine for its GPU pass-through which is built into the platform. This allows you to use any Linux application with a Graphical User Interface (GUI) natively on Windows. Additionally, it allowed me connect, develop and cross-compile with Visual Studio Code on my Windows host machine. WSL2 running Ubuntu 20 will be installed.
Open PowerShell in admin mode. This can be done by searching for powershell
in the Windows search bar. Next, right click the search result and select Run as administrator
.
Next type the text below into the powershell to install base WSL2 onto your computer.
wsl --install
Now the basic WSL2 framework has been installed, now let's install a Ubuntu-20 instance.
In the Windows search bar, type windows store
. In the Windows store search for Ubuntu 20
and select Ubuntu 20.04.6 LTS
- then install it.
Open WSL2 and in your new WSL2-Ubuntu 20 environment, you will find your WSL2 ip address by using this command:
ip addr | grep eth0
After entering this command, you should see this: Copy down the IP address underlined, this will be the IP address you will input into the GCS (GCS will send commands to this IP address) and for the next step in the network configuration.
For WSL2 to receive the command messages from the GCS You must create a Port Forwarding address for WSL2. Open your powershell
and enter this command to create a permanent port forwarding.
netsh interface portproxy add v4tov4 listenport=3390 listenaddress=0.0.0.0 connectport=3390 connectaddress=<INSERT_WSL2_IP_ADDRESS_HERE>
Input the WSL2 IP from the previous sub-section in the connectaddress
portion in the code provided above. Your port forwarding address will be 3390 (you can choose whatever port you like).
If you receive a Windows firewall error, create a Inbound Rule
for your WSL2 port. First go to Settings
--> Network & Internet
--> Advanced Settings
.
In the firewall program, select Inbound Rules
and select New Rule..
.
Follow these settings for the New Inbound Rule Wizard
:
- Rule Type: Port
- Protocol and Ports: TCP and specific local ports: 3390 (Or whatever port you have chosen)
- Action: Allow for connection
- Profile: Make sure all boxes (Domain, Private) are checked
- Name: Anything you wish
For this section, you can install ROS in you new WSL2-Ubuntu 20 environment using two methods.
The installation bash script in the main portion of this repo will automate the installation of ROS, workspace creation and install the ROS project/packages. It's recommended to manually install the first time, so you can understand the process. If you run this script installROS.sh
, there is no need to do the following sub-sections. Use the command below in the main directory (assuming you git cloned the directory into WSL2).
./installROS
The manual sub-section is in two parts, installing ROS, setting up ROS workspace, and installing the final project. These steps can be done in the WSL2-Ubuntu 20 environment (sim-mode) or if attached to real hardware - on the Raspberry Pi (real-mode).
Here are the instructions for ROS installation - follow this link, for further information Ubuntu install of ROS Noetic.
Setup ROS sources list
sudo sh -c 'echo "deb https://packages.ros.org/ros/ubuntu $(lsb_release -sc) main"
> /etc/apt/sources.list.d/ros-latest.list'
Install Curl for keys download
sudo apt install curl -y
Install GIT so you can download the final project from GitHub on WSL2/Raspberry Pi
sudo apt install git -y
If you're installing on a Raspberry Pi, install Python-is-Python3 with this command.
sudo apt install python-is-python3 -y
Update Keys
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
Update you system
sudo apt update
Install ROS version: Noetic
sudo apt install ros-noetic-desktop-full -y
Add the ROS workspace sourcing to your bashrc, Will automatically start ROS on terminal start-up.
echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc
Source (restart) your bash environment to start ROS. This will happen automatically in the future.
source ~/.bashrc
Install Python dependencies
sudo apt install python3-rosdep python3-rosinstall python3-rosinstall-generator python3-wstool build-essential -y
Start the Python ROS-Dep environment
sudo rosdep init
Update ROS-Dep
rosdep update
In this sub-section, we will create a ROS workspace to develop ROS programs, packages and projects. In you home directory in WSL2, run this command to create the directories.
mkdir -p ~/catkin_ws/src
Next, we will initialize the ROS workspace.
cd ~/catkin_ws/src
catkin_init_workspace
Now go back to the main work directory and do the initial make in the ROS workspace.
cd ../
catkin_make
In this sub-section we will set up and install the SWENG-452W final project. In your environment (WSL2 and/or Raspberry Pi) go into you new ROS workspace Now lets git clone the final project into the ROS workspace
cd ~/catkin_ws/src
Now GIT clone the repo into you source code section.
git clone https://github.com/carte731/sweng452w-fp.git
Now initialize the sub-module git repos (This step is not necessary if you're not running on real hardware - i.e. moving a real RC car/robot).
cd sweng452w-fp
git submodule init
Next, we will download the simulator repos (This step is not necessary if you're not running on real hardware i.e. moving a real RC car/robot).
git submodule update --recursive
After going back to the main ROS workspace. We will download all the required project dependencies using this command.
cd ~/catkin/
rosdep install --from-paths src/ -y
Next install the hardware drivers (This step is not necessary if you're not running on real hardware i.e. moving a real RC car/robot).
cd ~/catkin/src/sweng452w-fp/real_mode/Driver_installer
sudo python3 setup.py install
Finally, make your ROS workspace
cd ~/catkin/
catkin_make
For real-mode, the user will have to set up both the Raspberry-Pi 4 and the hardware.
You will need a Raspberry Pi 4 and an microSD card and a means to mount it to computer (to install an OS to the SD card).
In this section you will be installing Ubuntu-20 Server using the Raspberry Pi Imager. There is no GUI by default for the server versions of Ubuntu. Everything must be done through a terminal or a remote IDE like Visual Studio Code.
Download and install the Raspberry Pi Imager.
Insert the SD card into PC for imaging (installing an OS on the microSD card). There are three sections that must be fill out, enter these settings:
- Raspberry Pi Device: Raspberry Pi 4
- Operating Systems: scroll down and select
Other general-purpose OS
, SelectUbuntu
and then scroll down and select:Ubuntu Server 20.04.5 LTS (64-bit)
. - Storage: Select your MicroSD card.
IMPORTANT: AFTER SELECTING NEXT
- SELECT EDIT SETTINGS
AND APPLY YOUR NETWORK SETTINGS AND ENABLE SSH.
IMPORTANT: FOR THE GENERAL TAB - ENTER YOUR NETWORK INFORMATION, DON'T COPY WHAT IS PRESENTED IN THE EXAMPLE IMAGE
IMPORTANT: FOR THE SSH TAB - APPLY THE SAME SETTINGS
THIS IS IMPORTANT, BECAUSE YOU WILL BE ABLE TO SSH DIRECTLY INTO THE UBUNTU-20 SERVER AND WON'T HAVE TO MANUALLY CONFIGURE NETWORK SCRIPTS TO CONNECT TO WIFI (IT'S A PAIN TO DO THIS).
Open your powershell (ensure you have openssh installed) and enter:
ssh [username]@[hostname].local
The username
and hostname
come from what you selected in the OS set-up using the imager in the last sub-section.
If this doesn't work, you will have to manually attach a monitor to the Raspberry Pi 4 to collect your IP address (Directions below) and then use this command:
ssh [username]@[IP address]
Find your IP address in the Pi using the commands mention in earlier sub-sections. This address is important, this is what you will send commands to (from the GCS) and how you will SSH into the device normally.
For this project, I used YahBoom for my robot car chassis. They provide an assortment of chassis, boards and accessories for robotics design and development.
I chose the Yahboom Aluminum Alloy ROS Robot Car Chassis. It's a basic chassis, with just wheels, motors and a mounting frame - the final project I created provides the drive control, so the more complex platforms were not needed. Here's a tutorial showing how to assemble the chassis: 4WD chassis Installation Video
The control board interfaces with the hardware and allows communication with the hardware through a centralized system. I chose the YahBoom ROS Robot Control Board - my program interfaces with the board to send drive commands to the hardware.
The Installation video provided above will show you have to assemble the chassis. The ROS installation sub-section above will install the hardware controller drivers.
For further details, please read the material below:
This sub-section is critical for the Raspberry Pi to recognize the ROS Control Board - a new serial port rule must be made (Note: This section won't work for later Ubuntu distributions (Greater than 20 LTS) - you first have to unblock the usage of tinyUSB).
After connecting the ROS board to the Raspberry Pi via a USB-C port - open a terminal and type:
lsusb
there should be a list of connected devices, look for this device:
ID 1a86:7523 QinHeng Electronics HL-340 USB-Serial adapter
If it's present, the devices are connected properly. Now lets add a binding rule - so the device can be auto-mounted correctly. Let's create a new rule by editing the rule file using this command:
sudo nano /etc/udev/rules.d/myserial.rules
Copy and paste this command into the file:
KERNEL=="ttyUSB*", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", MODE:="0777", SYMLINK+="myserial"
Save and close the file. Now we will open the permissions on the file:
sudo chmod a+x /etc/udev/rules.d/myserial.rules
Now lets restart the serial port manage using these commands:
sudo udevadm trigger
sudo service udev reload
sudo service udev restart
Finally, check to ensure the ROS board has mounted correctly:
ll /dev/myserial
If you see the ROS Board attached to a tinyUSB port, congrats the ROS board is now attached to the serial port and can now receive commands from the Raspberry Pi. For more installation information, read through the YahBoom ROS Board manual.
It is helpful to connect Visual Studio code to either the Raspberry-Pi (Real-Mode) and to WSL2 (Sim-Mode) to update config files or to experiment with the program and settings. It makes cross system development, cross-compiling a lot easier.
Follow these links to learn how:
The GCS send commands to the RC car/robot from another computer or VM running Linux (Generally Ubuntu 20, but should be able to run on any OS. Other OS's haven't been tested). It runs off a GUI, that requires QT Creator to run. The GCS runs off of Qt Creator 4.5.2 (later versions have not been tested).
In a VM environment of your choice create or use a Ubuntu/Linux environment. Change the network type to bridged
for that VM - this allows the VM and the host machine to share an IIP address/connection.
Next, install QT-Creator 4.5.2 using these commands
sudo apt install qtcreator
sudo apt install qt5-default
Start the QT-Creator in the VM and GIT clone the project into a directory. Next, open a terminal in the VM that will run the GCS QT files located in sweng452w/GCS/GCS
in the repo directory. Press the play button in the bottom left corner of the window. A panel displayed in the section header should appear.
This also compiles the program, a file named GCS
will appear in the build directory. This is your executable and can run directly or through QT Creator IDE.
Next we will retrieve the VM IP. Write the IP address down - so that the RC car/robot can send telemetry and confirmation data back to the GCS. As with WSL2 - open a terminal and type in this command:
ip addr | grep enp
Copy down the VM's IP address - this is what you will input into the RC cars config file for sim and real modes.
Here is a break-down of main panel of the GCS:
- UP: Moves the RC car forwards.
- DOWN: Moves the RC car backwards.
- QUIT: Forces the RC car to stop operations - have to restart system afterwards.
- Queue Mode Start: As commands are entered or inputted via a
command execution file
, they will be loaded into a queue located to the right. Once this button is press, the program will execute each task in order and remove them front the queue. - Real-Time Mode: As buttons are pressed, they are immediately sent out to the RC car/robot.
- Network Config: This allows the user to set the IP address and port of either the WSL2 environment running the simulator or the actual RC car/robot hardware. Additionally, it can set the port number for the GCS (so the GCS can receive telemetry and heartbeats from the RC car/robot).
- Open CMD file: A CMD file (extension must be .CEF) contains commands to be sent to the RC car/robot. Commands that are accepted are UP, DOWN and QUIT. All other commands are ignored by the RC system. Real-Time mode, the commands are read automatically - for Queue-Mode, the
Queue Mode Start
button has to be pressed. A sample of a .CEF file in located in the main GCS directory
- Command Execution Queue: Shows either the commands in the queue - the order of execution in Queue-Mode. Or the current command being executed int Real-Time Mode.
- Telemetry/Status: Shows the GCS status messages and shows any inbound data from the RC car/robot.
For both modes, the GCS needs to be started first.
Open both you WSL2 and Ubuntu VM.
Start QT-Creator and press the play button or run the executable file (generated by QT-Creator) named GCS in the build directory. Select File-->Network Config
and enter the RC car/robot IP address (from WSL2). Additionally, choose a port for the GCS (default is 9000).
Select mount to save inputs, the server should restart and the GCS is ready.
In the main directory there are two files: config.sh
and RCStart.sh
. Config file must be set with correct IP and Port addresses for the VM running the GCS and the GCS Port.
In the main directory open the config.sh
file and input the GCS (VM) IP address and the port you selected in the last sub-section: GCS Start-Up. The RC port must match the port created in the WSL2 port forwarding section
Run the command below to start sim mode, put nothing in the input parameter for a help print out message.
./RCStart.sh sim
A simulator window should open running Gazebo with a robot, input commands to move the RC car/robot.
The instructions are the same as with sim mode - the only difference being:
- SSH into the Raspberry-Pi and to set-up config settings.
- Use this command to start Real-Mode on the RC-car:
./RCStart real
- Set up is the same as with Sim-Mode. Run the GCS first.