.. _Palette installation:
Software Installation
#####################
This section describes how to get your host development environment set up with the necessary software including the system requirements
before you begin installing the software. To make sure your system meets all the pre-requisites,
the Palette installation script, ``install.py``, automatically runs through the dependencies checklist.
The pre-requisites for installing the Palette software are listed in the **Installation Requirements** table below.
Installation Requirements
*************************
For more information on requirements, see :ref:`Palette requirements`.
.. list-table::
:widths: 21 79
:header-rows: 1
* - Requirement Type
- Requirement Details
* - Operating Systems
- - |var_palette_reqs_os_ubuntu_versions|
- |var_palette_reqs_os_windows_versions|
* - Docker Engine
- - |var_palette_reqs_docker_ubuntu_versions|
- |var_palette_reqs_docker_windows_versions|
* - Python
- - |var_palette_reqs_python_versions|
* - Open Ports
- - |var_palette_reqs_unused_ports|
* - Firewall access
- - |var_palette_reqs_firewall_port_access|
- |var_palette_reqs_firewall_docker|
- |var_palette_reqs_firewall_ssh|
* - System
- An |var_palette_reqs_system_arch| machine with:
- |var_palette_reqs_system_num_cpu_cores|
- |var_palette_reqs_system_ram_amount|
- |var_palette_reqs_system_storage_amount|
- |var_palette_reqs_system_storage_type|
* - Palette and MLSOC Firmware
- - Palette: |var_palette_reqs_version|
- MLSoC Firmware: |var_palette_reqs_mlsoc_fw_version|
Downloading Palette Software
****************************
.. button-link:: https://docs.sima.ai/pkg_downloads/SDK1.4.0/SiMa_CLI_1.4.0_master_B122.zip
:color: primary
:shadow:
Download Now
.. _docker-group-warning:
Installing on Linux
*******************
**Steps**
#. Unzip the downloaded software to a local directory and change your directory to :substitution-code:`|var_palette_reqs_version|/sima-cli/`:
.. code-block:: console
:substitutions:
sima-user@sima-user-machine:~$ cd Downloads
sima-user@sima-user-machine:~/Downloads$ unzip |var_palette_reqs_version|.zip
Archive: |var_palette_reqs_version|.zip
creating: |var_palette_reqs_version|/
creating: |var_palette_reqs_version|/sima-cli/
inflating: |var_palette_reqs_version|/sima-cli/uninstall.py
inflating: |var_palette_reqs_version|/sima-cli/release-notes.txt
inflating: |var_palette_reqs_version|/sima-cli/stop.py
inflating: |var_palette_reqs_version|/sima-cli/start.py
inflating: |var_palette_reqs_version|/sima-cli/install.py
inflating: |var_palette_reqs_version|/sima-cli/|var_palette_reqs_cli_version|.tar
inflating: |var_palette_reqs_version|/sima-cli/preinstall.py
sima-user@sima-user-machine:~/Downloads$ cd |var_palette_reqs_version|/sima-cli/
sima-user@sima-user-machine:~/Downloads/|var_palette_reqs_version|/sima-cli$ ls
install.py release-notes.txt start.py uninstall.py preinstall.py |var_palette_reqs_cli_version|.tar stop.py
The output of the command will be as shown above. It will take approximately a couple of minutes to complete the Docker image extraction.
.. note::
The Palette software package is delivered using the Docker container application; you must add your user to the Docker group if you have not done it already. Additionally, update your Docker application to the latest version.
Follow the Docker post-installation steps at `official documentation `_. For the Docker Desktop, follow the steps at `official installation docs `_.
To add a user to the Docker Engine see the code below.
.. code-block:: console
sima-user@sima-user-machine:~$ sudo apt-get update
sima-user@sima-user-machine:~$ sudo apt-get install docker-engine
#. If you have previously installed the Palette software, stop the Docker container before proceeding to install this latest version of the Palette software.
This ensures graceful termination of any ongoing processes using the Palette software.
#. Install all the necessary packages. See code below.
.. code-block:: console
sima-user@docker-image-id:~$ sudo apt-get install python3
sima-user@docker-image-id:~$ sudo apt-get install python3-pip
sima-user@docker-image-id:~$ sudo apt-get install net-tools
Dependencies Checklist
======================
The installation script ``install.py`` checks for the system requirements needed to ensure all dependencies are met for a successful installation of the Palette software.
See the System Requirements Report below.
.. code-block:: console
:substitutions:
sima-user@sima-user-machine:~/Downloads/|var_palette_reqs_version|/sima-cli$ python3 install.py
|var_palette_reqs_version| Palette Dependency Checklist
**********************************
This script checks the necessary dependencies a system needs to meet to ensure compatibility and
readiness for Palette installation and use. Please review and verify each of the following dependencies.
Once all the dependencies are verified, a final report will be displayed. And the installation script automatically proceeds with installing the software.
.. code-block:: console
___________________________________________________________________________
SYSTEM REQUIREMENTS REPORT
+------------------+-------------------+----------------------+----------+
| Component | Requirement | Found | Result |
+==================+===================+======================+==========+
| OS Version | 20.04/22.04 | 22.4 | [PASS] |
+------------------+-------------------+----------------------+----------+
| Docker | v20.10.21 | 24.0.7 | [PASS] |
+------------------+-------------------+----------------------+----------+
| Python | 3.8.10 | 3.10.12 | [PASS] |
+------------------+-------------------+----------------------+----------+
| CPU/RAM | 4 Cores/16 GB RAM | 6 Cores/33.35 GB RAM | [PASS] |
+------------------+-------------------+----------------------+----------+
| Free space | 30 GB free | 31.93 GB | [PASS] |
+------------------+-------------------+----------------------+----------+
| Firewall status | disabled | disabled | [PASS] |
+------------------+-------------------+----------------------+----------+
| Port 80 | Not used | Not used | [PASS] |
+------------------+-------------------+----------------------+----------+
| SSH to localhost | Possible | Possible | [PASS] |
+------------------+-------------------+----------------------+----------+
----------------------------------------------------------------------------------------------------
Result:
[PASS] All system requirements are successfully met. You may proceed to Palette installation.
However, if you wish to only check for system readiness, pass the ``--check-dependencies`` flag when running the ``install.py`` script as shown below.
The ``install.py`` script verifies all the dependencies and then stops; it does not proceed with installation of the software.
.. code-block:: console
:substitutions:
sima-user@sima-user-machine:~/Downloads/|var_palette_reqs_version|/sima-cli$ python3 install.py --check-dependencies
Installing the Software
=======================
Follow the steps below to install the Palette software.
**Steps**
#. Run ``python3 install.py`` and set up the Docker shared directory.
In this step you will set the work directory which will be mounted inside the Docker container as shown in the prompt below.
This work directory will be shared between the Docker SDK image and the host machine; and in this folder you can place most of your development
files so that they persist even after the container is shut down. In this case, the default directory is shown, but you may choose any other directory on the host machine.
.. code-block:: console
:substitutions:
sima-user@sima-user-machine:~/Downloads/|var_palette_reqs_version|/sima-cli$ python3 install.py
Checking if SiMa CLI |var_palette_reqs_version| is already installed...
Enter work directory [/home/sima-user/workspace]:
Loading Docker image version |var_palette_reqs_version|...
This step may take a few minutes to complete. Thank you for your patience.
Image loaded successfully.
Checking SiMa SDK Bridge Network...
SiMa SDK Bridge Network found.
Creating and starting the Docker container...
1587c3ed1226e4a1c66bc86b035786bc61716a73444d6f7828e279de56e51373
Successfully copied 2.56kB to /home/sima-user/Downloads/|var_palette_reqs_version|/sima-cli/passwd.txt
Successfully copied 4.1kB to simaclisdk_|var_palette_reqs_version|:/etc/passwd
Successfully copied 2.56kB to /home/sima-user/Downloads/|var_palette_reqs_version|/sima-cli/shadow.txt
Successfully copied 3.58kB to simaclisdk_|var_palette_reqs_version|:/etc/shadow
Successfully copied 2.05kB to /home/sima-user/Downloads/|var_palette_reqs_version|/sima-cli/group.txt
Successfully copied 3.58kB to simaclisdk_|var_palette_reqs_version|:/etc/group
Successfully copied 2.56kB to /home/sima-user/Downloads/|var_palette_reqs_version|/sima-cli/sudoers.txt
Successfully copied 3.58kB to simaclisdk_|var_palette_reqs_version|:/etc/sudoers
Successfully copied 3.07kB to simaclisdk_|var_palette_reqs_version|:/home/docker/.simaai/.port
Installation successful. To log in to the Docker container, please use the './start.py or python3 start.py'
Your local work directory '/home/sima-user/workspace' has been mounted to '/home/docker/sima-cli'
.. note::
The default work directory suggested by the install script will not be the same for all users.
.. _Palette CLI start:
Running/Launching Software
==========================
**Steps**
#. Start the Docker container and log in.
.. code-block:: console
:substitutions:
sima-user@sima-user-machine:~/Downloads/|var_palette_reqs_version|/sima-cli$ python3 start.py
Set no_proxy to localhost,127.0.0.1
Checking if the container is already running...
==> Container is already running. Proceeding to start an interactive shell.
sima-user@docker-image-id:/home$: ps aux
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
sima-user 1 4.6 0.1 30928 22596 pts/0 Ss+ 05:52 0:00 /usr/bin/python3 /usr/bin/supervisord -n -c /etc/supervisor/conf.d/
sima-user 7 0.0 0.0 7244 3712 pts/1 Ss 05:52 0:00 bash
sima-user 21 199 1.2 7570224 205076 pts/0 Sl 05:52 0:03 java -jar rpm-service.jar
sima-user 22 205 1.2 7570224 210388 pts/0 Sl 05:52 0:04 java -jar plugin-compilation.jar
sima-user 23 33.0 0.0 2908 1792 pts/0 S 05:52 0:00 /usr/local/bin/device_status_shadow -v
sima-user 24 221 1.2 7570224 209960 pts/0 Sl 05:52 0:04 java -jar gst-generator-service.jar
sima-user 25 35.5 0.0 2908 1792 pts/0 S 05:52 0:00 /usr/local/bin/local_port_forwarding -v
sima-user 26 210 1.3 5495088 215624 pts/0 Sl 05:52 0:04 java -Xmx2048m -jar packaging-service.jar
sima-user 27 38.5 0.0 2908 1792 pts/0 S 05:52 0:00 /usr/local/bin/pcie_forwarding -v
sima-user 28 140 0.8 7570224 145372 pts/0 Sl 05:52 0:02 java -jar performance-estimator.jar
sima-user 29 19.0 0.0 2908 1664 pts/0 S 05:52 0:00 /usr/local/bin/remote_port_forwarding -v
sima-user 127 31.0 0.6 479800 99848 pts/0 Sl 05:52 0:00 /usr/local/bin/remote_port_forwarding -v
sima-user 128 61.0 0.7 129396 115032 pts/0 S 05:52 0:00 /usr/local/bin/device_status_shadow -v
sima-user 129 57.0 0.7 500208 116800 pts/0 Sl 05:52 0:00 /usr/local/bin/local_port_forwarding -v
sima-user 141 53.0 0.6 480952 104888 pts/0 Sl 05:52 0:00 /usr/local/bin/pcie_forwarding -v
sima-user 164 0.0 0.6 279012 105364 pts/0 Sl 05:52 0:00 /usr/local/bin/local_port_forwarding -v
sima-user 187 0.0 0.0 8896 2944 pts/1 R+ 05:52 0:00 ps aux
Verifying the Installation
==========================
**Steps**
#. To verify installation, run the build and deploy software contained in the Palette software, the ``mpk`` package.
.. code-block:: console
sima-user@docker-image-id:/home$ mpk --help
usage: mpk [-h] [-d] [-q] [-v] {pe,model,remote-log,device,create,debug,deploy,firmware-upgrade,kill,launch,list,remove} ...
SiMa CLI Tool
options:
-h, --help show this help message and exit
-d, --debug full application debug mode
-q, --quiet suppress all console output
-v, --version show program's version number and exit
sub-commands:
{pe,model,remote-log,device,create,debug,deploy,firmware-upgrade,kill,launch,list,remove}
pe pe controller
model model controller
remote-log remote-log controller
device device controller
create create mpk from directory
debug debug a running package or deploy mpk in debug mode
deploy Deploy mpk to target
firmware-upgrade Upgrade or Reset a device
kill Kill the current running package.
Note: 1. In case -i/--id parameter isn't provided, it will kill the latest active deployment.
2. Incase only -i/--id parameter is provided, the latest deployed mpk (to a target) with the given id is killed.
3. In case both -i/--id and -t/--target parameters are provided, only the latest active deployment with given id on given target will be killed.
launch Launch previously deployed mpk
list List the current running packages
remove Remove previously deployed mpk
Installing on Windows using Hyper-V
***********************************
The Palette software supports Windows OS in Hyper-V mode, the setup and installation steps are described below.
.. note::
The Docker application (Docker Desktop or Docker Engine) must be installed before installing the Palette software.
Follow the link below for downloading and installing the Docker Desktop application.
https://docs.docker.com/desktop/install/windows-install/
Use the build version 4.26.1 or lower. See, https://docs.docker.com/desktop/release-notes/ for details.
In the **Configuration** window, do not click in the first checkbox, thereby the Hyper-V option will be enabled in the Docker Desktop application.
.. image:: media/Palette_windows_Hyper_V.png
:scale: 50%
:align: center
**Steps**
#. Reboot your PC and make sure that the Hyper-V option is enabled automatically as shown in the below image. If not, please select Hyper-V manually.
.. image:: media/Palette_windows_Hyper_V.png
:scale: 50%
:align: center
#. Launch the Docker Desktop application and open settings. Under resources, increase the memory to 6 GB as shown in the below image and choose ``Apply & Restart`` option.
.. image:: media/docker_resources.png
:scale: 50%
:align: center
#. Unzip the Palette software file.
#. Launch Windows powershell as an administrator and navigate to the sima-cli folder of the downloaded Palette software uncompressed file.
#. Make sure Python is installed on the computer by running the below command in powershell.
.. code-block:: powershell
PS C:\Users\SiMaUser> python --version
Python 3.10.8
#. Launch the Docker Engine application and continue without sign-in if required.
#. Install the Palette software.
.. code-block:: powershell
:substitutions:
PS C:\Users\SiMaUser\Downloads\|var_palette_reqs_version|\sima-cli> python ./install.py
#. Enter the workspace directory of your choice (this is the directory which gets mounted in the container) and wait untill installation completes. Typical flow is mentioned below.
#. If prompted for file sharing permission from Docker, accept it.
.. image:: media/docker_permissions.png
:scale: 50%
:align: center
#. Launch the Palette software.
.. code-block:: powershell
:substitutions:
PS C:\Users\SiMaUser\Downloads\|var_palette_reqs_version|\sima-cli> python ./start.py
Uninstalling the Palette Software
*********************************
#. Run the following command.
.. code-block:: console
:substitutions:
sima-user@sima-user-machine:/Downloads/|var_palette_reqs_version|/sima-cli$ python ./uninstall.py