diff --git a/docs/vms/ubuntu-14/README.md b/docs/vms/ubuntu-14/README.md deleted file mode 120000 index 2973c1d..0000000 --- a/docs/vms/ubuntu-14/README.md +++ /dev/null @@ -1 +0,0 @@ -../../../scripts/vms/ubuntu-14/README.md \ No newline at end of file diff --git a/docs/vms/ubuntu-14/how-to-use.md b/docs/vms/ubuntu-14/how-to-use.md new file mode 120000 index 0000000..436cc2b --- /dev/null +++ b/docs/vms/ubuntu-14/how-to-use.md @@ -0,0 +1 @@ +../../../scripts/vms/ubuntu-14/how-to-use.md \ No newline at end of file diff --git a/docs/vms/ubuntu-16/README.md b/docs/vms/ubuntu-16/README.md deleted file mode 120000 index 33aab63..0000000 --- a/docs/vms/ubuntu-16/README.md +++ /dev/null @@ -1 +0,0 @@ -../../../scripts/vms/ubuntu-16/README.md \ No newline at end of file diff --git a/docs/vms/ubuntu-16/how-to-use.md b/docs/vms/ubuntu-16/how-to-use.md new file mode 120000 index 0000000..8adf730 --- /dev/null +++ b/docs/vms/ubuntu-16/how-to-use.md @@ -0,0 +1 @@ +../../../scripts/vms/ubuntu-16/how-to-use.md \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index bacecd5..3ce4c3f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -79,24 +79,25 @@ nav: - Trabalhando com máquinas virtuais: Instruções/Maquina_Virtual.md - Trabalhando com o v4: - Introdução ao NAOqi: Instruções/NAOqi-overview_v4.md - - Máquina Virtual com scripts: vms/ubuntu-14/README.md + - Máquina Virtual e scripts de instalação (v4): vms/ubuntu-14/how-to-use.md - NAO Flasher: Instruções/NAO_Flasher.md - SDK C++: Instruções/CPP_SDK_v4.md - Choregraphe: Instruções/Choregraphe_v4.md - Exemplos NAOqi C++: naoqi-2.1/cpp/about-the-examples.md - Trabalhando com o v6: - Introdução ao NAOqi: Instruções/NAOqi-overview_v6.md - - Máquina Virtual com scripts: vms/ubuntu-16/README.md + - Máquina Virtual e scripts de instalação (v6): vms/ubuntu-16/how-to-use.md - Robot Settings: Instruções/Robot_Settings.md - SDK C++: Instruções/CPP_SDK_v6.md - Choregraphe: Instruções/Choregraphe_v6.md - Extra: - ROS1: - - Instruções: Instruções/ROS_1.md + - Instructions: Instruções/ROS_1.md - General: ros1/general-instructions.md - Precompiled: ros1/installing-precompiled-packages.md - Compiling: ros1/compiling-for-amd64-based-systems.md - Compiling for SBCs: ros1/compiling-for-arm-based-systems.md + - Native packages: ros1/installing-native-packages.md - ROS2: - General: ros2/general-instructions.md - Precompiled: ros2/installing-precompiled-packages.md @@ -104,4 +105,4 @@ nav: - Compiling for SBCs: ros2/compiling-for-arm-based-systems.md - Marcos: release/index.md - Equipe: sobre/equipe.md - - Sobre: sobre/sobre.md \ No newline at end of file + - Sobre: sobre/sobre.md diff --git a/scripts/vms/ubuntu-14/README.md b/scripts/vms/ubuntu-14/how-to-use.md similarity index 73% rename from scripts/vms/ubuntu-14/README.md rename to scripts/vms/ubuntu-14/how-to-use.md index b09f6b1..4999837 100644 --- a/scripts/vms/ubuntu-14/README.md +++ b/scripts/vms/ubuntu-14/how-to-use.md @@ -40,6 +40,14 @@ variable at the `env-vars.sh` script) [1]: https://releases.ubuntu.com/trusty/ubuntu-14.04.6-desktop-amd64.iso +The GNU/Linux distribution for fully installing NAOv4's programming environment +is Ubuntu 14.04 LTS. It is highly possible that one may be able to run it on the +equivalent Debian release. + +If the user wishes to **only** develop programs using NAOv4's C++98 API, it +*may* be possible to use a newer GNU/Linux distribution, provided that it has +support for Python 2 and Pip 20.3.4. + ### Creating the VM and preparing to compile NAOqi for NAOv4 The user must run in their host machine the scripts inside this repository in @@ -64,23 +72,24 @@ download Pip, as it crashes the Python SDK. ## Starting the Virtual Machine up for the first time -The initial images are created by the `reset-*` scripts - -``` -./reset-main-drive.sh -``` +The initial images are created by the `reset-main-drive.sh` and `first-boot.sh` +scripts. The former creates a QCOW2 image that will perform as the virtual +machine's or guest system's hard drive, and the latter will boot the VM with +the Ubuntu 14 LTS installation disk. With the drives created, run the initialisation script and install a regular Ubuntu 14.04 LTS installation: -- Language and keyboard layout: Português Brasileiro +- Language and keyboard layout: Português Brasileiro (or other UTF-8 locale) - Erase disk and install Ubuntu -- Timezone: Sao Paulo -- User: softex +- Timezone: Sao Paulo (or your local timezone) +- User: softex (must be the one specified in `VM_USER` in `env-vars.sh`) -``` -./first-boot.sh -``` +### WARNING + +The scripts expect an *unified root* partition scheme. Do not split `/home` or +other directories into other partitions unless you know how to modify the +scripts that copy data into or from the virtual machine or guest system. ## Running the VM @@ -314,7 +323,29 @@ qibuild configure -c "${NAOQI_QIBUILD_CTC_CONFIG}" qibuild make -c "${NAOQI_QIBUILD_CTC_CONFIG}" ``` -## Connecting to the Robot +## Connecting to the simulated robot + +The simulated robot is an executable located in the C++ toolchain directory +named `naoqi`. Provided that the tools were installed with the aforementioned +scripts in their default configuration, it will be located at +`/home/softex/NAO4/SDKs/cpp/naoqi-sdk-2.1.4.13-linux64/naoqi`. + +The simulated robot must always be initialised before running Choregraphe or +your desired module. It will behave similarly to a physical robot, except by its +lack of cameras, and it will by default initialise its *broker* at *localhost*, +also known as IPv4 127.0.0.1, at the port 9559. + +### Simulating in Choregraphe + +If you wish to simulate your C++ module in Choregraphe, first you should start +the simulated `naoqi`. After doing it, then you must open Choregraphe, and +connect it to the broker available at 127.0.0.1 port 9559. + +After these steps you should see a 3D simulation of a NAO robot in the +Robot View panel. At this stage you are ready to connect to the simulated robot +and check how it behaves in the simplified simulation offered by Choregraphe. + +## Connecting to the robot There are three scripts that are used when connecting the Virtual Machine to your NAO: @@ -339,3 +370,62 @@ reconfiguration event. You should be able to reset nftables to its standard configuration using the command: `nft flush ruleset`. This will break the network for the containers until the machine or the Docker service unit are restarted. + +## How to manually add files to the Virtual Machine + +You may want to add files from the host system, your current machine, to the +guest one, stored in the virtual machines. An usual way to do it is through SSH, +but it requires configuring an SSH server in the guest and a client in the host. + +A quicker way is to add the files directly to the virtual machine images. This +approach requires that the VMs must not be in execution, unlike the SSH-based +one. It is most convenient to use `guestfish`, a system shell that specialises +in manipulating virtual machine images, to manually add files to the VMs. + +You may create a script based on `inject-home.sh`, or use `guestfish` on its +interactive mode, which works similarly to the usual system shell. Even though +it requires more typing, the latter approach is more user-friendly and will be +explored in this tutorial. + +Firstly, you must know the path to the files that you wish to add to your VM and +their desired location in the virtual machine. These will be parameters that +will be used in `guestfish`'s `copy-in` command, responsible for copying files +*into* the VM. + +Then you must mount the virtual machine's partition that holds the output path. +This is the more cumbersome stage, as it requires knowing which partitions are +included in the virtual machine's image file. If you followed the previous +instructions and installed the VM using the recommended settings, you will be +able to use the following commands after executing `guestfish` on your terminal +with the working directory pointing where the image is located: + +``` + /dev/null; echo "add '${DISK_LOCATION}'" +run +mount '/dev/sda1' '/' +``` + +With the main partition mounted, you may use the `ls` command to list files and +directories. Copying files into the VM is done though the `copy-in` command: + +``` +# copying a file or directory from the current host directory +copy-in my-file-or-directory /home/softex +# copying a file or directory from an absolute path in the host +copy-in /absolute/path/in/the/host/something /desired/path/in/the/vm +``` + +The scripts use a more complicated syntax to automatically obtain the user that +has been configured in the `env-vars.sh` file: + +``` + /dev/null; echo "copy-in 'my-file' '/home/${VM_USER}/abc'" +``` + +After copying all the desired files, do not forget to unmount all the partitions +and close `guestfish` before running the VM: + +``` +umount-all +exit +``` \ No newline at end of file diff --git a/scripts/vms/ubuntu-16/README.md b/scripts/vms/ubuntu-16/how-to-use.md similarity index 72% rename from scripts/vms/ubuntu-16/README.md rename to scripts/vms/ubuntu-16/how-to-use.md index b3b838f..4498152 100644 --- a/scripts/vms/ubuntu-16/README.md +++ b/scripts/vms/ubuntu-16/how-to-use.md @@ -40,6 +40,14 @@ variable at the `env-vars.sh` script) [1]: https://releases.ubuntu.com/releases/xenial/ubuntu-16.04.7-desktop-amd64.iso +The GNU/Linux distribution for fully installing NAOv4's programming environment +is Ubuntu 16.04 LTS. It is highly possible that one may be able to run it on the +equivalent Debian release. + +If the user wishes to **only** develop programs using NAOv4's C++11 API, it +*may* be possible to use a newer GNU/Linux distribution, provided that it has +support for Python 2 and Pip 20.3.4. + ### Creating the VM and preparing to compile NAOqi for NAOv6 The user must run in their host machine the scripts inside this repository in @@ -62,23 +70,24 @@ using the `install-naov6.sh` script. ## Starting the Virtual Machine up for the first time -The initial images are created by the `reset-*` scripts - -``` -./reset-main-drive.sh -``` +The initial images are created by the `reset-main-drive.sh` and `first-boot.sh` +scripts. The former creates a QCOW2 image that will perform as the virtual +machine's or guest system's hard drive, and the latter will boot the VM with +the Ubuntu 16 LTS installation disk. With the drives created, run the initialisation script and install a regular Ubuntu 16.04 LTS installation: -- Language and keyboard layout: Português Brasileiro +- Language and keyboard layout: Português Brasileiro (or other UTF-8 locale) - Erase disk and install Ubuntu -- Timezone: Sao Paulo -- User: softex +- Timezone: Sao Paulo (or your local timezone) +- User: softex (must be the one specified in `VM_USER` in `env-vars.sh`) -``` -./first-boot.sh -``` +### WARNING + +The scripts expect an *unified root* partition scheme. Do not split `/home` or +other directories into other partitions unless you know how to modify the +scripts that copy data into or from the virtual machine or guest system. ## Running the VM @@ -311,6 +320,28 @@ qibuild configure -c "${NAOQI_QIBUILD_CTC_CONFIG}" qibuild make -c "${NAOQI_QIBUILD_CTC_CONFIG}" ``` +## Connecting to the simulated robot + +The simulated robot is an executable located in the C++ toolchain directory +named `naoqi`. Provided that the tools were installed with the aforementioned +scripts in their default configuration, it will be located at +`/home/softex/NAO6/SDKs/cpp/naoqi-sdk-2.8.5.10-linux64/naoqi`. + +The simulated robot must always be initialised before running Choregraphe or +your desired module. It will behave similarly to a physical robot, except by its +lack of cameras, and it will by default initialise its *broker* at *localhost*, +also known as IPv4 127.0.0.1, at the port 9559. + +### Simulating in Choregraphe + +If you wish to simulate your C++ module in Choregraphe, first you should start +the simulated `naoqi`. After doing it, then you must open Choregraphe, and +connect it to the broker available at 127.0.0.1 port 9559. + +After these steps you should see a 3D simulation of a NAO robot in the +Robot View panel. At this stage you are ready to connect to the simulated robot +and check how it behaves in the simplified simulation offered by Choregraphe. + ## Connecting to the Robot There are three scripts that are used when connecting the Virtual Machine to @@ -336,3 +367,62 @@ reconfiguration event. You should be able to reset nftables to its standard configuration using the command: `nft flush ruleset`. This will break the network for the containers until the machine or the Docker service unit are restarted. + +## How to manually add files to the Virtual Machine + +You may want to add files from the host system, your current machine, to the +guest one, stored in the virtual machines. An usual way to do it is through SSH, +but it requires configuring an SSH server in the guest and a client in the host. + +A quicker way is to add the files directly to the virtual machine images. This +approach requires that the VMs must not be in execution, unlike the SSH-based +one. It is most convenient to use `guestfish`, a system shell that specialises +in manipulating virtual machine images, to manually add files to the VMs. + +You may create a script based on `inject-home.sh`, or use `guestfish` on its +interactive mode, which works similarly to the usual system shell. Even though +it requires more typing, the latter approach is more user-friendly and will be +explored in this tutorial. + +Firstly, you must know the path to the files that you wish to add to your VM and +their desired location in the virtual machine. These will be parameters that +will be used in `guestfish`'s `copy-in` command, responsible for copying files +*into* the VM. + +Then you must mount the virtual machine's partition that holds the output path. +This is the more cumbersome stage, as it requires knowing which partitions are +included in the virtual machine's image file. If you followed the previous +instructions and installed the VM using the recommended settings, you will be +able to use the following commands after executing `guestfish` on your terminal +with the working directory pointing where the image is located: + +``` + /dev/null; echo "add '${DISK_LOCATION}'" +run +mount '/dev/sda2' '/' +``` + +With the main partition mounted, you may use the `ls` command to list files and +directories. Copying files into the VM is done though the `copy-in` command: + +``` +# copying a file or directory from the current host directory +copy-in my-file-or-directory /home/softex +# copying a file or directory from an absolute path in the host +copy-in /absolute/path/in/the/host/something /desired/path/in/the/vm +``` + +The scripts use a more complicated syntax to automatically obtain the user that +has been configured in the `env-vars.sh` file: + +``` + /dev/null; echo "copy-in 'my-file' '/home/${VM_USER}/abc'" +``` + +After copying all the desired files, do not forget to unmount all the partitions +and close `guestfish` before running the VM: + +``` +umount-all +exit +``` \ No newline at end of file