diff --git a/docs/en/simulation_native.md b/docs/en/simulation_native.md index c7cb7eb0..cb3a1dca 100644 --- a/docs/en/simulation_native.md +++ b/docs/en/simulation_native.md @@ -4,31 +4,56 @@ Setting up the simulation environment from scratch requires some effort, but res > **Hint** See up-to-date commands set for installation Clover simulation software in the script, that builds the virtual machine image with the simulator: [`install_software.sh`](https://github.com/CopterExpress/clover_vm/blob/master/scripts/install_software.sh). -Prerequisites: Ubuntu 20.04 and [ROS Noetic](http://wiki.ros.org/noetic/Installation/Ubuntu). +Prerequisites: **Ubuntu 20.04**. + +## Install ROS + +Install ROS Noetic using the [official installation manual](http://wiki.ros.org/noetic/Installation/Ubuntu) (Desktop or Full install). + +Add sourcing ROS' `setup.bash` initialization script to your `.bashrc`: + +```bash +echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc +source ~/.bashrc +``` + +Install required tools: + +```bash +sudo apt install build-essential git python3-pip python3-rosdep +``` ## Create a workspace for the simulation -Throughout this guide we will be using the `catkin_ws` as the workspace name. Feel free to change it in your setup. We will be creating it in the home directory of the current user (`~`). - -Create the workspace and clone Clover sources: +Create a workspace for the simulation: ```bash mkdir -p ~/catkin_ws/src +cd ~/catkin_ws +catkin_make +echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc +source ~/.bashrc +``` + +Clone Clover sources: + +```bash cd ~/catkin_ws/src git clone --depth 1 https://github.com/CopterExpress/clover git clone --depth 1 https://github.com/CopterExpress/ros_led git clone --depth 1 https://github.com/ethz-asl/mav_comm ``` -Install all prerequisites using `rosdep`: +Install all dependencies using `rosdep`: ```bash cd ~/catkin_ws +sudo rosdep init rosdep update rosdep install --from-paths src --ignore-src -y ``` -Install Python-dependencies: +Install Python dependencies: ```bash sudo /usr/bin/python3 -m pip install -r ~/catkin_ws/src/clover/clover/requirements.txt @@ -36,15 +61,19 @@ sudo /usr/bin/python3 -m pip install -r ~/catkin_ws/src/clover/clover/requiremen ## Get PX4 sources -PX4 will be built along with the other packages in our workspace. You may clone it directly into the workspace or put it somewhere and symlink to `~/catkin_ws/src`. We will need to put its `sitl_gazebo` submodule in `~/catkin_ws/src` as well. For simplicity's sake we will clone the firmware directly to the workspace: +PX4 will be built along with the other packages in our workspace. You may clone it directly into the workspace or put it somewhere and symlink to `~/catkin_ws/src`. We will need to put its `sitl_gazebo` and `mavlink` submodules into `~/catkin_ws/src` as well. + +Clone PX4 sources and make the required symlinks: ```bash -cd ~/catkin_ws/src git clone --recursive --depth 1 --branch v1.12.0 https://github.com/PX4/PX4-Autopilot.git ~/PX4-Autopilot -ln -s ~/PX4-Autopilot ~/catkin_ws/src/PX4-Autopilot -ln -s ~/PX4-Autopilot/Tools/sitl_gazebo ~/catkin_ws/src/sitl_gazebo +ln -s ~/PX4-Autopilot ~/catkin_ws/src/ +ln -s ~/PX4-Autopilot/Tools/sitl_gazebo ~/catkin_ws/src/ +ln -s ~/PX4-Autopilot/mavlink ~/catkin_ws/src/ ``` +> **Hint** You may use more recent PX4 version, but there would be more risk of something would not be working. + ## Install PX4 prerequisites PX4 comes with its own script for dependency installation. We may as well leverage it: @@ -56,10 +85,12 @@ sudo ./ubuntu.sh This will install everything required to build PX4 and its SITL environment. -You may want to skip installing the ARM toolchain if you're not planning on compiling PX4 for your flight controller. To do this, use the `--no-nuttx` flag: +> **Hint** You may want to skip installing the ARM toolchain if you're not planning on compiling PX4 for your flight controller. To do this, use the `--no-nuttx` flag: `sudo ./ubuntu.sh --no-nuttx`. -``` -sudo ./ubuntu.sh --no-nuttx +Install more required Python packages: + +```bash +pip3 install --user toml ``` ## Add the Clover airframe @@ -67,7 +98,7 @@ sudo ./ubuntu.sh --no-nuttx Add the Clover airframe to PX4 using the command: ```bash -ln -s "$(catkin_find clover_simulation airframes)"/* ~/PX4-Autopilot/ROMFS/px4fmu_common/init.d-posix/airframes/ +ln -s ~/catkin_ws/src/clover/clover_simulation/airframes/* ~/PX4-Autopilot/ROMFS/px4fmu_common/init.d-posix/airframes/ ``` ## Install geographiclib datasets @@ -80,20 +111,44 @@ sudo /opt/ros/noetic/lib/mavros/install_geographiclib_datasets.sh ## Build the simulator -With all dependencies installed, you can build your workspace: +Build your workspace: ```bash cd ~/catkin_ws catkin_make ``` -> **Note** Some of the files - particularly Gazebo plugins - require large amounts of RAM to be built. You may wish to reduce the number of parallel jobs; the number of parallel jobs should be equal to the amount of RAM in gigabytes divided by 2 - so a 16GB machine should use no more than 8 jobs. You can specify the number of jobs using the `-j` flag: `catkin_make -j8` +> **Note** If building fails with RAM issues (`c++: fatal error: Killed signal terminated program cc1plus`), reduce the number of parallel jobs using `-j` key. For example, to use only two parallel jobs use `catkin_make -j2` command. ## Run the simulator In order to be sure that everything was built correctly, try running the simulator for the first time: ```bash -source ~/catkin_ws/devel/setup.bash roslaunch clover_simulation simulator.launch ``` + +You can test autonomous flight using example scripts in `~/catkin_ws/src/clover/clover/examples` directory. + +## Additional steps + +Optionally, install roscore systemd service to have roscore running in background: + +```bash +sed -i "s/pi/$USER/g" ~/catkin_ws/src/clover/builder/assets/roscore.service +sudo cp ~/catkin_ws/src/clover/builder/assets/roscore.service /etc/systemd/system +sudo systemctl enable roscore +sudo systemctl start roscore +``` + +Install any web server to serve Clover's web tools (`.ros/www` directory), e. g. Monkey: + +```bash +wget https://github.com/CopterExpress/clover_vm/raw/master/assets/packages/monkey_1.6.9-1_amd64.deb -O /tmp/monkey_1.6.9-1_amd64.deb +sudo apt-get install -y /tmp/monkey_1.6.9-1_amd64.deb +sed "s/pi/$USER/g" ~/catkin_ws/src/clover/builder/assets/monkey | sudo tee /etc/monkey/sites/default +sudo -E sh -c "sed -i 's/SymLink Off/SymLink On/' /etc/monkey/monkey.conf" +sudo cp ~/catkin_ws/src/clover/builder/assets/monkey.service /etc/systemd/system/monkey.service +sudo systemctl enable monkey +sudo systemctl start monkey +``` diff --git a/docs/ru/simulation_native.md b/docs/ru/simulation_native.md index 681a6a01..c50c5223 100644 --- a/docs/ru/simulation_native.md +++ b/docs/ru/simulation_native.md @@ -4,16 +4,40 @@ > **Hint** Смотрите актуальный набор команд установки необходимого ПО для запуска симулятора Клевера в скрипте сборки виртуальной машины с симулятором: [`install_software.sh`](https://github.com/CopterExpress/clover_vm/blob/master/scripts/install_software.sh). -Требования для сборки: Ubuntu 20.04 и [ROS Noetic](http://wiki.ros.org/noetic/Installation/Ubuntu). +Требования для сборки: **Ubuntu 20.04**. + +## Установка ROS + +Установите ROS Noetic используя [официальную документацию по установке](http://wiki.ros.org/noetic/Installation/Ubuntu) (Desktop или Full установка). + +Добавьте выполнение инициализирующего скрипта ROS `setup.bash` в ваш файл `.bashrc`: + +```bash +echo "source /opt/ros/noetic/setup.bash" >> ~/.bashrc +source ~/.bashrc +``` + +Установите необходимые инструменты, которые понадобятся для дальнейшей установки: + +```bash +sudo apt install build-essential git python3-pip python3-rosdep +``` ## Создание рабочего пространства для симулятора -В этой статье мы будем использовать `catkin_ws` как имя рабочего пространства (вы можете поменять её). Мы создадим её в домашнем каталоге текущего пользователя (`~`). - -Создайте рабочее пространство и загрузите исходный код Клевера: +Создайте рабочее пространство: ```bash mkdir -p ~/catkin_ws/src +cd ~/catkin_ws +catkin_make +echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc +source ~/.bashrc +``` + +Склонируйте исходный код пакетов Clover: + +```bash cd ~/catkin_ws/src git clone --depth 1 https://github.com/CopterExpress/clover git clone --depth 1 https://github.com/CopterExpress/ros_led @@ -36,15 +60,19 @@ sudo /usr/bin/python3 -m pip install -r ~/catkin_ws/src/clover/clover/requiremen ## Загрузка исходного кода PX4 -Сборка PX4 будет осуществлена вместе с другими пакетами в нашем рабочем пространстве. Вы можете загрузить его прямо в рабочее пространство или поместить куда-нибудь и создать симлинк к `~/catkin_ws/src`. Нам также нужно будет поместить его подмодуль `sitl_gazebo` в `~/catkin_ws/src`. Для упрощения мы загрузим прошивку прямо в рабочее пространство: +Сборка PX4 будет осуществлена вместе с другими пакетами в нашем рабочем пространстве. Вы можете загрузить его прямо в рабочее пространство или поместить куда-нибудь и создать симлинк к `~/catkin_ws/src`. Нам также нужно будет поместить его подмодули `sitl_gazebo` и `mavlink` в `~/catkin_ws/src`. + +Склонируйте исходный код PX4 и создайте необходимые симлинки: ```bash -cd ~/catkin_ws/src git clone --recursive --depth 1 --branch v1.12.0 https://github.com/PX4/PX4-Autopilot.git ~/PX4-Autopilot -ln -s ~/PX4-Autopilot ~/catkin_ws/src/PX4-Autopilot -ln -s ~/PX4-Autopilot/Tools/sitl_gazebo ~/catkin_ws/src/sitl_gazebo +ln -s ~/PX4-Autopilot ~/catkin_ws/src/ +ln -s ~/PX4-Autopilot/Tools/sitl_gazebo ~/catkin_ws/src/ +ln -s ~/PX4-Autopilot/mavlink ~/catkin_ws/src/ ``` +> **Hint** Вы можете использовать более позднюю версию PX4 с большим риском, что что-то не заработает. + ## Установка зависимостей PX4 PX4 имеет свой собственный скрипт для установки зависимостей. Воспользуемся им: @@ -56,10 +84,12 @@ sudo ./ubuntu.sh Он установит все, что нужно для сборки PX4 и SITL. -Также вы можете пропустить установку ARM тулчейна, если вы не планируете компилировать PX4 для вашего полетного контроллера. Для этого воспользуйтесь флагом `--no-nuttx`: +> **Hint** Также вы можете пропустить установку ARM тулчейна, если вы не планируете компилировать PX4 для вашего полетного контроллера. Для этого воспользуйтесь флагом `--no-nuttx`: `sudo ./ubuntu.sh --no-nuttx`. -``` -sudo ./ubuntu.sh --no-nuttx +Установите дополнительные необходимые Python-пакеты: + +```bash +pip3 install --user toml ``` ## Добавление рамы Клевера @@ -67,7 +97,7 @@ sudo ./ubuntu.sh --no-nuttx Добавьте в PX4 раму Клевера с помощью следующей команды: ```bash -ln -s "$(catkin_find clover_simulation airframes)"/* ~/PX4-Autopilot/ROMFS/px4fmu_common/init.d-posix/airframes/ +ln -s ~/catkin_ws/src/clover/clover_simulation/airframes/* ~/PX4-Autopilot/ROMFS/px4fmu_common/init.d-posix/airframes/ ``` ## Установка датасетов geographiclib @@ -87,13 +117,37 @@ cd ~/catkin_ws catkin_make ``` -> **Note** Некоторые файлы, особенно плагины Gazebo, требуют большого объема оперативной памяти для сборки. Вы можете уменьшить количество параллельных процессов; количество параллельных процессов должно быть равно объёму RAM в гигабайтах, поделенному на 2. Например, для машины с 16Гб следует указывать не более 8 процессов. Вы можете указать количество процессов, используя флаг `-j` : ```catkin_make -j8``` +> **Note** Если процесс сборки завершится с ошибкой, связанной с недостатком памяти (`c++: fatal error: Killed signal terminated program cc1plus`), уменьшите количество параллельно исполняемых процессов используя ключ `-j`. Например, чтобы использовать только два параллельных процесса используйте команду `catkin_make -j2`. ## Запуск симулятора Чтобы удостовериться в том, что все было собрано корректно, попробуйте запустить симулятор: ```bash -source ~/catkin_ws/devel/setup.bash roslaunch clover_simulation simulator.launch ``` + +Вы можете проверить автономный полет используя скрипты в директории `~/catkin_ws/src/clover/clover/examples`. + +## Дополнительные шаги + +Опционально вы можете установить systemd-сервис для roscore для того, чтобы roscore был постоянно запущен в фоне: + +```bash +sed -i "s/pi/$USER/g" ~/catkin_ws/src/clover/builder/assets/roscore.service +sudo cp ~/catkin_ws/src/clover/builder/assets/roscore.service /etc/systemd/system +sudo systemctl enable roscore +sudo systemctl start roscore +``` + +Установите любой веб-сервер, чтобы раздавать веб-инструменты Клевера (директория `.ros/www`), например, Monkey: + +```bash +wget https://github.com/CopterExpress/clover_vm/raw/master/assets/packages/monkey_1.6.9-1_amd64.deb -O /tmp/monkey_1.6.9-1_amd64.deb +sudo apt-get install -y /tmp/monkey_1.6.9-1_amd64.deb +sed "s/pi/$USER/g" ~/catkin_ws/src/clover/builder/assets/monkey | sudo tee /etc/monkey/sites/default +sudo -E sh -c "sed -i 's/SymLink Off/SymLink On/' /etc/monkey/monkey.conf" +sudo cp ~/catkin_ws/src/clover/builder/assets/monkey.service /etc/systemd/system/monkey.service +sudo systemctl enable monkey +sudo systemctl start monkey +```