Skip to content

Commit

Permalink
Merge pull request #54 from ResidenciaTICBrisa/scripts-naov6
Browse files Browse the repository at this point in the history
Scripts de instalação do NAOv6
  • Loading branch information
damarcones authored Sep 5, 2023
2 parents 88c2445 + 1d981b3 commit 357621e
Show file tree
Hide file tree
Showing 19 changed files with 784 additions and 2 deletions.
3 changes: 2 additions & 1 deletion docs/mkdocs-kludge.sh
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
#!/bin/bash

readonly DOCDIRS=(ros1 ros2 vms/ubuntu-12)
readonly DOCDIRS=(ros1 ros2 vms/ubuntu-12 vms/ubuntu-16)

for docdir in "${DOCDIRS[@]}"; do
# Create directory inside the current one
rm -rv "${docdir}"
mkdir -pv "${docdir}"

dirlevel="$(perl -ne 'print tr/\///' <<< "${docdir}")"
Expand Down
1 change: 1 addition & 0 deletions docs/vms/ubuntu-16/README.md
4 changes: 3 additions & 1 deletion mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -74,12 +74,14 @@ markdown_extensions:

nav:
- Home: index.md
- Maquina Virtual: Instruções/Maquina_Virtual.md
- Máquina Virtual: Instruções/Maquina_Virtual.md
- NAOv4:
- Máquina Virtual com scripts: vms/ubuntu-12/README.md
- NAO Flahser: Instruções/NAO_Flasher.md
- SDK C++: Instruções/CPP_SDK_v4.md
- Choregraphe: Instruções/Choregraphe_v4.md
- NAOv6:
- Máquina Virtual com scripts: vms/ubuntu-16/README.md
- Robot Settings: Instruções/Robot_Settings.md
- SDK C++: Instruções/CPP_SDK_v6.md
- Choregraphe: Instruções/Choregraphe_v6.md
Expand Down
7 changes: 7 additions & 0 deletions scripts/vms/ubuntu-16/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Vim swap files
*.swp

# QEMU disks
*.qcow2
*.qcow
*.iso
206 changes: 206 additions & 0 deletions scripts/vms/ubuntu-16/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,206 @@
# Set up and run a VM for developing NAOv6-based solutions

## Setup

The scripts are flexible, but they still have requirements in order to be run.

### Packages

These scripts need the following packages to be installed on the host's system
(assuming a Debian GNU/Linux based distribution, such as Ubuntu, Linux Mint):

|Package |Version|
|----------------|-------|
|qemu-system-x86 |6.2.0 |
|qemu-utils |6.2.0 |
|qemu-system-gui |6.2.0 |
|qemu-block-extra|6.2.0 |
|ovmf |2022.11|
|libguestfs-tools|1.48.6 |

The scripts assume that KVM-based accelerated virtualisation is enabled on the
host machine. This requires a compatible processor and it may require a
configuration in the UEFI/BIOS (AMD-V, AMD SVM, Intel VT, Intel VT-x,
Intel VMX).

The package `cpu-checker` is able to verify if KVM is correctly enabled: one
only needs to run the command `kvm-ok` as superuser.

### Expected directory structure

Even though these scripts can be modified easily, they expect the following
directory structure in their current form:

- `env-vars.sh`, a script to centralise the VM's configurations
- an [image][1] from Ubuntu's installation disk version 16.04 named as
`ubuntu-16.04-desktop-amd64.iso` (this can be altered in the `IMAGE_LOCATION`
variable at the `env-vars.sh` script)

[1]: https://releases.ubuntu.com/releases/xenial/ubuntu-16.04.7-desktop-amd64.iso

### Creating the VM and preparing to compile NAOqi for NAOv6

The user must run in their host machine the scripts inside this repository in
the following order:

1. `reset-main-drive.sh`
2. `first-boot.sh`

After installing Ubuntu 16.04 in their virtual machine, the following scripts
must be executed in their host machine:

1. `update-sources.sh`
2. `inject-home.sh`

Now, inside the virtual machine, also known as the guest machine, the user
must run the `prepare-naoqi-requirements.sh` script to install Pip 20.3.4.

Finally, the user will be able to install the NAOv6 development environment
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
```

With the drives created, run the initialisation script and install a regular
Ubuntu 16.04 LTS installation:

- Language and keyboard layout: Português Brasileiro
- Erase disk and install Ubuntu
- Timezone: Sao Paulo
- User: softex

```
./first-boot.sh
```

## Running the VM

Sometimes the Brazilian server takes too long to synchronise with the main
server, leading to failed installations or upgrades. In order to avoid this
problem, please run the following script to set the repository to the main
archive:

```
./update-sources.sh
```

Don't forget to update (`apt update`) and upgrade (`apt dist-upgrade`) if there
are any updates available.

## Preparing to install NAOqi for NAOv6

Ubuntu 16.04 has an old version of `pip`. This requires an installation of the
last Python 2 compatible release to be able to download the packages and their
dependencies. These steps can be automated by sending a script to the user's
home on the VM:

```
./inject-home.sh
```

After the script is sent to the user's home, it must be executed in the VM. It
will propmpt for administrative privileges before updating the repository and
installing dependencies for installing Pip:

```
./prepare-naoqi-requirements.sh
```

## Installing NAOv6 development environment

After running the preparation script, the installation one must be run on a
new terminal session. If you wish to remain in the same session, you must reload
your `.bashrc` (`source .bashrc`) to enable the modifications made to enable
PIP2 and its binaries.

```
./install-naov6.sh
```

This script will also prompt for administrative rights, as it needs to install
packages used by the C++ and Python2 SDKs.

### Activating Choregraphe

Choregraphe may prompt for its activation key on its first initialisation. This
key is available in the installation script, and it will also be printed to the
terminal after the script is executed.

### Configuring the host USB

The `env-vars.sh` script has four variables to control how the virtual machine
will connect to the host USB device:

- `USB_HOST_BUS`: the bus' ID, including leading zeros
- `USB_HOST_ADDRESS`: the device's ID in the aforementioned bus, including leading
zeros
- `USB_VENDOR_ID`: the device's vendor ID in hexadecimal notation, that is, the
device's vendor ID preceded by `0x`
- `USB_PRODUCT_ID`: the device's product ID in hexadecimal notation, that is,
the device's product ID preceded by `0x`

The variables match the output of the `lsusb` command:

```
Bus $USB_HOST_BUS Device $USB_HOST_ADDRESS: ID $USB_VENDOR_ID:$USB_PRODUCT_ID MyUSB Device Thing
```

There are two scripts that will connect the host's device to the virtual
machine:

- `run-usb-productid.sh`: connects only the device with the matching vendor and
product ID as long as it is connected to the specified port. It requires
specifying all the four variables;
- `run-usb-hostid.sh`: connects anything currenctly connected to the specified
port. It requires specifying only the bus and the device.

The virtualiser uses the `/dev/bus/usb` files to connect the VM to the host
device. This requires superuser permissions on most machines. In order to
connect a host USB device to the VM, the user must provide the script with the
necessary privileges (run it as root, prefix with `sudo`) or change the
permissions of the USB interface (changing its group with `chgrp` to a group
that it user takes part in, or changing its owner with `chown`).

#### Example

Consider the following `lsusb` output:

```
Bus 001 Device 001: ID 0001:0001 USB Thing 1
Bus 001 Device 002: ID 0001:0002 USB Thing 2
Bus 001 Device 003: ID 0001:0001 USB Thing 1
Bus 002 Device 001: ID 0002:0001 USB Device 1
Bus 002 Device 002: ID 0002:0002 USB Device 2
Bus 002 Device 003: ID 0002:0001 USB Device 1
```

If one wishes to connect the `USB Thing 1` connected at the `Bus 001` as the
device numbered `003`, they should configure the variables at `env-vars.sh` as:

```
USB_HOST_BUS="001"
USB_HOST_ADDRESS="003"
USB_VENDOR_ID="0x0001"
USB_PRODUCT_ID="0x0001"
```

Before running the desired script, the permissions must be set for the USB file
(`chown the-user /dev/bus/usb/001/003`) or the script must be run with elevated
privileges (`sudo` or run as root).

Please be aware that in order to connect only the required device to the VM, one
must run the VM using `run-usb-productid.sh`. Choosing the
`run-usb-productid.sh` would connect all the devices connected to the `Bus 001`,
the two `USB Thing 1` and the `USB Thing 2`.


### NAO Flasher permissions

NAO Flasher requires administrative permissions (`sudo` or execution as the
`root` user) to write data. If `sudo` can't find the program's path, you may
find it with `command -v flasher`.
34 changes: 34 additions & 0 deletions scripts/vms/ubuntu-16/compress-drive.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
#!/bin/bash

readonly DRIVE="$1"
readonly DRIVE_BACKUP="${DRIVE}_backup"

usage()
{
printf "Converts image to QCOW2 and compresses it\n"
printf "Usage:\tcompress-drive drive-to-compress\n"
printf "The image is backed up with a '_backup' suffix\n"

exit 1
}

missing_drive()
{
printf "Drive specified on '%s' was not found\n" "${1}"
exit 2
}

[ -n "${DRIVE}" ] || usage

if [ -f "${DRIVE}" ]; then
printf "DRIVE=%s\n" "${DRIVE}"
else
missing_drive "${DRIVE}"
fi

printf "Converting to QCOW2 and compressing %s\n" "${DRIVE}"
mv "${DRIVE}" "${DRIVE_BACKUP}"
sync
qemu-img convert -c -p -O qcow2 "${DRIVE_BACKUP}" "${DRIVE}"
#qemu-img convert --salvage -c -p -O qcow2 "${DRIVE_BACKUP}" "${DRIVE}"
sync
107 changes: 107 additions & 0 deletions scripts/vms/ubuntu-16/env-vars.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
#!/bin/bash

# [ -z "${VAR}" ] && echo "unset" || echo "set"
[ -z "${SOURCED_ENV_VARS_SH}" ] || exit 0

readonly BIOS_LOCATION="/usr/share/OVMF/OVMF_CODE.fd"
readonly IMAGE_LOCATION="ubuntu-16.04-desktop-amd64.iso"
readonly DISK_LOCATION="ubuntu-16.04-vm.qcow2"

readonly DISK_SIZE="50G"

readonly VM_INITIAL_NAME="ubuntu-16.04-nao-first-boot"
readonly VM_NAME="ubuntu-16.04-nao"
readonly IPV4_NETWORK="192.168.3.0/24"
readonly IPV4_DHCP_FIRST_ADDR="192.168.3.220"
readonly P22_FWD="10022"
readonly MACHINE_TYPE="pc-q35-6.2"
readonly MACHINE_CFG="type=${MACHINE_TYPE},accel=kvm"
readonly CPU_MODEL="Haswell-v4"
readonly CPU_NUMBER="4"
readonly MACHINE_MEMORY_SIZE="4G"
readonly DISPLAY_DEVICE="virtio-vga-gl"
readonly DISPLAY_BACKEND="gtk,gl=on"

readonly VM_USER="softex"

readonly USB_HOST_BUS=""
readonly USB_HOST_ADDRESS=""
readonly USB_VENDOR_ID=""
readonly USB_PRODUCT_ID=""
readonly USB_FILE="/dev/bus/usb/${USB_HOST_BUS}/${USB_HOST_ADDRESS}"

readonly UNSET_WARNING="is unset or empty"

echo "BIOS_LOCATION=${BIOS_LOCATION:?${UNSET_WARNING}}"
echo "IMAGE_LOCATION=${IMAGE_LOCATION:?${UNSET_WARNING}}"
echo "DISK_LOCATION=${DISK_LOCATION:?${UNSET_WARNING}}"

echo "DISK_SIZE=${DISK_SIZE:?${UNSET_WARNING}}"

echo "VM_INITIAL_NAME=${VM_INITIAL_NAME:?${UNSET_WARNING}}"
echo "VM_NAME=${VM_NAME:?${UNSET_WARNING}}"

echo "VM_USER=${VM_USER:?${UNSET_WARNING}}"

echo "IPV4_NETWORK=${IPV4_NETWORK:?${UNSET_WARNING}}"
echo "IPV4_DHCP_FIRST_ADDR=${IPV4_DHCP_FIRST_ADDR:?${UNSET_WARNING}}"
echo "P22_FWD=${P22_FWD:?${UNSET_WARNING}}"
echo "MACHINE_TYPE=${MACHINE_TYPE:?${UNSET_WARNING}}"
echo "MACHINE_CFG=${MACHINE_CFG:?${UNSET_WARNING}}"
echo "CPU_MODEL=${CPU_MODEL:?${UNSET_WARNING}}"
echo "CPU_NUMBER=${CPU_NUMBER:?${UNSET_WARNING}}"
echo "MACHINE_MEMORY_SIZE=${MACHINE_MEMORY_SIZE:?${UNSET_WARNING}}"

abort_if_bios_not_found() {
if [[ ! -e "${BIOS_LOCATION}" ]]; then
echo "UEFI/BIOS not found on '${BIOS_LOCATION}'"
echo "Try 'apt install ovmf' or 'apt install seabios'"
exit 1
fi
}

abort_if_image_not_found() {
if [[ ! -e "${IMAGE_LOCATION}" ]]; then
echo "Installation image not found on '${IMAGE_LOCATION}'"
exit 2
fi
}

abort_if_disk_not_found() {
if [[ ! -e "${DISK_LOCATION}" ]]; then
echo "Virtual Machine disk not found on '${DISK_LOCATION}'"
exit 3
fi
}

abort_if_usb_not_found() {
echo "USB_HOST_BUS=${USB_HOST_BUS:?${UNSET_WARNING}}"
echo "USB_HOST_ADDRESS=${USB_HOST_ADDRESS:?${UNSET_WARNING}}"

if [[ ! -e "${USB_FILE}" ]]; then
echo "USB device not found at '${USB_FILE}'"
exit 4
fi
}

abort_if_usb_misconfigured() {
echo "USB_HOST_BUS=${USB_HOST_BUS:?${UNSET_WARNING}}"
echo "USB_HOST_ADDRESS=${USB_HOST_ADDRESS:?${UNSET_WARNING}}"
echo "USB_VENDOR_ID=${USB_VENDOR_ID:?${UNSET_WARNING}}"
echo "USB_PRODUCT_ID=${USB_PRODUCT_ID:?${UNSET_WARNING}}"

abort_if_usb_not_found

lsusb \
-s "${USB_HOST_BUS}:${USB_HOST_ADDRESS}" \
-d "${USB_VENDOR_ID}:${USB_PRODUCT_ID}" \
>/dev/null
local status=$?

if [[ "$status" != 0 ]]; then
echo "Mismatched vendor or product id"
exit 5
fi
}

readonly SOURCED_ENV_VARS_SH=1
Loading

0 comments on commit 357621e

Please sign in to comment.