Manual Installation

The installation script automates the steps described below. It is recommended that you follow the manual installation steps described below the first time you are installing the asclinic-system on a computer.

Note

The installation steps on this page should work for any of the following:

  • Installation on the single board computer single board computer that is onboard the robot.

  • Installation on a partition of a laptop or desktop computer.

  • Installation on a virtual machine.

Note that when peripherals such as GPIO and I2C pins are not accessible on a laptop, then those installation steps still work and should be performed,

Contents of this page

Fresh install of Operating System

Follow the instructions for flashing an SD card with the Ubuntu operating system for the single board computer you are using:

  • Nvidia Jetson models: follow the links on the Jetpack SDK page for your respective Jetson model.

  • Raspberry Pi: follow the links on the Install Ubuntu on a Raspberry Pi page for your respective Raspberry Pi model.

  • Laptop or Virtual machine: download the appropriate version of Ubuntu from the Download Ubuntu Desktop page and use installation instructions appropriate for your physical machine or virtual machine software. * Virtual Box is a freely available virtual machine software option that runs on Windows, Linux, and macOS.

Important

It is recommended that you install the version of Ubuntu that is officially supported for the version of ROS:

  • For ROS1 Noetic -> Install Ubuntu 20.04 (for Nvidia Jetson install Jetpack 5.X).

Respond to broadcast pings

Taken from this broadcast icmp in linux post

This makes it significantly easier to discover the IP address of the SBC when it is connected to a network, especially so if the a dynamic IP address configuration is used.

Open the /etc/sysctl.conf file for editing:

sudo nano /etc/sysctl.conf

Add the following lines at the end of the sysctl.conf file:

net.ipv4.icmp_echo_ignore_all=0
net.ipv4.icmp_echo_ignore_broadcasts=0

To make the change take effect, enter the command:

sysctl -p

Then, enter the following command to check the “ignore broadcast” status:

less /proc/sys/net/ipv4/icmp/echo_ignore_broadcasts

If the output is 1 then broadcast pings are ignored, otherwise, if the output 0 then broadcast pings will be responded to.

To again ignore broadcast pings, simply remove the above changes made to the sysctl.conf file and then enter the sysctl -p command.

Install mosh

Mosh, which stands for mobile shell, is an alternative to ssh (which stands for secure shell). As described on the mosh website, mosh is a “remote terminal application that allows roaming and supports intermittent connectivity”. Hence mosh can avoid the annoyance of broken ssh pipelines in those areas of your campus with patchy WiFi connection.

Install mosh:

sudo apt install mosh

Install I2C library

Install the libi2c-dev and i2c-tools libraries:

sudo apt install libi2c-dev i2c-tools

Afterwards, to test the successful installation, execute the following command in a terminal:

sudo i2cdetect -y -r 1

Note: for the i2cdetect command, the 1 argument indicate the I2C bus.

To allow the gpiod library to be used without requiring root priviliges, add the user you are logged in with to the i2c group (and any other users that need such access):

sudo usermod -a -G i2c $(whoami)

where $(whoami) simply provides the username of the user that is currently logged in.

Install GPIO library

Install the gpiod, libgpiod-dev, and libgpiod-doc libraries:

sudo apt install gpiod libgpiod-dev libgpiod-doc

Afterwards, to test the successful installation, execute the following command in a terminal:

sudo gpiodetect

To allow the gpiod library to be used without requiring root privileges, we now add a udev rule to give the user access to a particular gpio chip.

Creating a new user group names gpiod:

sudo groupadd gpiod

Now add a udev rule to give the gpiod group access to gpiochip0. Create the following file with you preferred editor, for example:

sudo vi /etc/udev/rules.d/60-gpiod.rules

Add the following comments and rule to the file just opened:

# udev rules for giving gpio port access to the gpiod group
# This allows use of certain libgpiod functions without sudo
SUBSYSTEM==\"gpio\", KERNEL==\"gpiochip0\", GROUP=\"gpiod\", MODE=\"0660\"

The first two lines are comments for a reminder for when you look back at this file in the (distant) future. The third line specifies that any members of the gpiod group are allowed to access the gpiochip0 kernel that is part of the gpio subsystem.

Add the user you are logged in with to the gpiod group (and any other users that need such access):

sudo usermod -a -G gpiod $(whoami)

where $(whoami) simply provides the username of the user that is currently logged in.

Important

New udev rules only comes into effect after a restart of the computer, after which you can check that the rule is working correctly by using the following command:

gpioinfo gpiochip0

The following commands may be useful to check various details about the groups.

  • List of all groups that the $(whoami) user currently belongs to:

    groups $(whoami)

  • List of all the members of a particular group, for example the sudo group:

    getent group sudo

  • Look at the file that list all groups and their members:

    less /etc/group

Install ROS

Follow the ROS installation instructions recommended for the version of Ubuntu installed in the step above.

Note

Ensure the you complete the step to initialize rosdep.

Clone the asclinic-system repository

Clone the asclinic-system repository into the desired location on your computer, the recommended location is ~, hence clone with the following commands:

cd ~
git clone https://gitlab.unimelb.edu.au/asclinic/asclinic-system.git

Compile the ASClinic ROS package

To compile the ASClinic ROS Package, first change directory to the catkin_ws directory, where ws stands for workspace:

cd ~/asclinic-system/catkin_ws

Then build the asclinic ROS Package using the catkin_make command:

catkin_make

Add ROS setup scripts to bashrc

Add the following source commands to the bottom of the file ~/.bashrc (replace <ros version name> and <catkin workspace> accordingly)

source /opt/ros/<ros version name>/setup.bash
source <catkin workspace>/devel/setup.bash

If you followed the steps Install ROS and Clone the asclinic-system repository above, then:

  • <ros version name> should be noetic

  • <catkin workspace> should be ~/asclinic-system/catkin_ws

Note

The catkin workspace setup.bash script will only appear after the first catkin_make compilation of the catkin workspace.

Install the Slamtec RPLidar ROS package

These instructions are based on the information provided by the git repository for the Slamtec RPLidar ROS package.

Clone the RPLidar ROS package into the catkin_ws/src/ directory of your asclinic-system git repository:

cd ~/asclinic-system/catkin_ws/src/
git clone https://github.com/Slamtec/rplidar_ros.git

Remove to the .git directory that is created as part of cloning in order to avoid having this RPLidar git repository nested inside your git repository.

rm -rf rplidar_ros/.git/

Note

Removing the .git directory means that you can no longer pull updates that Slamtec makes to the rplidar_ros repository. Instead you would need to remove the whole rplidar_ros directory and clone the repository again.

Install the Video for Linux (v4l) utilities

The settings of a USB camera can be adjusted using the command line interface program v4l2-ctl, which stands for video for linux controls. This program is installed as part of the following package:

sudo apt install v4l-utils

The following are additional video for linux tools that can come in handy:

sudo apt install libv4l-dev
sudo apt install qv4l2
sudo apt install uvcdynctrl

OpenCV Installation for Python3

In order to use OpenCV and the contributed libraries for ArUco marker detection via Python3, the package opencv-contrib-python needs to be installed, which is achieved with the following steps.

Install pip3

Install the python3 package manager pip3 using the following:

sudo apt install python3-pip

Note

You can list the installed packages that are managed by pip3 with the following command:

pip3 list

To see all the commands and option for pip3, display the help information in the usual fashion:

pip3 --help

You can display the pip version, package location, and Python version it relies on, with the following command:

pip3 --version

Upgrade pip3

Ensure that pip3 is upgraded to the latest version with the following command:

sudo pip3 install --upgrade pip

Upgrade also the setuptools and wheel packages to avoid some subsequent installation errors that may occur:

sudo pip3 install --upgrade setuptools wheel

Upgrade numpy

The OpenCV contributions package relies on the numpy package and requires a certain minimum version, hence upgrade to the latest version of numpy with the following command:

sudo pip3 install --upgrade numpy

Install OpenCV Contributions for python

Install the

sudo pip3 install opencv-contrib-python

Updates to the opencv-contrib-python can cause warnings and/or errors to be display during the installation. Pay attention to these warnings/errors and action accordingly to upgrade/ammend the packages mentioned in the warnings/errors.

Important

The dangers of using sudo pip3 install!!

A quick google uncovers many blog post about:

  • Avoiding using sudo with pip3 install, because it gives root privileges to potentially malicious pip installation scripts.

  • Versus using pip3 install --user withOUT sudo, meaning that the package is installed only for the user running the command, i.e., it is installed in ~/local/lib/python/ and you need to add this directory to your PATH environment variable so that the installed package is available to execute.

The instructions above use sudo to install the opencv-contrib-python packages because we trust developer and distributor of the package (though even a trusted source can be hacked), and it saves some extra configuration steps.

If you are performing this installation on a computer where you wish to avoid the sudo pip3 install risks, then the following should work:

pip3 install --user opencv-contrib-python
echo "" >> ~/.bashrc
echo "# Add my local python directory to the PATH environment variable" >> ~/.bashrc
echo "export PATH=$PATH:~/.local/lib/python" >> ~/.bashrc
source ~/.bashrc
echo $PATH

The more formal option it to use virtualenv, for which there are plenty of good tutorials online.

Install ROS packages for running python3 scripts

Important

This step is only required if you are running ROS with Ubuntu 18.04 or earlier, for example, ROS Melodic on Ubuntu 18.04.

Otherwise, you do NOT need to perform this step.

In order to run python3 node in ROS, run the following installation commands in order:

sudo apt install python3-pip python3-yaml

pip3 install --user rospkg catkin_pkg

You can now run a python node in ROS as python3, simply adjust the very first line of the script to the following:

#!/usr/bin/env python3

Extra steps for some camera use cases

After following the installation steps in the sections above, you should be able to run a python3 ROS node the call OpenCV and ArUco functions. However, certain errors may still occur when calling certain functions. As always with programming, read the details of the error and attempt to determine whether a package is missing that needs to be installed.

For example, the OpenCV function imshow() may need the following package to be installed:

sudo apt install libcanberra-gtk0 libcanberra-gtk-module

Creative Commons License
Paul N. Beuchat, 2023
This page is licensed under a Creative Commons Attribution 4.0 International License.