From a5982693c7165a533defa034840e76f941578e38 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonas=20Kvarnstr=C3=B6m?= <jonas.kvarnstrom@liu.se>
Date: Sun, 11 Apr 2021 10:17:43 +0200
Subject: [PATCH] Instruction updates. Splitting OS from playbooks.
---
README.md | 18 +---
doc/install.md | 175 ---------------------------------------
doc/install_os.md | 45 ++++++++++
doc/install_playbooks.md | 121 +++++++++++++++++++++++++++
4 files changed, 169 insertions(+), 190 deletions(-)
delete mode 100644 doc/install.md
create mode 100644 doc/install_os.md
create mode 100644 doc/install_playbooks.md
diff --git a/README.md b/README.md
index 8fbaa15..cd340f5 100644
--- a/README.md
+++ b/README.md
@@ -2,23 +2,11 @@
A number of development environments have been set up, adapted to different tasks.
-## General information
+Please note that the instructions for the development environments are written for developers. They do not necessarily explain every step in detail and have not necessarily been tested on every combination of hardware, operating system, software setup and so on. You are welcome to contact us for assistance in troubleshooting problems that may arise.
-Please note that these instructions are for developers. They do not necessarily explain every step in detail and have not necessarily been tested on every combination of
-hardware, operating system, software setup and so on. You are welcome to contact us for assistance in troubleshooting problems that may arise.
+To install a development environment, follow these steps:
-## Operating Systems
-
-Unlike the *tutorials*, these development environments cannot be
-entirely encapsulated in Docker images that can be executed on a
-wider variety of operating systems. For almost all development
-purposes, you will also need a "real" or virtual Ubuntu Linux
-system, with ROS installed, for the actual development of your
-own software.
-
-Follow these installation instructions to install
-
- - [Install Software on Local Machine or Virtual Machine](doc/install.md)
+- [Ensure that you have a supported operating system](doc/install_os.md) (directly on your hardware or in a virtual machine)
The development environment then provides many additional functionalities
related to the core system, including those functionalities that are present
diff --git a/doc/install.md b/doc/install.md
deleted file mode 100644
index 48af7b8..0000000
--- a/doc/install.md
+++ /dev/null
@@ -1,175 +0,0 @@
-# Installing Linux and/or ROS
-
-Please make sure you have read the "Operating Systems" part of the [README](../README.md) first!
-
-## General information
-
-Please note that these instructions are for developers. They do not necessarily explain every step in detail and have not necessarily been tested on every combination of
-hardware, operating system, software setup and so on. You are welcome to contact us for assistance in troubleshooting problems that may arise.
-
-
-## Operating Systems and Development Environments
-
-As mentioned in the [README](../README.md), you need an installation of Ubuntu 20.04 or 18.04 LTS (Long Term Support). Other versions, such as the more recent 20.10, are not supported by ROS or by the software in the development environment. We recommend **version 20.04**, which you can install either directly on your hardware (recommended) or in a virtual machine.
-
-### Terminology
-
-- **Main Operating System**: The operating system that runs directly on your hardware.
-
-- **Development System**: A *real computer* or *virtual machine* running *Ubuntu 18.04 or 20.04*, where you intend to do software development.
-
-### Alternatives
-
-You can develop in one of the following ways:
-
-- Use Ubuntu 20.04 as the main operating system on your computer, and do not upgrade until the next long term support version is released (22.04), a new ROS version for Ubuntu 22.04 LTS is released, and a new version of the development environments. This is the main alternative for many developers as the long term support versions provide a stable development system that minimizes the risk of incompatibility.
-
-- Use another version of Linux as the main operating system (for example a newer version of Ubuntu), with Ubuntu 20.04 installed in a virtual machine. This is the best supported alternative to using Ubuntu 20.04 directly on your computer. However, there can be issues with 3D graphics, in particular when new driver versions are released. --- 3D graphics will work, but will be slower???, especially if you use Gazebo??? +++++++++++ What is the precise meaning of "not recommended if Gazebo should be used because of 3D graphics requirements"?
-
-- Install Ubuntu 20.04 in a virtual machine such as VirtualBox, running on a Windows machine. This will lead to some issues in terms of using 3D graphics, but 2D graphics will work if you install an X Windows server on the Windows machine. There are some [initial instructions](https://gitlab.liu.se/lrs/symbicloud_docker_images/-/blob/master/doc/itn.md) for this, and we will do our best to help out in case of problems, but cannot guarantee that absolutely all aspects of a development environment will work as expected.
-
-- Install Ubuntu 20.04 in a virtual machine such as VirtualBox, running on MacOS. This will lead to some issues in terms of using 3D graphics, but 2D graphics will work if you install an X Windows server. +++++ Tested/untested? +++++
-
-## Installing a Virtual Machine running Ubuntu 18.04 or 20.04
-
-*These instructions are quite terse, as there exist plenty of descriptions on the web.*
-
-If you do not run Ubuntu 20.04 (or 18.04) on your machine, you need to install a virtual machine. You may use software such as [VirtualBox](https://www.virtualbox.org/), [Parallels](https://www.parallels.com/se/) or [VMWare Player](https://www.vmware.com/se/products/workstation-player.html) for this purpose. We have mainly tested VirtualBox, as it is free.
-
-For VirtualBox:
-
-- Install VirtualBox
-- Download [installation media](https://ubuntu.com/download/desktop) for Ubuntu 20.04.x LTS
-- Start VirtualBox and create a new virtual machine
-- Install Ubuntu from the installation media that you downloaded
-- If and when Virtual box asks about the network: You want a *bridged* network.
-- You need to do the following in the *virtual* machine. One reason is that you need to build the [Guest Addition](https://www.virtualbox.org/manual/ch04.html) modules that allow the "virtual Ubuntu" to communicate with the virtual machine software more efficiently, speed up graphics, allow the use of shared folders, and so on.
-
- ```bash
- sudo apt install gcc perl make # to build guest addition kernel modules
- sudo apt install net-tools openssh-server
- ```
-
-- You also need to actually *build and install* the [Guest Additions](https://help.ubuntu.com/community/VirtualBox/GuestAdditions).
-
-## Installing Required Software on your Development System
-
-The following instructions need to be followed and executed on your *Development System*, regardless of whether this runs in a virtual machine or not.
-
-### Setting up SSH
-
-Open a terminal window (on your Development System as defined above!) and execute the following command to update the list of packages available for your system:
-```bash
-sudo apt update
-```
-
-Install the openssh package:
-```bash
-sudo apt install openssh-server
-```
-
-In the instructions below replace USER with the specific name of the user you logged in with.
-You can check what name it is by executing the following command to display the value of the USER environment variable:
-```bash
-echo $USER
-```
-
-Test if you can ssh from the development system into itself without providing the password. It is necessary for the remaining steps described below.
-```bash
-ssh USER@localhost
-```
-If you are asked to enter the password, cancel the command (Ctrl+C) and execute the following command to install the needed ssh key:
-```bash
-ssh-copy-id -i USER@localhost
-```
-If you don't have an SSH key generated on the development system yet, execute:
-```bash
-ssh-keygen
-```
-and repeat the previous step. You should now be able to login to the development system using ```ssh USER@localhost```
-
-### Installing Ansible
-
-Some of the WARA PS software is installed using [Ansible Playbooks](https://docs.ansible.com/ansible/latest/index.html).
-
-If you use Ubuntu 18.04, you first need to do the following in order to get access to a repository containing the Ansible software:
-
-```bash
-## sudo install --reinstall ca-certificates # Had to do this for the apt-add-repository to work
-sudo apt install software-properties-common
-sudo apt-add-repository --yes --update ppa:ansible/ansible
-```
-
-Regardless of Ubuntu version, continue as follows:
-
-```bash
-sudo apt install ansible
-```
-
-### Installing software using Ansible Playbooks
-
-Clone our playbooks repo to get access to the actual playbooks for WARA PS:
-
-```bash
-sudo apt install git
-git clone https://gitlab.liu.se/lrs/lrs_playbooks.git
-```
-
-Run the `wara_develop` playbook as follows to install and update the WARA PS developer software. It can take several minutes to complete.
-
-- In the command below the value of the environment variable specifying the login name is used. You don't have to replace it.
-
-- But make sure you replace the last argument with the actual password of the root/administrator on the development system.
-
-```bash
-cd lrs_playbooks
-git pull
-ansible-playbook -i hosts playbooks/wara_develop.yml -e user=${USER} -e install_user=${USER} -e ansible_sudo_pass=******
-```
-
-### Finishing Up
-
-Add the following commands at the end of the ```~/.bashrc``` file on your development system:
-```bash
-export WORLD_ORIGIN_LAT=57.7605573519
-export WORLD_ORIGIN_LON=16.6827607783
-export WORLD_ORIGIN_ELEVATION=29.8
-
-#source /opt/ros/melodic/setup.bash
-source ${HOME}/wara_ws/devel/setup.bash
-export PATH=${HOME}/lrs_devenv_common/script:${PATH}
-```
-
-Then log in and log out to the development system for the docker commands to work. Test this with:
-
-```bash
-docker ps
-```
-It should show:
-```bash
-tompe@philo:~$ docker ps
-CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
-tompe@philo:~$
-```
-
-At this point your system now has the necessary software installed.
-
-You can use the following commands on the development system to test the 3D graphics hardware and driver setup on your system:
-
-```bash
-glxgears
-glmark2
-```
-
-If the above commands execute without errors you can test that Gazebo
-works correctly on your development system:
-
-```bash
-roslaunch lrs_wara_gazebo gazebo.launch
-roslaunch lrs_wara_gazebo dji_to_gazebo.launch name:=dji0 with_laser:=true x:=5
-```
-
-All files to run these tests should be available in lrs_wara_gazebo
-which is installed in wara_ws by the Playbook above. The first command
-starts Gazebo and the second command adds a model of a DJI M100 to the
-Gazebo world.
diff --git a/doc/install_os.md b/doc/install_os.md
new file mode 100644
index 0000000..d7f7f85
--- /dev/null
+++ b/doc/install_os.md
@@ -0,0 +1,45 @@
+# Using Ubuntu LTS
+
+Unlike the *tutorials*, the development environments cannot be entirely encapsulated in Docker images that can be executed on a wider variety of operating systems. For almost all development purposes, you will also need a "real" or virtual Ubuntu Linux system, with ROS installed, for the actual development of your own software.
+
+The supported operating system versions are **Ubuntu 20.04 and 18.04 LTS** (Long Term Support). Other versions, such as the more recent 20.10, are not supported by ROS or by the software in the development environment. We recommend **version 20.04**, which you can install either directly on your hardware (recommended) or in a virtual machine.
+
+## Terminology
+
+- **Main Operating System**: The operating system that runs directly on your hardware.
+
+- **Development System**: A *real computer* or *virtual machine* running *Ubuntu 18.04 or 20.04*, where you intend to do software development.
+
+## Alternatives
+
+You can develop in one of the following ways:
+
+- **Use Ubuntu 20.04 as the main operating system** on your computer, and do not upgrade until the next long term support version is released (22.04), a new ROS version for Ubuntu 22.04 LTS is released, and a new version of the development environments. This is the main alternative for many developers as the long term support versions provide a stable development system that minimizes the risk of incompatibility.
+
+- Use **Ubuntu 20.04 in a virtual machine running on another version of Linux**, such as a newer version of Ubuntu. This is the best supported alternative to using Ubuntu 20.04 directly on your computer. However, there can be issues with 3D graphics, in particular when new driver versions are released. --- 3D graphics will work, but will be slower???, especially if you use Gazebo??? +++++++++++ What is the precise meaning of "not recommended if Gazebo should be used because of 3D graphics requirements"?
+
+- Use **Ubuntu 20.04 in a virtual machine running on a Windows machine**. This will lead to some issues in terms of using 3D graphics, but 2D graphics will work if you install an X Windows server on the Windows machine. There are some [initial instructions](https://gitlab.liu.se/lrs/symbicloud_docker_images/-/blob/master/doc/itn.md) for this, and we will do our best to help out in case of problems, but cannot guarantee that absolutely all aspects of a development environment will work as expected.
+
+- Use **Ubuntu 20.04 in a virtual machine running on MacOS**. This will lead to some issues in terms of using 3D graphics, but 2D graphics will work if you install an X Windows server. +++++ Tested/untested? +++++
+
+## Installing a Virtual Machine running Ubuntu 18.04 or 20.04
+
+*These instructions are quite terse, as there exist plenty of descriptions on the web.*
+
+As noted above, if you do not run Ubuntu 20.04 (or 18.04) on your machine, you need to install a virtual machine. You may use software such as [VirtualBox](https://www.virtualbox.org/), [Parallels](https://www.parallels.com/se/) or [VMWare Player](https://www.vmware.com/se/products/workstation-player.html) for this purpose. We have mainly tested VirtualBox, as it is free.
+
+For VirtualBox:
+
+- Install VirtualBox
+- Download [installation media](https://ubuntu.com/download/desktop) for Ubuntu 20.04.x LTS
+- Start VirtualBox and create a new virtual machine
+- Install Ubuntu from the installation media that you downloaded
+- If and when Virtual box asks about the network: You want a *bridged* network.
+- You need to do the following in the *virtual* machine. One reason is that you need to build the [VirtualBox Guest Addition](https://www.virtualbox.org/manual/ch04.html) modules that allow the "virtual Ubuntu" to communicate with the virtual machine software more efficiently, speed up graphics, allow the use of shared folders, and so on.
+
+ ```bash
+ sudo apt install gcc perl make # to build guest addition kernel modules
+ sudo apt install net-tools openssh-server
+ ```
+
+- You also need to actually *build and install* the [VirtualBox Guest Additions](https://help.ubuntu.com/community/VirtualBox/GuestAdditions).
diff --git a/doc/install_playbooks.md b/doc/install_playbooks.md
new file mode 100644
index 0000000..edeff2c
--- /dev/null
+++ b/doc/install_playbooks.md
@@ -0,0 +1,121 @@
+# Installing Required Software on your Development System
+
+The following instructions need to be followed and executed on your *Development System*, regardless of whether this runs in a virtual machine or not.
+
+### Setting up SSH
+
+Open a terminal window (on your Development System as defined above!) and execute the following command to update the list of packages available for your system:
+```bash
+sudo apt update
+```
+
+Install the openssh package:
+```bash
+sudo apt install openssh-server
+```
+
+In the instructions below replace USER with the specific name of the user you logged in with.
+You can check what name it is by executing the following command to display the value of the USER environment variable:
+```bash
+echo $USER
+```
+
+Test if you can ssh from the development system into itself without providing the password. It is necessary for the remaining steps described below.
+```bash
+ssh USER@localhost
+```
+If you are asked to enter the password, cancel the command (Ctrl+C) and execute the following command to install the needed ssh key:
+```bash
+ssh-copy-id -i USER@localhost
+```
+If you don't have an SSH key generated on the development system yet, execute:
+```bash
+ssh-keygen
+```
+and repeat the previous step. You should now be able to login to the development system using ```ssh USER@localhost```
+
+### Installing Ansible
+
+Some of the WARA PS software is installed using [Ansible Playbooks](https://docs.ansible.com/ansible/latest/index.html).
+
+If you use Ubuntu 18.04, you first need to do the following in order to get access to a repository containing the Ansible software:
+
+```bash
+## sudo install --reinstall ca-certificates # Had to do this for the apt-add-repository to work
+sudo apt install software-properties-common
+sudo apt-add-repository --yes --update ppa:ansible/ansible
+```
+
+Regardless of Ubuntu version, continue as follows:
+
+```bash
+sudo apt install ansible
+```
+
+### Installing software using Ansible Playbooks
+
+Clone our playbooks repo to get access to the actual playbooks for WARA PS:
+
+```bash
+sudo apt install git
+git clone https://gitlab.liu.se/lrs/lrs_playbooks.git
+```
+
+Run the `wara_develop` playbook as follows to install and update the WARA PS developer software. It can take several minutes to complete.
+
+- In the command below the value of the environment variable specifying the login name is used. You don't have to replace it.
+
+- But make sure you replace the last argument with the actual password of the root/administrator on the development system.
+
+```bash
+cd lrs_playbooks
+git pull
+ansible-playbook -i hosts playbooks/wara_develop.yml -e user=${USER} -e install_user=${USER} -e ansible_sudo_pass=******
+```
+
+### Finishing Up
+
+Add the following commands at the end of the ```~/.bashrc``` file on your development system:
+```bash
+export WORLD_ORIGIN_LAT=57.7605573519
+export WORLD_ORIGIN_LON=16.6827607783
+export WORLD_ORIGIN_ELEVATION=29.8
+
+#source /opt/ros/melodic/setup.bash
+source ${HOME}/wara_ws/devel/setup.bash
+export PATH=${HOME}/lrs_devenv_common/script:${PATH}
+```
+
+Then log in and log out to the development system for the docker commands to work. Test this with:
+
+```bash
+docker ps
+```
+It should show:
+```bash
+tompe@philo:~$ docker ps
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+tompe@philo:~$
+```
+
+At this point your system now has the necessary software installed.
+
+You can use the following commands on the development system to test the 3D graphics hardware and driver setup on your system:
+
+```bash
+glxgears
+glmark2
+```
+
+If the above commands execute without errors you can test that Gazebo
+works correctly on your development system:
+
+```bash
+roslaunch lrs_wara_gazebo gazebo.launch
+roslaunch lrs_wara_gazebo dji_to_gazebo.launch name:=dji0 with_laser:=true x:=5
+```
+
+All files to run these tests should be available in lrs_wara_gazebo
+which is installed in wara_ws by the Playbook above. The first command
+starts Gazebo and the second command adds a model of a DJI M100 to the
+Gazebo world.
--
GitLab