MLECO-3035: [Documentation] Add instructions for updating to python3.8 for Ubuntu 18.04 (or older) users

Change-Id: If7bb02f44f8bb7b84b7b7a620e69429a7b5fbb60
Signed-off-by: Isabella Gottardi <isabella.gottardi@arm.com>

6 files changed, 150 insertions, 42 deletions

diff --git a/docs/documentation.md b/docs/documentation.md
index 4bc572a..9fe2b46 100644
--- a/docs/documentation.md
+++ b/docs/documentation.md
@@ -367,8 +367,10 @@ For further information, please see:
   - [Inference results are incorrect for my custom files](./sections/troubleshooting.md#inference-results-are-incorrect-for-my-custom-files)
   - [The application does not work with my custom model](./sections/troubleshooting.md#the-application-does-not-work-with-my-custom-model)
   - [NPU configuration mismatch error when running inference](./sections/troubleshooting.md#npu-configuration-mismatch-error-when-running-inference)
-  - [Problem installing Vela](./sections/troubleshooting.md#problem-installing-vela)
   - [Errors when cloning the repository](./sections/troubleshooting.md#errors-when-cloning-the-repository)
+  - [Problem installing Vela](./sections/troubleshooting.md#problem-installing-vela)
+  - [No matching distribution found for ethos-u-vela==3.3.0](./sections/troubleshooting.md#no-matching-distribution-found-for-ethos_u_vela)
+    - [How to update Python3 package to newer version](./sections/troubleshooting.md#how-to-update-python3-package-to-newer-version)
 
 ## Appendix
 
diff --git a/docs/quick_start.md b/docs/quick_start.md
index dc8df50..d21a554 100644
--- a/docs/quick_start.md
+++ b/docs/quick_start.md
@@ -7,11 +7,11 @@ This documentation assumes that you are using an Arm® *Ethos™-U55* NPU, it is
 sharing SRAM with the Arm® *Cortex®-M55*.
 
 The FVP is also available via Arm Virtual Hardware (AVH) hosted on AWS. This quick start guide can also be executed on an AVH instance
-but requires creation of an AWS account and basic configuration outlined [here](./arm_virtual_hardware.md).
+but requires creation of an AWS account and basic configuration outlined [here](./sections/arm_virtual_hardware.md#getting-started).
 
 To get started quickly, please follow these steps:
 
-1. First, verify that you have installed [the required prerequisites](sections/building.md#Build-prerequisites).
+1. First, verify that you have installed [the required prerequisites](sections/building.md#build-prerequisites).
 
 2. Clone the *Ethos-U* evaluation kit repository:
 
@@ -47,16 +47,16 @@ To get started quickly, please follow these steps:
     ./build_default.py --toolchain arm
     ```
 
-5. Launch the project as explained in the following section: [Deployments](sections/deployment.md#Deployment). In quick
+5. Launch the project as explained in the following section: [Deployments](sections/deployment.md#deployment). In quick
    start guide, we use the keyword spotting application and the FVP.
 
     Change directory to generated cmake build folder which contains the .axf file output from step 4 in it's `bin`
-    subdirectory. Launch the application by passing the axf to the FVP you downloaded when installing the prerequisites. 
+    subdirectory. Launch the application by passing the axf to the FVP you downloaded when installing the prerequisites.
     Alternatively, from the root directory add `<cmake-build-your_config>` to the path to the axf and use one of the
     following commands:
 
     ```commandline
-   From auto-generated (or custom) build directory: 
+   From auto-generated (or custom) build directory:
    <path_to_FVP>/FVP_Corstone_SSE-300_Ethos-U55 -a ./bin/ethos-u-kws.axf
    From root directory:
    <path_to_FVP>/FVP_Corstone_SSE-300_Ethos-U55 -a <cmake-build-your_config>/bin/ethos-u-kws.axf
diff --git a/docs/sections/arm_virtual_hardware.md b/docs/sections/arm_virtual_hardware.md
index dcd5534..23c21c4 100644
--- a/docs/sections/arm_virtual_hardware.md
+++ b/docs/sections/arm_virtual_hardware.md
@@ -2,13 +2,15 @@
 
 - [Overview](./arm_virtual_hardware.md#overview)
   - [Getting started](./arm_virtual_hardware.md#getting-started)
+  - [Useful Links](./arm_virtual_hardware.md#useful-links)
 
 ## Overview
 
-Arm® Virtual Hardware is an accurate representation of a physical System on Chip and runs as a simple application in a Linux environment for easy
-scalability in the cloud and removes dependency from silicon availability. Powered by Amazon Web Services (AWS), developers can launch Amazon Machine Image
-(AMI) running as a virtual server in the cloud. The Arm Virtual Hardware is configured with the Corstone™-300 MPS3 based Fixed Virtual Platform (FVP),
-compiler and other tools.
+Arm® Virtual Hardware is an accurate representation of a physical System on Chip and runs as a simple application in a
+Linux environment for easy scalability in the cloud and removes dependency from silicon availability.
+Powered by Amazon Web Services (AWS), developers can launch Amazon Machine Image
+(AMI) running as a virtual server in the cloud. The Arm Virtual Hardware is configured with the Corstone™-300 MPS3
+based Fixed Virtual Platform (FVP), compiler and other tools.
 
 ### Getting started
 
@@ -19,19 +21,21 @@ To take advantage of Arm Virtual Hardware, you would need to have an AWS account
  3. Subscribe to the Arm Virtual Hardware Amazon Machine Image.
  4. Launch the AWS instance.
 
-
- To access the Arm Virtual Hardware AWS instance via ssh, accept the prompt  to generate a *.pem* key while creating the instance or add it later.
- You can then access the AWS instance over ssh: `$ ssh -i <mykey.pem> ubuntu@<ec2-ip-address>`. 
+ To access the Arm Virtual Hardware AWS instance via ssh, accept the prompt  to generate a *.pem* key
+ while creating the instance or add it later.
+ You can then access the AWS instance over ssh: `$ ssh -i <mykey.pem> ubuntu@<ec2-ip-address>`.
  It may be necessary to change the permissions for mykey.pem with `$ chmod 400 mykey.pem`.
 
-
 ### Useful Links
-Note that you can register to receive free AWS credits to use Arm Virtual Hardware from [here](https://www.arm.com/company/contact-us/virtual-hardware).
+
+Note that you can register to receive free AWS credits to use Arm Virtual Hardware from
+[here](https://www.arm.com/company/contact-us/virtual-hardware).
 
 You can find more information about Arm Virtual Hardware [here](https://arm-software.github.io/VHT/main/overview/html/index.html).
 
-Once you have access to the AWS instance, we recommend starting from the [quick start guide](../quick_start.md#Quick-start-example-ML-application) in order to get familiar
+Once you have access to the AWS instance, we recommend starting from the
+[quick start guide](../quick_start.md#Quick-start-example-ML-application) in order to get familiar
 with the ml-embedded-evaluation-kit. Note that on the AWS instance, the FVP is available under `/opt/FVP_Corstone_SSE-300`.
 
 In order to view the FVP window when launching on the AWS instance a VNC is required.
-See relevant section [here](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-linux-2-install-gui/).
\ No newline at end of file
+See relevant section [here](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-linux-2-install-gui/).
diff --git a/docs/sections/building.md b/docs/sections/building.md
index f4acfa1..301d945 100644
--- a/docs/sections/building.md
+++ b/docs/sections/building.md
@@ -86,6 +86,10 @@ Before proceeding, it is *essential* to ensure that the following prerequisites
     Python 3.8.12
     ```
 
+  > **Note:** If you have an older version of Python installed (< 3.8) see the
+  > [Troubleshooting](./troubleshooting.md#how-to-update-python3-package-to-newer-version)
+  > for instruction on how to update it.
+
 - The build system creates a Python virtual environment during the build process. Please make sure that Python virtual
   environment module is installed by running:
 
diff --git a/docs/sections/troubleshooting.md b/docs/sections/troubleshooting.md
index 8b2646a..998600a 100644
--- a/docs/sections/troubleshooting.md
+++ b/docs/sections/troubleshooting.md
@@ -4,8 +4,10 @@
   - [Inference results are incorrect for my custom files](./troubleshooting.md#inference-results-are-incorrect-for-my-custom-files)
   - [The application does not work with my custom model](./troubleshooting.md#the-application-does-not-work-with-my-custom-model)
   - [NPU configuration mismatch error when running inference](./troubleshooting.md#npu-configuration-mismatch-error-when-running-inference)
-  - [Problem installing Vela](./troubleshooting.md#problem-installing-vela)
   - [Errors when cloning the repository](./troubleshooting.md#errors-when-cloning-the-repository)
+  - [Problem installing Vela](./troubleshooting.md#problem-installing-vela)
+  - [No matching distribution found for ethos-u-vela==3.3.0](./troubleshooting.md#no-matching-distribution-found-for-ethos_u_vela)
+    - [How to update Python3 package to 3.8 version](./troubleshooting.md#how-to-update-python3-package-to-newer-version)
 
 ## Inference results are incorrect for my custom files
 
@@ -67,6 +69,33 @@ INFO - Arm Corstone-300 - AN552 platform initialised
 INFO - ARM ML Embedded Evaluation Kit
 ```
 
+## Errors when cloning the repository
+
+If you see following errors when cloning the repository:
+
+- ```log
+   fatal: unable to access 'https://review.mlplatform.org/ml/ethos-u/ml-embedded-evaluation-kit/':
+   server certificate verification failed. CAfile: /etc/ssl/certs/ca-certificates.crt CRLfile: none
+  ```
+
+  We suggest to update to the latest common CA certificates:
+
+  ```commandline
+  sudo apt-get update
+  sudo apt-get install ca-certificates
+  ```
+
+- ```log
+  fatal: unable to access 'https://review.mlplatform.org/ml/ethos-u/ml-embedded-evaluation-kit/':
+  error:06FFF089:digital envelope routines:CRYPTO_internal:bad key length
+  ```
+
+  We suggest to export the `CURL_SSL_BACKEND` variable as `secure-transport`:
+
+  ```commandline
+  export CURL_SSL_BACKEND="secure-transport"
+  ```
+
 ## Problem installing Vela
 
 During Vela installation, part of the package is compiled and requires libpython3.
@@ -95,31 +124,81 @@ install --record /tmp/pip-record-jidxiokn/install-record.txt --single-version-ex
 
 To solve this issue install libpython3 on the system.
 
-## Errors when cloning the repository
+## No matching distribution found for ethos-u-vela
 
-If you see following errors when cloning the repository:
+Vela 3.3.0 increases Python requirement to at least version 3.8, if not installed on your system the following error will occur:
 
-- ```log
-   fatal: unable to access 'https://review.mlplatform.org/ml/ethos-u/ml-embedded-evaluation-kit/':
-   server certificate verification failed. CAfile: /etc/ssl/certs/ca-certificates.crt CRLfile: none
-  ```
+```log
+python3 -m pip install ethos-u-vela==3.3.0
+ERROR: Could not find a version that satisfies the requirement ethos-u-vela==3.3.0 (from versions: 0.1.0, 1.0.0, 1.1.0, 1.2.0, 2.0.0, 2.0.1, 2.1.1, 3.0.0, 3.1.0, 3.2.0)
+ERROR: No matching distribution found for ethos-u-vela==3.3.0
+```
 
-  We suggest to update to the latest common CA certificates:
+Ensure that the minimum Python 3.8 requirement is installed and it's the default version.
+Check your current installed version of Python by running:
 
-  ```commandline
-  sudo apt-get update
-  sudo apt-get install ca-certificates
-  ```
+```commandline
+python3 --version
+```
 
-- ```log
-  fatal: unable to access 'https://review.mlplatform.org/ml/ethos-u/ml-embedded-evaluation-kit/':
-  error:06FFF089:digital envelope routines:CRYPTO_internal:bad key length
-  ```
+### How to update Python3 package to newer version
 
-  We suggest to export the `CURL_SSL_BACKEND` variable as `secure-transport`:
+1. Check your current installed version of Python by running:
 
-  ```commandline
-  export CURL_SSL_BACKEND="secure-transport"
-  ```
+   ```commandline
+   python3 --version
+   ```
+
+   For example:
+
+   ```log
+   Python 3.6.9
+   ```
+
+2. Install the Python 3.8 packages necessary on the system:
+
+   ```commandline
+   sudo apt-get install python3.8 python3.8-venv libpython3.8 libpython3.8-dev
+   ```
+
+3. Update the `python3` alternatives (set as 1 your previous version displayed at step 1):
+
+   ```commandline
+   sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.6 1
+   sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.8 2
+   ```
+
+4. At the prompt, update the configuration by selecting Python3.8 as the chosen default alternative:
+
+   ```commandline
+   sudo update-alternatives --config python3
+   ```
+
+5. Python3.8 is now set as default you can check it by running:
+
+   ```commandline
+   python3 --version
+   ```
+
+   ```log
+   Python 3.8.0
+   ```
+
+> **Note:** After updating to from Python3.6 Python3.8 it may happen that the `gnome-terminal` or the relative
+> shortcuts doesn't work anymore.
+> If when opening it from XTerm with `gnome-terminal` the following error appear:
+>
+> ```log
+> Traceback (most recent call last):
+>   File "/usr/bin/gnome-terminal", line 9, in <module>
+>     from gi.repository import GLib, Gio
+>   File "/usr/lib/python3/dist-packages/gi/__init__.py", line 42, in <module>
+>     from . import _gi
+> ImportError: cannot import name '_gi' from partially initialized module 'gi' (most likely due to a circular import)
+> (/usr/lib/python3/dist-packages/gi/> __init__.py)
+> ```
+>
+> Modify the `gnome-terminal` script located in `/usr/bin/` and changing the environment (first line of the script)
+> from `#!/usr/bin/python3` to `#!/usr/bin/python3.6`.
 
 Next section of the documentation: [Appendix](appendix.md).
diff --git a/set_up_default_resources.py b/set_up_default_resources.py
index 56363a1..a4c3594 100755
--- a/set_up_default_resources.py
+++ b/set_up_default_resources.py
@@ -27,6 +27,7 @@ from argparse import ArgumentParser
 from argparse import ArgumentTypeError
 from collections import namedtuple
 from urllib.error import URLError
+
 from scripts.py.check_update_resources_downloaded import get_md5sum_for_file
 
 
@@ -345,7 +346,7 @@ def set_up_resources(
     additional_npu_config_names: list = (),
     arena_cache_size: int = 0,
     check_clean_folder: bool = False,
-    additional_requirements_file: str = ''
+    additional_requirements_file: str = "",
 ):
     """
     Helpers function that retrieve the output from a command.
@@ -375,6 +376,18 @@ def set_up_resources(
 
     metadata_dict = dict()
     vela_version = "3.3.0"
+    py3_major_version_minimum = 3  # Python > 3.8 is required
+    py3_minor_version_minimum = 8
+
+    # Is Python minimum requirement matched?
+    py3_version = sys.version_info
+    if (
+        py3_version.major < py3_major_version_minimum
+        or py3_version.minor < py3_minor_version_minimum
+    ):
+        raise Exception(
+            "ERROR: Python3.8+ is required, please see the documentation on how to update it."
+        )
 
     setup_script_hash_verified = False
     setup_script_hash = get_md5sum_for_file(os.path.abspath(__file__))
@@ -401,7 +414,9 @@ def set_up_resources(
                     else:
                         # Check if the set_up_default_resorces.py has changed from last setup
                         setup_script_hash_verified = (
-                            metadata_dict.get('set_up_script_md5sum') == setup_script_hash)
+                            metadata_dict.get("set_up_script_md5sum")
+                            == setup_script_hash
+                        )
         else:
             raise
 
@@ -628,8 +643,12 @@ if __name__ == "__main__":
         "--requirements-file",
         help="Path to requirements.txt file to install additional packages",
         type=str,
-        default=os.path.join(os.path.dirname(os.path.abspath(__file__)),
-                             'scripts', 'py', 'requirements.txt')
+        default=os.path.join(
+            os.path.dirname(os.path.abspath(__file__)),
+            "scripts",
+            "py",
+            "requirements.txt",
+        ),
     )
 
     args = parser.parse_args()
@@ -648,5 +667,5 @@ if __name__ == "__main__":
         args.additional_ethos_u_config_name,
         args.arena_cache_size,
         args.clean,
-        args.requirements_file
+        args.requirements_file,
     )