Setup

TL,DR: Run the venv and compilation setups. If you want to run arm and wheels controls, or use the Aruco node, there are additional steps. Then compile with colcon build --symlink-install --packages-skip usb_cam. Now, you can run a launch file. For instance, to run the simulation of IK, run ros2 launch arm_ik local_ik.launch.py. NOTE: VS Code’s integrated terminal causes issues with RVIZ, so I recommend you use a traditional terminal emulator (Terminator or Terminal).

Setup venv

We highly recommend you setup a Python venv. Run python3 -m venv ./space-env from the robotics-prototype folder. This will create a python venv in the space-env folder. To make it always run on startup, run the following command to add it to your bashrc: echo "source ${PWD}/space-env/bin/activate" >> ~/.bashrc

Setup to compile repo

The code in this repo was built around ROS Humble. First install that. Then, from this folder (robotics-prototype):

• Install rosdep, colcon, catkin, and pip (if not already) (sudo apt install python3-colcon-common-extensions python3-pip python3-rosdep2)
• Init rosdep (sudo rosdep init). An error of the form ERROR: default sources list file already exists: is expected, if you’ve already installed rosdep.
• Go in the rospackages folder: cd robot/rospackages
• Update rosdep and install rosdep update && rosdep install --from-paths src --ignore-src -r -y. Enter your password when prompted.
• Run rosdep so it installs packages:- Install misc python deps (pip install -r ../../requirements.txt)
• Install JetsonGPIO from GitHub. This must be manually installed. The default options will work.
• Build: colcon build --symlink-install --packages-skip usb_cam (usb_cam can only compile on the Jetson).
• Source this ros2 package by adding a command to your bashrc. You can do that by running this command: echo "source ${PWD}/install/local_setup.bash" >> ~/.bashrc
• Restart your terminal so the above command runs and you can have access to the ros2 workspace.

Running arm and wheels controls

First, run sudo ./scripts/configure-can0.sh and sudo ./scripts/configure-arm.sh. The error message “chmod: cannot access ‘/dev/ttyUSB1’: No such file or directory” is normal. Then, run ros2 launch robot/rospackages/launch/robot_ik.py. NOTE: you will likely need to unplug and re-plug in the USB-Serial adapter for the absolute encoders.

Then, on another computer, run ros2 run joy joy_node that is on the same network as the rover, and with a Logitech X3D joystick plugged in (allowing a wider range of input methods is in progress).

Setting up ros2_aruco

Short version

Run these commands:

• pip install transforms3d
• Find where your python packages are installed (eg run the above command again) and source it in ~/.bashrc. This line should look like the following: export PYTHONPATH="~/Programming/robotics-prototype/space-env/lib/python3.10/site-packages:$PYTHONPATH"
• If need to duplicate video: sudo apt install ffmpeg v4l2loopback-dkms v4l2loopback-utils v4l-utils

Long version

To get this working, you may see the following error:

Installing the transforms3d library by hand required. Please run
        sudo pip3 install transforms3d

Run this command (in my case without the sudo and with pip) and it should work. Adding to PYTHONPATH is likely necessary. You will add a command like the following to ~/.bashrc: export PYTHONPATH="/home/marc/Programming/robotics-prototype/space-env/lib/python3.10/site-packages:$PYTHONPATH"

Another thing to consider is that while python3-opencv (installed with apt, from rosdep) works with this package, it also works with opencv-python (installed through pip). There is a version difference, which is why there are lines such as if cv2.__version__ < "4.7.0": in the source.

In addition, to allow the camera used for aruco detection to also be streamed, v4l2loopback must be configured and ffmpeg must be present. Install the following: v4l2loopback-dkms, v4l2loopback-utils, v4l-utils, and ffmpeg.

If you have secure boot enabled, there will be additional setup involved (requiring a reboot). These packages might be added to package.xml at some point, but it will need to be added to rosdep, which takes a little while.

To allow simultaneous streaming on another process, set the camera_index and camera_destination_index params in the launch file. They correspond to which index in /dev/video to use. If camera_destination_index is set (to a value which is not -1), it will (attempt) to stream the camera from the source to the destination location (in /dev/video). Now, any other process can load the camera from the destination index.

Programming Guidelines

General Guidelines

Why do we even need guidelines in the first place?

At the beginning, Space Concordia Robotics was small. The code base was maintained by two individuals that knew the code very well. The robotics team is now growing with new members of a wide range of programming experience. Due to the negligence of the best practices, the code became spaghetti and almost impossible to read for new members. It is hard to debug and to test. We need clean code because

Clean code is easier to read

Clean code is easier to debug and is more maintainable

Well designed code is scalable

Well planned code is fun to build on

There is a cost to having a total mess

Teams that have moved swiftly at the beginning of projects can find themselves moving at a much slower rate further in. The term Technical Debt describes the cost of the additional work that needs to be done (because of slower debugging, more bugs, etc) due to messy code.

Best Practices

These best practices are mostly taken from the book Clean Code, A Handbook of Agile Craftsmanship by Robert C. Martin

1. Functions

1.1 Do one thing

Functions should do one thing. They should do it well. They should do it only. This is called the Single Responsibility Principle (SRP). One symptom of doing more than one thing is having sections within functions. These can oftentimes easily be split up into subroutines that will only have a specific role. Additionally, this software engineering design principle extends to classes. Classes should have a clear purpose and not attempt to be a Swiss Army Knife.

1.2 Size

Size does matter! The size of the function should be small. We do not impose a hard limit on the number of lines of code. However, common sense should be applied. Code should be able to be read on a single monitor. It should be short enough to be able to conceptualize the logic in your head. Use common sense.

1.3 Duplication

Duplicating code is one of the primary source of hard to maintain code. Here is an example of duplicated code in the code base of robotics-prototype

void Commands::accOn(void) {
    for (i = 0; i < RobotMotor::numMotors; i++) {
        motorList[i].accLimit = true;
        String msg = "ASTRO Motor " + String(i + 1);
        msg += " Acceleration Limiter: ";
        msg += String(motorList[i].accLimit ? "Open" : "CLose");
        println(msg);
    }
}
void Commands::accOff(void) {
    for (i = 0; i < RobotMotor::numMotors; i++) {
        motorList[i].accLimit = false;
        String msg = "ASTRO Motor " + String(i + 1);
        msg += " Acceleration Limiter: ";
        msg += String(motorList[i].accLimit ? "Open" : "CLose");
        println(msg);
    }
}

Which can just be simplified to

void Commands::acc(bool hasAccelerationLimit) {
    for (i = 0; i < RobotMotor::numMotors; i++) {
        motorList[i].accLimit = hasAccLimit;
        String msg = "ASTRO Motor " + String(i + 1);
        msg += " Acceleration Limiter: ";
        msg += String(motorList[i].accLimit ? "Open" : "CLose");
        println(msg);
    }
}

What we gain by eliminating duplication is the need to change the function multiple times to make changes. If the logic above need to add another instruction, we would need to change accOn(void) and accOff(void) while now we only need to change acc(bool)

There are more changes we could do to improve this function that we will see later.

2. Coupling

Coupling is the degree of interdependence between software modules.

2.1 Modularity

Since the rover needs to be modular, we need to have very loose coupling. The software needs to have independent modules that we can quickly swap out. This is one of the many reasons we use ROS, which creates a modular foundation.

2.2 Levels of abstraction

It is a best practice to abstract the code into different layers. For example, code related to communication with ROS should not include GUI changes. Common layers are GUI, Logic, Communication.

3. Comments

Comments can be a blessing or a curse. Proper documentation can help developers while bad documentation can obstruct or mislead them.

3.1 Useless comments

Ideal code is self explanatory. Do not comment when it is obvious like

//Initialize ROS
initRos();

This adds lines for the programmers to read without adding any value.

3.2 Rotten Comments

One major issue with comments is that they rot with time. Before writing a comment, make sure that this comment will still be relevant after the code passes through a lot of changes.

3.3 Todos

Do not write any Todo comments. These get easily lost and forgotten. Open an issue instead. It is fine to create TODOs as self-reminder on a certain branch as opening an issue may not be appropriate. However, TODOs should be removed prior to opening the Pull Request.

3.4 Commented code

Avoid commenting code. A lot of the code that is commented, never gets uncommented again. It is a better practice to remove the code. We are using git as a version control tool, this means that old code can always be recuperated.

4. Meaningful Names

4.1 Variable Names

With the function that we improved above there is still a glaring issue :

void Commands::acc(bool hasAccelerationLimit) {
    for (i = 0; i < RobotMotor::numMotors; i++) {
        motorList[i].accLimit = hasAccLimit;
        String msg = "ASTRO Motor " + String(i + 1);
        msg += " Acceleration Limiter: ";
        msg += String(motorList[i].accLimit ? "Open" : "CLose");
        println(msg);
    }
}

What the heck is acc? By observing this function and it’s argument, it is obvious that it’s for Acceleration Limit. However, imagine that you were stumbling upon a call to this function like this

//some code
acc(false);
//more code

To know what acc means, you need to go to the function definition which could be tedious if you have to do this often.

void Commands::setAccelerationLimit(bool hasAccelerationLimit) {
    for (i = 0; i < RobotMotor::numMotors; i++) {
        motorList[i].accLimit = hasAccLimit;
        String msg = "ASTRO Motor " + String(i + 1);
        msg += " Acceleration Limiter: ";
        msg += String(motorList[i].accLimit ? "Open" : "CLose");
        println(msg);
    }
}

Now it is much cleaner when the call is being read.

//some code
setAccelerationLimit(false);
//more code

4.2 Magic Values

Magic values (or magic numbers) are values used with unexplained context.

An example of the usage of a magic value :

if (isPressed(input[65]))

We do not know what 65 is.

To fix this problem, we can simply defined a constant.

if (isPressed(input[A_KEY]))

Magic values should be avoided and replaced by variables or constants with names that self-describes their behavior.

Programming Specific Guidelines

Python

We use the PEP8 Style Guide. Please refer to it here

JavaScript

We follow the standard conventions, there exists an auto-formatter package in atom called atom-standard-formatter which automates this.

Furthermore, we are attempting to use a strict variant of JavaScript. We have not enabled strict mode yet, but all future code should respect the strict variant of JavaScript which can be found here

We are also using JQuery, therefore you should use JQuery for document traversal and and manipulation.

JavaScript should be organized per Jinja template.

C++

While we have not officially started using standard programming practices. Future C++ code should use the C++ core guidelines defined here

HTML

HTML code must be placed in templates using Jinja. Note that Jinja is included with Flask. Each module should have it’s own HTML to meet our modularity requirements.

CSS

CSS code should be organized per Jinja template along with JavaScript and HTML.

Display values should avoid being hardcoded (such as width for example) as they hurt the ease of responsiveness. Instead, bootstrap columns should be used to adjust width.

CSS should be regrouped together. Inline CSS should not be present.