UBC Snowbots Repository for the 2017 Intelligent Ground Vehicle Competition.

• Installation and Setup
  • Important Notes
  • Zed Configuration
  • Catkin Migration
• Conventions
  • Github
  • Coding Conventions
  • Coordinate Systems
• Creating a New Node
• Creating a New Simple Node
• Launch Files
• Testing
  • GTest
  • Rostest
• Simulating with Gazebo
• Arduino Development
• Debugging Tips

You will be downloading an Ubuntu ISO and multiple ROS packages with their respective dependencies. It is highly recommended that you have access to high speed internet while doing this entire setup; if you're on campus use the ubcsecure or resnet networks for best results.

1. Install Ubuntu 16.04 (Backup your important data first) (We recommend you use a minimum of 30GB of space)
   • For dual-booting: Windows Instructions, Mac Instructions
   • Note: You should always choose the "install alongside Windows/OSX" during your installation (step 7 in the windows tutorial)
2. If you haven't done so already, setup your UBC alumni email account here
3. Using your UBC email account, get a JetBrains education account here
   • JetBrains will send an initial email to confirm the UBC email you inputted, once you've confirmed another email will be sent to activate your new education account; you will use this account to set up CLion later on
4. Boot into Ubuntu for the remaining steps
5. Install git by running sudo apt-get install git
6. Clone this repository by running git clone --recursive https://github.com/UBC-Snowbots/IGVC-2017.git ~/IGVC-2017
7. To start set-up run cd ~/IGVC-2017 && ./get_started.sh (Do not run this script as root)
   • Just choose yes and enter your password when the terminal prompts you
8. Build the ROS project by running source /opt/ros/kinetic/setup.bash and cd ~/IGVC-2017 && catkin_make
   • If everything compiles correctly and you don't get any errors, then you're good to go!

• To run CLion with ROS, you must first go in to terminal, navigate to your project (cd ~/IGVC-2017), run source devel/setup.sh and then from the same terminal run clion
• CLion will not support auto-completion in your .cpp and .h files until you've added them to the CMake file

• Follow the instructions on this github page (this package already contains zed_ros_wrapper as a submodule in src/zed_ros_wrapper)
• Download ZED calibration file from the link indicated when you run zed.launch and place it in the folder /usr/local/zed/settings/

• We follow the "Feature Branch Workflow"
• Only commit files that are essential for the system to run; do not put any photos or videos in here

• Every .cpp and .h file should start with

/*
 * Created By: Someone
 * Created On: December 1st, 2000
 * Description: A quick description of what this file does/is for
 */

• Functions should be commented a la JavaDoc
• The Javadoc comment (below) should be directly above every function in the header file

/**
 * One line description of the function
 *
 * A longer and more in depth description of the function
 * if it is needed.
 * 
 * @param param_one the first parameter of the function
 * @param param_two the second parameter of the function whose
 *                  description goes longer than one line
 * @return what the function returns if it returns anything
 * 
 */

• Classes are CamelCase
• Variables are non_camel_case
• Constants are ALL_CAPS_WITH_UNDERSCORES
• Functions are camelCase
• Indentations are 4 spaces

• We try to follow ROS standards, which can be found here
• x : forward
• y : left
• z : up

              +X
              ^
              |
      +θ  +<----->+ -θ
          |   |   |
          V   |   V
+Y <---------------------> -Y
              |
              |
              |
              V
              -X

• If your node is at all complicated, then this format should be followed. For simple nodes, please see below
• Each node should be class based
• MyNode.h should contain your class declaration
• MyNode.cpp should contain your class definition
• my_node.cpp should be relatively small, and should just contain a main function to run your node
• my-node-test.cpp should contain all your gtest (unit test)
• my_node_rostest.cpp should contain your rostest (integrated test)
• For an example of this, please see src/sample_package

some_ros_package
|  CMakeLists.txt
|  package.xml
└───src
|   | MyNode.cpp 
|   | my_node.cpp
|
└───launch
|   | my_node.launch
|
└───include
|   | MyNode.h
| 
└───test
|   | my-node-test.cpp
|   | my_node_rostest.cpp
|   | sample_package_test.test

• You will not be able to write unit tests for this type of node, so it must be extremely simple
• my_node.cpp will contain the entire node, and will probably contain a while(ros::ok()){} loop

some_ros_package
|  CMakeLists.txt
|  package.xml
└───src
|   | my_node.cpp

• A launch file (ends in .launch) is an easy way to run multiple nodes with specified parameters with one single command. This is useful if a package has multiple nodes that needs to be run. A launch file can also launch other smaller launch files so it can be used to start every node needed for the robot to run properly. Reference here.
• To use the launch file, the command is: roslaunch package_name package_launch_file.launch

• GTest is our primary testing tool at the moment. The ROS wiki has a quick intro to it here, and we also strongly recommend you read Google's introduction to it [here] (https://github.com/google/googletest/blob/master/googletest/docs/Primer.md), then setup and write a few example tests before you start using it with ROS.
• Once you've setup your tests in ROS, run catkin_make run_tests to run them
• To test a specific package, run catkin_make run_tests_MY_PACKAGE_NAME

• For tests which require more than one active node, i.e. integrated testing, the rostest framework provides a way to launch your test alongside all the nodes it requires. This is an extension on roslaunch enabling it to run test nodes. Special test nodes are nested within a <test></test> tag. This also needs a special entry under CMakelists as shown in the sample package. See more details here
• Similar to launch files, the command is: rostest package_name package_test_file.test.

• You will always need to source the project before running gazebo, by moving to the project directory with cd ~/IGVC-2017 and then source devel/setup.sh
• You will probably need a computer with an dedicated gpu, as gazebo sometimes works with intel integrated graphics, but generally not. If you do end up using a computer without a dedicated gpu, make sure to go in to sb_gazebo/urdf/**ROBOT_NAME**.gazebo and switch around the lidar settings (see comments in said file)
• All worlds should go in the sb_gazebo/worlds folder
• To launch a world, simply run the appropriate launch file in sb_gazebo/launch
• Once the world has launched, it is common for the robot to be initially unable to move. Just lift it up a bit in gazebo and drop it for this to be fixed
• You can manually control the robot with your keyboard, logitech, ps3, or xbox controller. To do so, simply cd ~/IGVC-2017 and then source devel/setup.sh, then run the appriate launchfile from src/sb_gazebo/launch by running roslaunch LAUNCH_FILE.launch (from within the launch folder). Note: At least with PS3 controllers, you have to hold down L1 while using the joystick for the controller to work

• When developing the firmware/Arduino parts of the software, we've made a complete arduino workspace in src/firmware. This way you don't need to worry about downloading the libraries yourself!
• In order to use this, go to your Arduino IDE's Preferences dialog box and use /your/path/to/IGVC-2017/src/firmware as your sketchbook directory. Open arduino sketches in the workspace and they will work!

• If something is happening that does not seem to correspond to your code, (ex. if your node is subscribing to the totally wrong topic) try deleting the build and devel folders (if present) to remove any "cached" information