Merge branch 'main' into pages_v2

docs/vms/ubuntu-14/how-to-use.md

@@ -0,0 +1 @@
+../../../scripts/vms/ubuntu-14/how-to-use.md

docs/vms/ubuntu-16/how-to-use.md

@@ -0,0 +1 @@
+../../../scripts/vms/ubuntu-16/how-to-use.md

mkdocs.yml

@@ -79,29 +79,30 @@ 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
       - Compiling: ros2/compiling-for-amd64-based-systems.md
       - Compiling for SBCs: ros2/compiling-for-arm-based-systems.md
   - Marcos: release/index.md
   - Equipe: sobre/equipe.md
-  - Sobre: sobre/sobre.md
+  - Sobre: sobre/sobre.md

scripts/vms/ubuntu-14/README.md → 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:
+
+```
+<!. ./env-vars.sh > /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:
+
+```
+<!. ./env-vars.sh > /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
+```

scripts/vms/ubuntu-16/README.md → 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:
+
+```
+<!. ./env-vars.sh > /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:
+
+```
+<!. ./env-vars.sh > /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
+```