Difference between revisions of "PC prerequisites"

[quality revision] [quality revision]
m
m (Undo revision 76676 by Sebastien Gandon (talk))
(Tag: Undo)
 

Template:ArticleMainWriter Template:ArticleApprovedVersion

Info white.png Information
Recommended setup: Native Linux® PC

1 Purpose[edit]

This article explains and describes the host PC hardware and software configuration required to be able to activate and run the STM32 MPU platforms.

2 Recommended PC configurations[edit]

The PC requirements depend on the Package you want to use.

The table below guides through the selection and configuration of the host PC environment according the targeted Package:

Host
Environment
environment Starter Package Developer Package Distribution Package
Windows® (64 bits)
 Tested with
Windows7
Windows 7 and
Windows10
Windows 10
 Prefered
 Preferred version is Windows 10 native Virtual
Machine
machine Virtual Machine
Linux (64 bits)
 Tested with Ubuntu
16
® 18.04 and 20.04
native
Native
native
Native + additional packages (see Linux PC chapter ) native + additional packages (see Linux PC chapter )


There are no absolute minimal requirements regarding the PC hardware configuration, however . However ST recommends to meet or exceed the following hardware configurations requirements when using the Developer Package or Distribution Package.

The table below correspond corresponds to the minimal validated configuration:

Hardware item Minimal validated configuration Comments /
Recommandations
Recommendations
CPU core i5-2540M @ 2.
6GHz
6 GHz
2 cores (4 threads)
3MB
3-Mbyte cache 64
bits
-bit instruction set is mandatory
8 cores/threads or more is a good
config moreover
configuration for Developer Package and Distribution Package.
RAM
8GB
8 Gbytes
16GB
16 Gbytes or more
is
are recommended especially for Virtual
Machine
machine setup, Developer Package and Distribution Package.
Hard
Drive
drive
320GB
320 Gbytes
1TB is probably a better config when using
1 Tbytes is the best suited configuration for Distribution Package

3 Linux® PC[edit]

A Linux PC with Ubuntu 1618.04 is the recommended setup. Other Ubuntu revisions should are also be supported , please (refer to Yocto Manualreference manual[1]) .

Info white.png Information
ecosystem release v2.1.0 More info.png

ST solutions are tested and validated on a Linux PC running Ubuntu 18.04 LTS (and Ubuntu 20.04 LTS).

Info white.png Information
ecosystem release v2.0.0 More info.png

ST solutions are tested and validated on a Linux PC running Ubuntu 18.04 LTS (and Ubuntu 16.04 LTS).


3.1 Check Checking Internet access[edit]

  • An Internet access through http and https protocols must be provided.

Required at least for Developer Package and Distribution Package at least.

The command below allows to check for Internet enables checking internet access through http/https protocols:

PC $> wget -q www.google.com && echo "Internet access over HTTP/HTTPS is OK !" || echo "No internet access over HTTP/HTTPS ! You maymight need to set up a proxy."

If a an 'OK' message is returned, the network is well configured. In such case, skip the rest of this section and jump to next one (Install extra packages).

Any other situation likely indicates the need for that a proxy is required for http/https protocols.
The best solution to set a proxy for http/https protocols is via the shell variables http_proxy and https_proxy:

PC $> export http_proxy=http://<MyProxyLogin>:<MyProxyPassword>@<MyProxyServerUrl>:<MyProxyPort>
PC $> export https_proxy=http://<MyProxyLogin>:<MyProxyPassword>@<MyProxyServerUrl>:<MyProxyPort>

Since your password (<MyProxyPassword>) might contain "special characters", translate it into ASCII hexacode. To do this, use the command below:

PC $> echo -n " <MyProxyPassword>" | od -A n -t x1 -w128 | head -1 | tr " " "%"


Check again the Internet access with by using the following command:

PC $> wget -q www.google.com && echo "Internet access over HTTP/HTTPS is OK !" || echo "No internet access over HTTP/HTTPS ! You maymight need to set up a proxy."


  • Internet access for sudo commands

Required for Distribution Package.


By default, sudo commands are executed in the root user environment; by default, no Internet proxy settings are applied for root user users.
Root user should users must be able to browse Internet , after creation of having created an alias passing the proxy settings on sudo command commands:

PC $> alias sudo='sudo http_proxy=$http_proxy'

Check that the sudo commands is are successful (requires Internet access):

PC $> sudo apt-get update


  • Internet over git://, ssh:// and others specifics protocols

Required for Distribution Package.
In addition to http/https protocols (used in 90% of the Internet traffic), some other protocols like such as git:// or ssh:// may might be required.

For example, in the context of the Distribution Package, some "git fetch" commands could might require "git:// protocols".
In order to To support these protocols through a proxy, the best way is to directly setup the proxy in the $HOME/.gitconfig file (core.gitproxy) and use a tool like such as cockscrew[2] in order to tunnel the git:// flow into the http flow:

PC $> sudo apt-get update
PC $> sudo apt-get install corkscrew

PC $> git config --replace-all --global core.gitproxy "$HOME/bin/git-proxy.sh"
PC $> git config --add --global core.gitproxy "none for <MyPrivateNetworkDomain>" (optionnaloptional, and for example .st.com, or localhost, ...)
PC $> echo 'exec corkscrew <MyProxyServerUrl> <MyProxyPort> $* $HOME/.git-proxy.auth' > $HOME/bin/git-proxy.sh
PC $> chmod 700 $HOME/bin/git-proxy.sh
PC $> echo '<MyProxyLogin>:<MyProxyPassword>' > $HOME/.git-proxy.auth
PC $> chmod 600 $HOME/.git-proxy.auth

Here is a Use the command below to test this the proxy settings:

PC $> git ls-remote git://git.openembedded.org/openembedded-core > /dev/null && echo OK || echo KO

The command should return returns 'OK' , else if the proxy settings are wrongcorrect.

3.2 Install Installing extra packages[edit]

Required for Developer Package and Distribution Package.

In order to do Additional Ubuntu packages must be installed to perform basic development tasks, basic cross-compilation (via Developer Package) or more complex cross-compilation such as OpenEmbedded does (via Distribution Package), some extra Ubuntu packages should be installed: :

PC $> sudo apt-get update
PC $> sudo apt-get install sedgawk wget curl cvs subversion git-core coreutilsdiffstat unzip texi2html texinfo docbookgcc-utilsmultilib gawk pythonbuild-pysqlite2essential diffstatchrpath help2mansocat makecpio gccpython3 buildpython3-essential g++ desktop-file-utils chrpath libxml2-utils xmlto docbook bsdmainutils iputils-ping cpio python-wand python-pycryptopp python-crypto
pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint3 pylint xterm
PC $> sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto

  • Packages needed for some "Developer Package" use cases:
PC $> sudo apt-get install libsdl1.2libncurses5 libncurses5-dev xterm corkscrew nfs-common nfs-kernel-serverlibncursesw5-dev libssl-dev linux-headers-generic u-boot-tools device-tree-compiler mercurial u-boot-tools libarchive-zip-perl
bison flex g++ libyaml-dev

  • Package for repo (used to download the "Distribution Package" source code):
Please follow the installation instructions described in repo.
 For Ubuntu 16.04, use the legacy repo old-repo-python2 chapter

  • Useful tools:
PC $> sudo apt-get install ncurses-dev bc linux-headers-generic gcc-multilib libncurses5-dev libncursesw5-dev lrzsz dos2unix lib32ncurses5 repo libssl-devcoreutils bsdmainutils sed curl bc lrzsz corkscrew cvs subversion mercurial nfs-common nfs-kernel-server libarchive-zip-perl dos2unix texi2html diffstat libxml2-utils

You can also install a Java Runtime Engine that is required for STM32CubeMX and STM32CubeProgrammer

PC $> sudo apt-get install default-jre

3.2.1 Install Installing extra packages for AndroidTM[edit]

Android logo.png Below information is related to the Android™ distribution
Before downloading and building the STM32MPU distribution for Android™, make sure your system meets the following requirements:
  • A 64-bit Linux® environment.
  • At least 150 Gbytes of free disk space. If you conduct multiple builds, even more space is required.
  • At least 8 Gbytes of RAM/swap. If you are running Linux on a virtual machine, at least 16 Gbytes of RAM/swap are required.

For more details, refer to the requirements page of the AOSP website.


Use the following commands to install the packages required to build an environment for Android (Distribution Package), after having installed the required packages listed on Android website:

sudo apt-get update
sudo apt-get install chrpath curl libxml2-utils gdisk pv python-pycryptopp python-crypto autotools-dev automake libusb-1.0-0-dev


To ensure USB communication (with ADB) between the host and the device, see ADB § Device Connection.


To run Android-provided tests (CTS and VTS), see Android Platform Testing.

At this stage: Your environment is ready for Android build, debug and test.


3.3 Additionnal Additional configurations[edit]

  • Allow Allowing up to 16 partitions per mmcMMC

By default , on Linux system, a maximum of 8 MMC partitions are allowed on mmcLinux systems. All Packages (such as Starter Package, ...) need more than 10 partitons for the storage device. In order to To extend the number of partitions per device to 16, the following options must be added to modprobe:

PC $> echo 'options mmc_block perdev_minors=16' > /tmp/mmc_block.conf
PC $> sudo mv /tmp/mmc_block.conf /etc/modprobe.d/mmc_block.conf
  • Check Checking for locale setup

Required for Distribution Package.

The locale setting is used by some applications/commands (including by Distribution Package applications/commands).
Verify that the locale settings are as follows:

PC $> locale
LANG=en-US.UTF-8

In case If the locale command returns a different configuration than the one shown above, reconfigure it must be reconfigured as follows:

PC $> sudo update-locale LANG=en_US.UTF-8

Then reboot the PC.

  • Add user Adding users in basics groups

The user login should must belong to the basic Linux groups such as disk, tty, dialout or plugdev
Use the groups command groups to list groups for the current user:

PC $> groups

If needed, add user to the missing <groups>:

PC $> sudo adduser $USER <group>

Then reboot the PC.

3.4 Setup Seting up Git user information[edit]

Required for Developer Package and Distribution Package.
The User user Information is are needed by git[3] in case if commit and/or push commands are being used used:


PC $> git config --global user.name "Your Name"
PC $> git config --global user.email "you@example.com"

4 Windows PC[edit]

Starter Package may run on Windows.
Developer Package and Distribution Package require a Linux environment.

Warning white.png Warning
ST solutions, while reportedly functional when running on a Linux Virtual machine, are only validated for Linux native setups. ..

There are several ways to run Linux system on top of a Windows host PC, . ST recommends to use a Virtual Machine System:

  1. Install a virtual machine such as VMWare [4]
  2. Setup a 64 bits-bit Ubuntu image compatible with your virtual machine

ST, in an experimental way, has also run Developer Package and Distribution Package on WSL2 (Windows Subsystem for Linux 2). Refer to WSL2 chapter.

4.1 Virtual Machine installationmachine system[edit]

4.1.1 Installing the virtual machine[edit]


ST has selected VMWare as Linux virtual machine solution.

VMWare is a commercial company specialized in virtualization solutions. The available solutions to support a virtual Linux machine on a Windows PC are:

  • VMWare Workstation Player (paid solution) for commercial use (download here [5])
  • VMWare Workstation Player (free solution) for home use (download here [6])

Please proceed with the installation of the virtual machine.

Before running the virtual machine, make sure the virtualization is activated in the BIOS (it should be activated by default for any retail PC).



4.1.2

Download

Downloading the Ubuntu image for the virtual machine[edit]

The "osboxes.org" [7] website provides virtual machine images compatible with VMWare(*.vmdk).

Only Ubuntu 16ecosystem release v2.1.0 More info.png : Setup have been validated and tested on Ubuntu 18.04 (64bit) has 64bits) and Ubuntu 20.04 (64bits).
ecosystem release v2.0.0 More info.png : Setup have been validated and tested on Ubuntu 18.04 (64bits) and Ubuntu 16.04 (64bits).

Download the 64 bits -bit Ubuntu image available at [8] and, then:

  1. Unzip the downloaded file
  2. In VMware, create a virtual machine using the Ubuntu virtual disk downloaded from osboxes.org.

The recommended usage is to dedicate, at least, half of the host machine to the virtual machine:

- CPU: 2 cores at least,
- RAM: 6 Gbytes or more is a good choice (the more RAM allocated to Virtual Machine the better - the RAM allocated to Virtual Machine must be 2GB minimumat least 4 Gbytes),
- Network: NAT is a good and an easy way to benefit formfrom a network connection within the virtual machine.

Virutal The virtual size of the virtual disk downloaded from osboxes.org is about 500GB500 Gbytes. Even if, at beginning, the real size of the file of the virtual disk is less at beginning, the size could growth can grow up to 500GB 500 Gbytes over compiling distribution package compiling or package development package.

Info white.png Information
For VMware, you need first to create a default virtual machine, then add the previously downloaded .vmdk file, previously downloaded.

Please refer to the VMwarePlayer screenshot tutorial.

4.1.3

Launch of

Launching Ubuntu image[edit]

Warning white.png Warning
For "AZERTY" keyboard users:

The default keyboard configuration is "QWERTY".
In order to To configure the keyboard for to "AZERTY", start by opening a session (take care that the keyboard layout is QWERTY).
TIP: the password for the default user "osboxes.org" is "osboxes.org".
TIP: the '.' character is obtained by clicking ':' on an AZERTY keyboard configured in QWERTY.
Once the session is openedopen, click the 'En' icon on top/right of the screen, select the French ('Fr') keyboard layout and move it to the first position in the list.
Optionally the 'En' keyboard can be completely removed. If the 'Fr' option is not present, it can be added with the 'Text entry setting' menu.

Default 'Ubuntu Credentials of the Ubuntu ' are set to "osboxes.org" for both login and password.

Warning white.png Warning
Adjust Adjusting screen resolution:

The (default) resolution used by the virtual machine is 800x600 (smallest available). It is not automatically adjusted to the display resolution. In order to To adjust the resolution, click the "settings" icon ('toothed wheel' on top/right of the screen), then "system settings ..." > "display" and select the appropriate resolution for the display (do not to forget to click the "Apply" button on bottom/left of the "Screen Resolution Setting" window).

For a better experience with the VMware virtual machine, install "vmware-tools" in order to be able to use the clipboard to drag-and-drop and copy/paste files between VMware and Windows. A step-by-step installation procedure of vmware-tools is available in the document: PreRequisite-Vmware-tools.pdf.


The virtual machine is now up and running!

The Ubuntu setup must be finalized according recommendations provided in Linux PC chapter

4.4 References[edit]

  • https://www.yoctoproject.org/docs/2.4.3/ref-manual/ref-manual.html#detailed-supported-distros
  • Warning white.png Warning
    USB connection speed:

    A USB connection is required to access STLink (debugger and serial port) and by STM32CubeProgrammer. The speed of the USB connection between Linux running in the virtual machine and the external USB devices can be severely impacted by the following factors:

    • the virtual machine USB setup
    • the USB controller in the host PC
    • the USB device connected to host PC
    • any USB hub between the USB host and the USB device.

    If the speed of your USB connection is too low:

    • try different USB configurations of the virtual machine;
    • connect the USB device directly to the host USB port (without any USB hub);
    • try connecting the USB device to another USB port of the host (some PC have different USB controller on different USB port).

    4.2 WSL2 (experimental)[edit]

    Even if STMicroelectronics strongly recommends to use a Linux® environment, the Developer Package and Distribution Package work on WSL2 (Windows Sub-system Linux 2) environment. WSL is a feature provided by Windows 10®.
    WSL2 is a new version of the architecture that powers the Windows subsystem for Linux to run ELF64 Linux binaries on Windows (more details on aka.ms/wsl2). It is available on Windows 10 since build 18917. The Developer Package successfully runs on WSL2 but unsuccessfully on WSL.

    • Installing WSL2 :
    • WSL2 limitations :
      • Up to now (September 2019), WSL2 does not support hardware such as USB or serial devices (more details).
        This means that STM32CubeProgrammer must be used through native Windows.
      • WSL2 files are not browsable from Windows native file explorer.
        To share files between WSL2 and Windows, it is recommend to use the mount point /mnt/c from WSL2 and perform copies.
    • Tips for using WSL2 :

    4.3 References[edit]


    <noinclude>
    
    {{ArticleMainWriter | SebastienG}}
    {{ArticleApprovedVersion | SebastienG | NathalieS, ChristopheP, DenisH , ChristopheM , GeraldB, Jean-ChristopheT | 24Jan'18 |  BrunoB - 22Aug'18 - 8347 | 18Sep'18}}
    [[Category:MainMenu]]
    [[Category:Getting started with this user guide|02]]
    [[Category:Getting started with ST boards]]</noinclude>
    
    
    {{{{Info|Recommended setup: Native Linux<sup>&reg;</sup> PC}}
    == Purpose ==
    This article explains and describes the host PC hardware and software configuration required to be able to activate and run the STM32 MPU platforms.
    
    == Recommended PC configurations ==
    The PC requirements depend on the [[Which Package better suits your needs|Package you want to use]].
    
    The table below guides through the selection and configuration of the host PC environment according the targeted Package:
    {| class="wikitable" align=center text=center width=100%
    |-
    ! Host Environmentst-table" 
    |-
    ! Host environment !! Starter Package !! Developer Package !! Distribution Package
    |-
    | '''Windows<sup>&reg;</sup> (64 bits) '''<br>&emsp;Tested with Windows7 Windows 7 and Windows10Windows 10<br>&emsp;PreferedPreferred version is Windows 10 || native || [[PC_prerequisites#Virtual Machine installation|Virtual Machine]] || [[PC_prerequisites#Virtual Machine installationprerequisites#Installing the virtual machine|Virtual machine]] || [[PC_prerequisites#Installing the virtual machine|Virtual Machine]] 
    |-
    | '''Linux (64 bits)'''<br>&emsp;Tested with Ubuntu 16.04 || native || native<sup>&reg;</sup> '''18.04''' and 20.04|| Native || Native + additional packages (see [[#Linux PC|Linux PC]] chapter ) || native + additional packages  (see [[#Linux PC| Linux PC]] chapter )
    |}
    
    There are no absolute minimal requirements regarding the PC hardware configuration, however. However ST recommends to meet or exceed the following hardware configurationsrequirements when using '' the ''Developer Package'' or ''Distribution Package''.
    
    The table below correspondcorresponds to the minimal validated configuration:
    {| class="wikitable" align=center text=center width=100%st-table"|-
    ! Hardware item !! Minimal validated configuration !! Comments / RecommandationsRecommendations
    
    |-
    | CPU || core i5-2540M @ 2.6GHz 6 GHz <br> 2 cores (4 threads) <br> 3MB3-Mbyte cache || '''64 bits -bit instruction set is mandatory''' <br> '''8 cores/threads or more''' is a good config moreover configuration for ''Developer Package'' and ''Distribution Package''.  
    |-
    | RAM || 8GB || '''16GB or more''' is8 Gbytes || '''16 Gbytes or more''' are recommended especially for ''Virtual Machinemachine'' setup , ''Developer Package'' and ''Distribution Package''.
    |-
    | Hard Drive || 320GB || '''1TB''' is probably a better config when using ''Distribution Package''  
    |}
    
    ==Linux PC==
    {{ReviewsComments|RJE: "The prerequisites are obviously not the same when you installed SDK rather than Distribution Package: SDK comes with cross compile toolchain and supposed to provide all needed tools... while Distribution Package needs specific tools on host to generate (at least) the cross tool chain... So i don't think it's really usefull to ask customer to install all these packages on host for SDK only.<br>
    
    I'm just wondering if we have to split or not host prerequisites according to Package installed: dev or distribution, as they are not requesting the same tools...<br>
    
    SGA, 28Jun18: To split the needed packages by kind of Package is quiet hard to do. Integration have taken an action to do it later. Just keep this comment in the meanwhile}}
    
    A Linux PC with '''Ubuntu 16.04''' is the recommended setup. Other Ubuntu revisions should also be supported, please refer to Yocto Manual<ref> https://www.yoctoproject.org/docs/2.4.3/ref-manual/ref-manual.html#detailed-supported-distros </ref> .<br>
    
    {{Info| drive || 320 Gbytes || '''1 Tbytes''' is the best suited configuration for ''Distribution Package''  
    |}
    
    ==Linux<sup>&reg;</sup> PC==
    A Linux PC with '''Ubuntu 18.04''' is the recommended setup. Other Ubuntu revisions are also supported (refer to Yocto reference manual<ref>{{DocSource | domain=Yocto Project | path=ref-manual/ref-manual.html#detailed-supported-distros | text=Supported Linux Distributionsl}}</ref>) .<br>
    
    
    {{Info|'''{{EcosystemRelease | revision = 2.1.0}}'''
    ST solutions are tested and validated on a Linux PC running Ubuntu 18.04 LTS (and Ubuntu 20.04 LTS).}}
    {{Info|'''{{EcosystemRelease | revision = 2.0.0}}'''ST solutions are tested and validated on a Linux PC running Ubuntu 16.04 LTS18.04 LTS (and Ubuntu 16.04 LTS).}}
    
    {{InternalInfo|ST employees who are connected at ato an ST network (ST-Ubuntu or VMWare) need to configure itstheir environment first:{{ReviewsComments|E Combette: please specify this apply on native PC Ubuntu and also VM Ubuntu  }}* Open a shell with bash:
    
    The shell to use is bash, which could might not be not the default shell on ST-UBUNTUUbuntu PCs.<br>
    
    First, open a terminal and check the default shell by typing ''export'. ''. ''export'' is not availbleavailable in non -bash compliant shell (like shells (such as csh or tcsh).
    If 'export' command is not found by the shell, there are 2 options:
    :# ask for the shell does not find the ''export'' command, there are two options:
    :# Ask ICT to change the default shell to bash on your PC.
    
    :# switchSwitch to a bash shell by typing ''bash' (to not break scp, to avoid tricky env issue by experience '. To avoid breaking scp as well as tricky env issues, DO NOT invoke bash from your .profile, .cshrc or any others file)other files.
    
    
    * Add some proxy and repo configuration functions to the bash shell (. This has to be done once at first image startup):<br>
    The functions are available in the file: [[File:stenv.sh]] $> mkdir -p $HOME/bin
     $> wget http://intranet.lme.st.com:8000/php-bin/ug_mcdmpu/images/0/02/Stenv--no-check-certificate https://citools.st.com/artifacts/artifactory/oeivi-codex-st-com/HostEnv/stenv/stenv.sh -O $HOME/bin/stenv.sh
     $> echo 'export STENV_NOGERRIT{{=}}yes' >> $HOME/.bashrc (if you do not need to access to code on codex/gerrit repository)
     $> echo 'source $HOME/bin/stenv.sh' >> $HOME/.bashrc
     $> exit (new terminal will source the stenv.sh)Now by opening a new shell, the The proxy and git/github/repo should be set correctly
     {{ReviewsComments|HuguesF: On a newly installed ST-PC Ubuntu-16.04, sudo password is claimed:
     Check Internet connection ...	INSTALLATION of corkscrew ... [sudo] password for frq08990: 
    Apres l'install de corkscrew et git (sudo apt-get install corkscrew git) on va plus loin:<pre>
    
    Check Internet connection ...  OK(proxy: appgw.gnb.st.com:8080)
    Check for your installed packages ...
    Check for your installed packages ... DONE
    Check for your git/github/repo (settings)...
    Your Fisrtname LASTNAME [] : Hugues FRUCHET
    Your email [] : hugues.fruchet@st.com
    Your SSH username (used for codex/gerrit) [] : frq08990
    ssh_askpass: exec(/usr/bin/ssh-askpass): No such file or directory
    ssh_askpass: exec(/usr/bin/ssh-askpass): No such file or directory</pre>
    
    Attention il y a une typo dans le script:
     Your '''FiSRtname''' LASTNAME
    }}
    is now correctly set when you open a new shell. 
    * Answer the questions of [[File:''stenv.sh]] (sourced automatically '' (automatically  sourced from your .bashrc) which setsto set the proxy (if needed) and sets , codex/gerrit ssh keys, the git configs, git proxy and github credentials. However you You can force at any moment the reconfiguration of any setting by running the following commands (provided by stenv.sh):<br>
    
     $> stenv-gitrepo_config -f # Sets gitconfig file and github credentials
     $> stenv-proxy_config # Sets proxy credentials
     $> stenv-github_config # sets github.com credentials
     $> stenv-github_clear_credential # clear proxy, github.com, codex/gerrit credentials
    
    '''appgw.gnb.st.com is the 'hardcoded' proxy url used in stenv.sh, if. If you use another proxy please , edit the stenv.sh file.<br>Moreover, by By default st proxyST proxies (appgw.gnb.st.com, and others) isare not open by default for to all employees, so you may need to ask for request access (via to appgw.gnb.st.com through the http protocol (go to [http://flow.st.com/st/UP/EICOM/Lists/RequestList/NewForm.aspx FLOW]) to appgw.gnb.st.com through http protocol (even though it is not used yet, you can . Even if you do not use it yet, ask for the git protocol tool).'''
    
    * TIPS:
    :* mount aan ST network directory (such as your network home) into the virtual machine via '''sshfs''' <br>
    and update the login, machine and mounting path:$> sudo apt-get install sshfs
     $> sshfs your_login@your_machine:/home/your_login/ /home/osboxes/mnt/mounting_path/(update the login, machine and mounting path in the line above)
    }}
    
    === Check Internet access===
    
    * An }}
    
    === Checking Internet access===
    
    * <u>'''Internet access through http and https protocols must be provided.
    '''Required '''</u>
    
    '''Required at least for ''Developer Package'' and ''Distribution Package'' at least.'''
    
    The command below allows to check for Internet enables checking internet access through http/https protocols:
     {{PC$}} wget -q www.google.com && echo "Internet access over HTTP/HTTPS is OK !" || echo "No internet access over HTTP/HTTPS ! You maymight need to set up a proxy."
    
    If aan 'OK' message is returned, the network is well configured. 
    In such case, skip the rest of this section and jump to next one ([[#Install extra packages|Install extra packages]]).
    
    Any other situation likely indicates the need for a proxy that a proxy is required for http/https protocols.<br>
    
    The best solution to set a proxy for http/https protocols is via the shell variables http_proxy and https_proxy:
     {{PC$}} export http_proxy=http://''<MyProxyLogin>'':''<MyProxyPassword>''@''<MyProxyServerUrl>'':''<MyProxyPort>''
     {{PC$}} export https_proxy=http://''<MyProxyLogin>'':''<MyProxyPassword>''@''<MyProxyServerUrl>'':''<MyProxyPort>''
    {{ReviewsComments| 20180907, AntonioB : We need to explain the case of unusual characters (e.g. space in the username is very common in ST). The suggestion here is to use HTML hexadecimal escape for all the unusual characters (e.g. replace space with '%20', '#' with '%23' and so on). It is supposed to not work if the username contains a ':' because the proxy takes it as separator between username and password. }}
    Since your password (<MyProxyPassword>) might contain "special characters", translate it into ASCII hexacode. To do this, use the command below: 
    :{{PC$}} echo -n " <MyProxyPassword>" | od -A n -t x1 -w128 | head -1 | tr " " "%"
    Check again the Internet access with by using the following command:
     {{PC$}} wget -q www.google.com && echo "Internet access over HTTP/HTTPS is OK !" || echo "No internet access over HTTP/HTTPS ! You maymight need to set up a proxy."
    * 
    
    * <u>'''Internet access for ''sudo'' commands'''</u>
    
    '''Required for ''Distribution Package''.'''
    
    {{InternalInfo|In case of ST-Ubuntu (Linux native provided by ICT) please do not set the sudo alias}}By default, ''sudo'' commands are executed in the ''root'' user environment; by default, no Internet proxy settings are applied for ''root'' userusers.<br>
    
    ''Root'' user shouldusers must be able to browse Internet, after creation ofhaving created an alias passing the proxy settings on ''sudo'' commandcommands:<br>
    
     {{PC$}} alias sudo{{=}}'sudo http_proxy{{=}}$http_proxy'
    
    Check that the ''sudo'' commands isare successful (requires Internet access):
     {{PC$}} sudo apt-get update
    * 
    
    * <u>'''Internet over git://, ssh:// and others specifics protocols'''</u>
    
    '''Required for ''Distribution Package''.'''<br>
    
    In addition to http/https protocols (used in 90% of the Internet traffic), some other protocols like such as git:// or ssh:// maymight be required. 
    
    For example, in the context of the ''Distribution Package'', some "git fetch" commands couldmight require "git:// protocols".<br>
    In order to To support these protocols through a proxy, the best way is to directly setup the proxy in the $HOME/.gitconfig file (core.gitproxy) and use a tool like such as ''cockscrew''<ref>  https://en.wikipedia.org/wiki/Corkscrew_(program) </ref> in order to tunnel the git:// flow into the http flow:
     {{PC$}} sudo apt-get update
     {{PC$}} sudo apt-get install corkscrew
    
     {{PC$}} git config --replace-all --global core.gitproxy "$HOME/bin/git-proxy.sh"
     {{PC$}} git config --add --global core.gitproxy "none for <MyPrivateNetworkDomain>" (optionnal and optional, for example .st.com,  or localhost, ...)
     {{PC$}} echo <nowiki>'</nowiki>exec corkscrew ''<MyProxyServerUrl>'' ''<MyProxyPort>'' $* $HOME/.git-proxy.auth<nowiki>'</nowiki> > $HOME/bin/git-proxy.sh
     {{PC$}} chmod 700 $HOME/bin/git-proxy.sh
     {{PC$}} echo <nowiki>'</nowiki>''<MyProxyLogin>'':''<MyProxyPassword>''<nowiki>'</nowiki> > $HOME/.git-proxy.auth
     {{PC$}} chmod 600 $HOME/.git-proxy.auth
    Here is a command to test thisUse the command below to test the proxy settings:
     {{PC$}} git ls-remote git://git.openembedded.org/openembedded-core > /dev/null && echo OK || echo KO
    
    The command should return returns 'OK', else  if the proxy settings are wrong.
    
    === Installcorrect.
    
    === Installing extra packages ===
    '''Required for ''Developer Package'' and ''Distribution Package''.'''
    In order to do<section begin=InstallExtraPackages/>
    
    Additional Ubuntu packages must be installed to perform basic development tasks, basic cross-compilation (via ''Developer Package'') or more complex cross-compilation such as OpenEmbedded does (via ''Distribution Package''), some extra Ubuntu packages should be installed:
    
    * Packages required by OpenEmbedded/Yocto ({{DocSource | domain=Yocto Project | path=mega-manual/mega-manual.html#required-packages-for-the-build-host | text=details here}}):
     {{PC$}} sudo apt-get update
     {{PC$}} sudo apt-get install sedgawk wget curl cvs subversion git-core coreutils unzip texi2html texinfo docbook-utils gawk python-pysqlite2 diffstat help2man make gcc build-essential g++ desktop-file-utils chrpath libxml2-utils xmlto docbook bsdmainutils iputils-ping cpio python-wand python-pycryptopp python-crypto
    {{ReviewsComments| 10 Oct2018 E Combette: python-pycryptopp or python-pycrypto could you confirm ?<br>On VM Ubuntu, pycrypto is missing during the compilation. Compile is fine as soon as python-pycrypto installed<br>20181030, SebastienG : this is confirmed and has been added. In fact in last ubuntu 16.04 revision (16.04.5) python-pycryptopp do not have python-crypto as dependence anymore}}
     {{PC$}} sudo apt-get install libsdl1.2-dev xterm corkscrew nfs-common nfs-kernel-server device-tree-compiler mercurial u-boot-tools libarchive-zip-perlgit-core diffstat unzip texinfo gcc-multilib build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint3 pylint xterm
     {{PC$}} sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
    
    * Packages needed for some "Developer Package" use cases:
     {{PC$}} sudo apt-get install libncurses5 libncurses5-dev libncursesw5-dev libssl-dev linux-headers-generic u-boot-tools device-tree-compiler bison flex g++ libyaml-dev
    
    * Package for repo (used to download the "Distribution Package" source code):
     Please follow the installation instructions described in [https://source.android.com/setup/develop#installing-repo repo].
     '' For Ubuntu 16.04, use the legacy repo [https://source.android.com/setup/develop#old-repo-python2 old-repo-python2 chapter]''
    
    * Useful tools:{{PC$}} sudo apt-get install ncurses-dev bc linux-headers-generic gcc-multilib libncurses5-dev libncursesw5-dev lrzsz dos2unix lib32ncurses5 repo libssl-dev
    {{ReviewsComments| 14 Jan2019 mcc: 
    please could you add java install command (useful for CubeMx)
    as we spent a lot of time finding the correct command :<br>coreutils bsdmainutils sed curl bc lrzsz corkscrew cvs subversion mercurial nfs-common nfs-kernel-server libarchive-zip-perl dos2unix texi2html diffstat libxml2-utils
    
    You can also install a Java Runtime Engine that is required for [[STM32CubeMX]] and [[STM32CubeProgrammer]]
    {{ReviewsComments|-- ECO 20/Nov~<br />Not needed for CubeProg 2.6.0 }}
     {{PC$}} sudo apt-get install default-jre
    
    }}
    
    ==== Install<section end=InstallExtraPackages />
    
    ==== Installing extra packages for Android<sup>TM</sup> ====
    {{Android|{{:PC prerequisites about STM32MPU distribution for Android}}}}
    
    === AdditionnalAdditional configurations ===
    
    {{InternalInfo|
    '''For ST user withusers using ST-Ubuntu 16.04 only ! (Linux native provided by ICT):'''<br>
    
    ST-Ubuntu are Linux machines with restricted adminadministrator rights.<br>However in order to ease and to improve ST-Ubuntu exprience, the required additionnals configurations have been packaged by ST-UBUNTU team in some packages:
    * st-settings : to be able to deal with experience, additional configurations are required. They are provided by ST-Ubuntu team in the following packages:
    * st-settings: to handle more than 8 partitons per microSD card
    * st-sudoers : to allow a be able to use the set of sudo commands, the ones needed  required to use Packages
    * st-udev : to allow user to format microSD card and usb stick
    * st-nfs : enable nfs serverformat microSD cards and USB sticks
    * st-nfs : to enable nfs server, which can be used by distribution the Distribution Package
    
    
    Please proceed in the installation of them, if any.
    
    Proceed as follows to install one of the above packages:
    
     {{PC$}} sudo apt-get install st-sudoers st-nfs st-settings st-udev
    After that you can Then skip this section and jump to next one [[#Setup Git user information| Setup Git user information]]
    
    }}
    * Allow.
    }}
    * Allowing up to 16 partitions per mmcMMC
    
    By default, on Linux system,  a maximum of 8 MMC partitions are allowed on mmc.
    All Packages (Starter Package, ...Linux systems. 
    All Packages (such as Starter Package) need more than 10 partitons for the storage device. In order to To extend the number of partitions per device to 16, the following options must be added to modprobe:
     {{PC$}} echo 'options mmc_block perdev_minors=16' > /tmp/mmc_block.conf
     {{PC$}} sudo mv /tmp/mmc_block.conf /etc/modprobe.d/mmc_block.conf
    
    * CheckChecking for ''locale'' setup
    '''Required for ''Distribution Package''.'''
    
    The ''locale'' setting is used by some applications/commands (including by ''Distribution Package'' applications/commands). <br>
    
    Verify that the ''locale'' settings are as follows:
     {{PC$}} locale
     LANG=en-US.UTF-8
    In case If the ''locale'' command returns a different configuration than the one shown above, reconfigure it must be reconfigured as follows:
     {{PC$}} sudo update-locale LANG=en_US.UTF-8Then '''reboot''' the PC.
    
    * Add user
    
    * Adding users in basics groups 
    The ''user'' login shouldmust belong to the basic Linux groups such as '''disk''', '''tty''', '''dialout''' or '''plugdev'''<br>
    
    Use the command ''groups'' command to list groups for the current user:
     {{PC$}} groups
    If needed, add ''user'' to the missing ''<groups>'':
     {{PC$}} sudo adduser $USER <group>
    
    === Setup Then '''reboot''' the PC.
    
    === Seting up ''Git'' user information  ===
    '''Required for ''Developer Package'' and ''Distribution Package''.'''<br> 
    
    The Useruser Information isare needed by git<ref> [[Git]] </ref> in case if ''commit'' and/or ''push'' commands are being used : 
    
    {{InternalInfo|If you have used the [[File:stenv.sh]]https://citools.st.com/artifacts/artifactory/oeivi-codex-st-com/HostEnv/stenv/stenv.sh stenv.sh] script please skip this section}}
     {{PC$}} git config --global user.name "Your Name"
     {{PC$}} git config --global user.email "you@example.com"
    
    ==Windows PC==
    '''''Starter Package'' may run on Windows.''' <br>
    
    '''''Developer Package'' and ''Distribution Package'' require a Linux environment.'''
    
    {{Warning|ST solutions, while reportedly functional when running on a Linux Virtual machine, are only validated for Linux native setups ....}}<br />
    
    
    There are several ways to run Linux system on top of a Windows host PC,. ST recommends to use a [[#Virtual Machine System|Virtual Machine System]]:
    # Install a virtual machine such as  VMWare <ref> http://vmware.com </ref>
    
    # Setup a '''64 bits-bit''' Ubuntu image compatible with your virtual machine
    
    
    ===Virtual Machine installation===
    {{InternalInfo|For ST employees you ST, in an experimental way, has also run ''Developer Package'' and ''Distribution Package'' on WSL2 (Windows Subsystem for Linux 2). Refer to [[#WSL2 (experimental)|WSL2 chapter]].
    
    ===Virtual machine system===
    ====Installing the virtual machine====
    {{InternalInfo|ST employees must use VMware Workstation player, other. Other virtual machines are forbidden ((such as VirtualBox, ...)) are forbidden.}}
    
    ST has selected VMWare as Linux virtual machine solution.
    
    VMWare is a commercial company specialized in virtualization solutions. The available solutions to support a virtual Linux machine on a Windows PC are:
    * VMWare Workstation Player (paid solution) for commercial use (download  here <ref> https://my.vmware.com/en/web/vmware/free#desktop_end_user_computing/vmware_workstation_player/15_0 </ref>)
    * VMWare Workstation Player (free solution) for home use (download here <ref> https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html</ref>)
    
    Please proceed with the installation of the virtual machine.
    
    {{highlight|Before running the virtual machine, make sure the virtualization is activated in the BIOS (it should be activated by default for any retail PC).}}
    
    {{InternalInfo|PCs from ICT are delivered with virtualization deactivated in the BIOS, please call 8787 to enable it}}
    ===Download
    
    ====Downloading the Ubuntu image for the virtual machine====
    
    The "osboxes.org" <ref> http://osboxes.org </ref> website provides virtual machine images compatible with VMWare(*.vmdk).<br>
    
    {{highlight|Only Ubuntu 16.04 (64bit) has '''{{EcosystemRelease | revision=2.1.0}}:''' {{highlight|Setup have been validated and tested on Ubuntu 18.04 (64bits)}}<span style="color: #D4007A;"> and Ubuntu 20.04 (64bits).</span><br/>
    
    '''{{EcosystemRelease | revision=2.0.0}}:''' {{highlight|Setup have been validated and tested.}}
    
    Download the 64 bits  on Ubuntu 18.04 (64bits)}}<span style="color: #D4007A;"> and Ubuntu 16.04 (64bits).</span>
    
    
    Download the 64-bit Ubuntu image available at <ref> httphttps://www.osboxes.org/ubuntu/#ubuntu-16-04-1804-vmware </ref> and, then:
    # Unzip the downloaded file
    # In VMware, create a virtual machine using the Ubuntu virtual disk downloaded from osboxes.org.<br>
    
    The recommended usage is to dedicate, at least, half of the host machine to the virtual machine:
     - CPU: 2 cores at least,
     - RAM: 6 Gbytes or more is a good choice (the more RAM allocated to Virtual Machine the better - the RAM allocated to Virtual Machine must be 2GB minimumat least 4 Gbytes),
     - Network: NAT is a good and an easy way to benefit formfrom a network connection within the virtual machine.
    
    {{highlight|Virutal The virtual size of the virtual disk downloaded from osboxes.org is about 500GB500 Gbytes. Even if ,  at beginning, the real size of the file of the virtual disk is less at beginning, the size could growthcan grow up to 500GB 500 Gbytes over compiling distribution package compiling or package development package.}}
    {{info|{{highlight|For VMware}}, you need first to create a default virtual machine, then add the previously downloaded ''.vmdk'' file, previously downloaded.<br>
    
    Please refer to the [[media:VMwarePlayerHelp.pdf|VMwarePlayer screenshot tutorial]].}}
    
    ===Launch of =Launching Ubuntu image====
    
    {{Warning | For "AZERTY" keyboard users:<br>
    
    The default keyboard configuration is "QWERTY".<br>
    In order to To configure the keyboard forto "AZERTY", start by opening a session (take care that the keyboard layout is QWERTY).<br>
    
    TIP: the password for the default user "''osboxes.org''" is "''osboxes.org''".<br>
    
    TIP: the '.' character is obtained by clicking ':' on an AZERTY keyboard configured in QWERTY.<br>
    
    Once the session is openedopen, click the 'En' icon on top/right of the screen, select the French ('Fr') keyboard layout and move it to the first position in the list.<br>
    
    Optionally the 'En' keyboard can be completely removed. If the 'Fr' option is not present, it can be added with the 'Text entry setting' menu.}}
    Default 'Ubuntu ''Credentials''' of the Ubuntu ''' are set to "osboxes.org" for both login and password.'''
    
    {{Warning | AdjustAdjusting screen resolution:<br>
    
    The (default) resolution used by the virtual machine is 800x600 (smallest available). It is not automatically adjusted to the display resolution.In order to To adjust the resolution, click the "settings" icon ('toothed wheel' on top/right of the screen), then "system&#xa0;settings&#xa0;..."&#xa0;>&#xa0;"display" and select the appropriate resolution for the display (do not to forget to click the "Apply" button on bottom/left of the "Screen Resolution Setting" window).}}
    
    For a better experience with the VMware virtual machine, install "vmware-tools" in order to be able to use the clipboard to drag-and-drop and copy/paste files between VMware and Windows.
    A step-by-step installation procedure of '''vmware-tools''' is available in the document: [[media:PreRequisite-Vmware-tools.pdf|PreRequisite-Vmware-tools.pdf]].
    
    
    The virtual machine is now up and running!
    
    {{highlight|The Ubuntu setup must be finalized according recommendations provided in [[#Linux PC |Linux PC ]] chapter}}
    ===References===<references/>{{Warning | USB connection  speed:<br>
    
    A USB connection is required to access STLink (debugger and serial port) and by STM32CubeProgrammer. The speed of the USB connection  between Linux running in the virtual machine and the external USB devices can be severely impacted by the following factors:
    * the virtual machine USB setup
    * the USB controller in the host PC
    * the USB device connected to host PC
    * any USB hub between the USB host and the USB device.
    If the speed of your USB connection is too low:
    * try different USB configurations of the virtual machine;
    * connect the USB device directly to the host USB port (without any USB hub);
    * try connecting the USB device to another USB port of the host (some PC have different USB controller on different USB port).
    }}
    
    ===WSL2 (experimental)===
    Even if STMicroelectronics strongly recommends to use a Linux<sup>&reg;</sup> environment, the ''Developer Package'' and ''Distribution Package'' work on WSL2 (Windows Sub-system Linux 2) environment. WSL is a feature provided by '''Windows 10<sup>&reg;</sup>'''.<br/>
    
    WSL2 is a new version of the architecture that powers the Windows subsystem for Linux to run ELF64 Linux binaries on Windows (more details on [http://aka.ms/wsl2 aka.ms/wsl2]). It is available on Windows 10 since build 18917.
    The  ''Developer Package'' successfully runs on WSL2 but unsuccessfully on WSL.
    
    * <u>Installing WSL2</u> : 
    ** To install WSL2, read [https://docs.microsoft.com/fr-fr/windows/wsl/wsl2-install https://docs.microsoft.com/fr-fr/windows/wsl/wsl2-install]
    ** Once WSL2 is installed, jump to [[#Linux_PC]] to make your WSL2 ready to run ''Developer Package'' and/or ''Distribution Package''.
    * <u>WSL2 limitations</u> : 
    ** Up to now (September 2019), WSL2 does not support hardware such as USB or serial devices ([https://docs.microsoft.com/fr-fr/windows/wsl/wsl2-faq#can-i-access-the-gpu-in-wsl-2-are-there-plans-to-increase-hardware-support more details]).
    **: This means that STM32CubeProgrammer must be used through native Windows.
    ** WSL2 files are not browsable from Windows native file explorer.
    **: To share files between WSL2 and Windows, it is recommend to use the mount point ''/mnt/c'' from WSL2 and perform copies.
    * <u>Tips for using WSL2</u> : 
    ** Launching graphical application : on ''wiki.ubuntu.com'', go to [https://wiki.ubuntu.com/WSL WSL] page and read the chapter [https://wiki.ubuntu.com/WSL#Running_Graphical_Applications Running Graphical Applications].
    
    ===References===<references/>
    
    <noinclude>
    
    [[Category:Prerequisites]]
    [[Category:STM32 MPU boards]]
    {{PublicationRequestId | 18175| 2020-11-19| previeous PR  8347has been treated by BrunoB}}</noinclude>
    (119 intermediate revisions by 11 users not shown)
    Line 1: Line 1:
    <noinclude>
    +
    {{Info|Recommended setup: Native Linux<sup>&reg;</sup> PC}}
    {{ArticleMainWriter | SebastienG}}
     
    {{ArticleApprovedVersion | SebastienG | NathalieS, ChristopheP, DenisH , ChristopheM , GeraldB, Jean-ChristopheT | 24Jan'18 |  BrunoB - 22Aug'18 - 8347 | 18Sep'18}}
     
    [[Category:MainMenu]]
     
    [[Category:Getting started with this user guide|02]]
     
    [[Category:Getting started with ST boards]]
     
    </noinclude>
     
     
     
    {{Info|Recommended setup: Native Linux PC}}
     
     
     
     
    == Purpose ==
     
    == Purpose ==
    This article explains and describes the hardware configuration required to be able to activate and run the STM32 MPU platforms.
    +
    This article explains and describes the host PC hardware and software configuration required to activate and run the STM32 MPU platforms.
       
     
    == Recommended PC configurations ==
     
    == Recommended PC configurations ==
    Line 16: Line 7:
       
     
    The table below guides through the selection and configuration of the host PC environment according the targeted Package:
     
    The table below guides through the selection and configuration of the host PC environment according the targeted Package:
    {| class="wikitable" align=center text=center width=100%
    +
    {| class="st-table"  
     
    |-
     
    |-
    ! Host Environment !! Starter Package !! Developer Package !! Distribution Package
    +
    ! Host environment !! Starter Package !! Developer Package !! Distribution Package
     
    |-
     
    |-
    | '''Windows (64 bits) '''<br>&emsp;Tested with Windows7 and Windows10<br>&emsp;Prefered version Windows 10 || native || [[PC_prerequisites#Virtual Machine installation|Virtual Machine]] || [[PC_prerequisites#Virtual Machine installation|Virtual Machine]]  
    +
    | '''Windows<sup>&reg;</sup> (64 bits) '''<br>&emsp;Tested with Windows 7 and Windows 10<br>&emsp;Preferred version is Windows 10 || native || [[PC_prerequisites#Installing the virtual machine|Virtual machine]] || [[PC_prerequisites#Installing the virtual machine|Virtual Machine]]  
     
    |-
     
    |-
    | '''Linux (64 bits)'''<br>&emsp;Tested with Ubuntu 16.04 || native || native + additional packages (see [[#Linux PC|Linux PC]] chapter ) || native + additional packages  (see [[#Linux PC| Linux PC]] chapter )
    +
    | '''Linux (64 bits)'''<br>&emsp;Tested with Ubuntu<sup>&reg;</sup> '''18.04''' and 20.04|| Native || Native + additional packages (see [[#Linux PC|Linux PC]] chapter ) || native + additional packages  (see [[#Linux PC| Linux PC]] chapter )
     
    |}
     
    |}
       
       
    There are no absolute minimal requirements regarding the PC hardware configuration, however ST recommends to meet or exceed the following hardware configurations when using '' Developer Package'' or ''Distribution Package''.
    +
    There are no absolute minimal requirements regarding the PC hardware configuration. However ST recommends to meet or exceed the following hardware requirements when using the ''Developer Package'' or ''Distribution Package''.
       
    The table below correspond to the minimal validated configuration:
    +
    The table below corresponds to the minimal validated configuration:
    {| class="wikitable" align=center text=center width=100%
    +
    {| class="st-table"
     
    |-
     
    |-
    ! Hardware item !! Minimal validated configuration !! Comments / Recommandations
    +
    ! Hardware item !! Minimal validated configuration !! Comments / Recommendations
     
    |-
     
    |-
    | CPU || core i5-2540M @ 2.6GHz <br> 2 cores (4 threads) <br> 3MB cache || '''64 bits instruction set is mandatory''' <br> '''8 cores/threads or more''' is a good config moreover for ''Developer Package'' and ''Distribution Package''.   
    +
    | CPU || core i5-2540M @ 2.6 GHz <br> 2 cores (4 threads) <br> 3-Mbyte cache || '''64-bit instruction set is mandatory''' <br> '''8 cores/threads or more''' is a good configuration for ''Developer Package'' and ''Distribution Package''.   
     
    |-
     
    |-
    | RAM || 8GB || '''16GB or more''' is recommended especially for ''Virtual Machine'' setup , ''Developer Package'' and ''Distribution Package''.
    +
    | RAM || 8 Gbytes || '''16 Gbytes or more''' are recommended especially for ''Virtual machine'' setup, ''Developer Package'' and ''Distribution Package''.
     
    |-
     
    |-
    | Hard Drive || 320GB || '''1TB''' is probably a better config when using ''Distribution Package''   
    +
    | Hard drive || 320 Gbytes || '''1 Tbytes''' is the best suited configuration for ''Distribution Package''   
     
    |}
     
    |}
       
    ==Linux PC==
    +
    ==Linux<sup>&reg;</sup> PC==
    {{ReviewsComments|RJE: "The prerequisites are obviously not the same when you installed SDK rather than Distribution Package: SDK comes with cross compile toolchain and supposed to provide all needed tools... while Distribution Package needs specific tools on host to generate (at least) the cross tool chain... So i don't think it's really usefull to ask customer to install all these packages on host for SDK only.<br>
    +
    A Linux PC with '''Ubuntu 18.04''' is the recommended setup. Other Ubuntu revisions are also supported (refer to Yocto reference manual<ref>{{DocSource | domain=Yocto Project | path=ref-manual/ref-manual.html#detailed-supported-distros | text=Supported Linux Distributionsl}}</ref>) .<br>
    I'm just wondering if we have to split or not host prerequisites according to Package installed: dev or distribution, as they are not requesting the same tools...<br>
     
    SGA, 28Jun18: To split the needed packages by kind of Package is quiet hard to do. Integration have taken an action to do it later. Just keep this comment in the meanwhile}}
     
       
    A Linux PC with '''Ubuntu 16.04''' is the recommended setup. Other Ubuntu revisions should also be supported, please refer to Yocto Manual<ref> https://www.yoctoproject.org/docs/2.4.3/ref-manual/ref-manual.html#detailed-supported-distros </ref> .<br>
    +
    {{Info|'''{{EcosystemRelease | revision = 2.1.0}}'''
    {{Info| ST solutions are tested and validated on a Linux PC running Ubuntu 16.04 LTS.}}
    +
    ST solutions are tested and validated on a Linux PC running Ubuntu 18.04 LTS (and Ubuntu 20.04 LTS).}}
      +
    {{Info|'''{{EcosystemRelease | revision = 2.0.0}}'''
      +
    ST solutions are tested and validated on a Linux PC running Ubuntu 18.04 LTS (and Ubuntu 16.04 LTS).}}
       
    {{InternalInfo|ST employees who are connected at a ST network need to configure its environment first:
    +
    {{InternalInfo|ST employees who are connected to an ST network (ST-Ubuntu or VMWare) need to configure their environment first:
    {{ReviewsComments|E Combette: please specify this apply on native PC Ubuntu and also VM Ubuntu  }}
    +
    * Open a shell with bash:
    * Open a shell with bash
    +
    The shell to use is bash, which might not be the default shell on ST-Ubuntu PCs.<br>
    The shell to use is bash, which could be not the default shell on ST-UBUNTU PCs.<br>
    +
    First, open a terminal and check the default shell by typing ''export''. ''export'' is not available in non-bash compliant shells (such as csh or tcsh).
    First, open a terminal and check the default shell by typing 'export'. 'export' is not availble in non bash compliant shell (like csh or tcsh).
    +
    If the shell does not find the ''export'' command, there are two options:
    If 'export' command is not found by the shell, there are 2 options:
    +
    :# Ask ICT to change the default shell to bash on your PC.
    :# ask for ICT to change the default shell to bash on your PC
    +
    :# Switch to a bash shell by typing ''bash''. To avoid breaking scp as well as tricky env issues, DO NOT invoke bash from your .profile, .cshrc or any other files.
    :# switch to a bash shell by typing 'bash' (to not break scp, to avoid tricky env issue by experience DO NOT invoke bash from your .profile, .cshrc or any others file)
     
       
    * Add some proxy and repo configuration functions to the bash shell (to be done once at first image startup):<br>
    +
    * Add some proxy and repo configuration functions to the bash shell. This has to be done once at first image startup:<br>
    The functions are available in the file: [[File:stenv.sh]]
     
     
      $> mkdir -p $HOME/bin
     
      $> mkdir -p $HOME/bin
      $> wget http://intranet.lme.st.com:8000/php-bin/ug_mcdmpu/images/0/02/Stenv.sh -O $HOME/bin/stenv.sh
    +
      $> wget --no-check-certificate https://citools.st.com/artifacts/artifactory/oeivi-codex-st-com/HostEnv/stenv/stenv.sh -O $HOME/bin/stenv.sh
      $> echo 'export STENV_NOGERRIT{{=}}yes' >> $HOME/.bashrc (if you do not need to access to code on codex/gerrit repository)
    +
      $> echo 'export STENV_NOGERRIT{{=}}yes' >> $HOME/.bashrc (if you do not need to access code on codex/gerrit repository)
     
      $> echo 'source $HOME/bin/stenv.sh' >> $HOME/.bashrc
     
      $> echo 'source $HOME/bin/stenv.sh' >> $HOME/.bashrc
     
      $> exit (new terminal will source the stenv.sh)
     
      $> exit (new terminal will source the stenv.sh)
      Now by opening a new shell, the proxy and git/github/repo should be set correctly
    +
      The proxy and git/github/repo is now correctly set when you open a new shell.  
    {{ReviewsComments|HuguesF: On a newly installed ST-PC Ubuntu-16.04, sudo password is claimed:
     
    Check Internet connection ... INSTALLATION of corkscrew ... [sudo] password for frq08990:
     
    Apres l'install de corkscrew et git (sudo apt-get install corkscrew git) on va plus loin:
     
    <pre>
     
    Check Internet connection ...  OK(proxy: appgw.gnb.st.com:8080)
     
    Check for your installed packages ...
     
    Check for your installed packages ... DONE
     
    Check for your git/github/repo (settings)...
     
    Your Fisrtname LASTNAME [] : Hugues FRUCHET
     
    Your email [] : hugues.fruchet@st.com
     
    Your SSH username (used for codex/gerrit) [] : frq08990
     
    ssh_askpass: exec(/usr/bin/ssh-askpass): No such file or directory
     
    ssh_askpass: exec(/usr/bin/ssh-askpass): No such file or directory
     
    </pre>
     
    Attention il y a une typo dans le script:
     
    Your '''FiSRtname''' LASTNAME
     
    }}
     
       
    * Answer the questions of [[File:stenv.sh]] (sourced automatically from your .bashrc) which sets the proxy (if needed) and sets codex/gerrit ssh keys, the git configs, git proxy and github credentials.  
    +
    * Answer the questions of ''stenv.sh'' (automatically  sourced from your .bashrc) to set the proxy (if needed), codex/gerrit ssh keys, git configs, git proxy and github credentials.  
    However you can force at any moment the reconfiguration of any setting by running the following commands (provided by stenv.sh):
    +
    You can force at any moment the reconfiguration of any setting by running the following commands (provided by stenv.sh):
     
    <br>
     
    <br>
     
      $> stenv-gitrepo_config -f # Sets gitconfig file and github credentials
     
      $> stenv-gitrepo_config -f # Sets gitconfig file and github credentials
    Line 91: Line 63:
     
      $> stenv-github_clear_credential # clear proxy, github.com, codex/gerrit credentials
     
      $> stenv-github_clear_credential # clear proxy, github.com, codex/gerrit credentials
       
    '''appgw.gnb.st.com is the 'hardcoded' proxy url used in stenv.sh, if you use another proxy please edit the stenv.sh file.<br>Moreover, by default st proxy (appgw.gnb.st.com, and others) is not open by default for all employees, so you may need to ask for access (via [http://flow.st.com/st/UP/EICOM/Lists/RequestList/NewForm.aspx FLOW]) to appgw.gnb.st.com through http protocol (even though it is not used yet, you can ask for the git protocol tool)'''
    +
    '''appgw.gnb.st.com is the 'hardcoded' proxy url used in stenv.sh. If you use another proxy, edit the stenv.sh file.<br>By default ST proxies (appgw.gnb.st.com, and others) are not open to all employees, so you may need to request access to appgw.gnb.st.com through the http protocol (go to [http://flow.st.com/st/UP/EICOM/Lists/RequestList/NewForm.aspx FLOW]). Even if you do not use it yet, ask for the git protocol tool.'''
       
     
    * TIPS:
     
    * TIPS:
    :* mount a ST network directory (such as your network home) into the virtual machine via '''sshfs'''
    +
    :* mount an ST network directory (such as your network home) into the virtual machine via '''sshfs''' and update the login, machine and mounting path:
    <br>
     
     
      $> sudo apt-get install sshfs
     
      $> sudo apt-get install sshfs
     
      $> sshfs your_login@your_machine:/home/your_login/ /home/osboxes/mnt/mounting_path/
     
      $> sshfs your_login@your_machine:/home/your_login/ /home/osboxes/mnt/mounting_path/
    (update the login, machine and mounting path in the line above)
     
     
    }}
     
    }}
       
    === Check Internet access===
    +
    === Checking Internet access===
       
    * An Internet access through http and https protocols must be provided.
    +
    * <u>'''Internet access through http and https protocols'''</u>
    '''Required for ''Developer Package'' and ''Distribution Package'' at least.'''
    +
    '''Required at least for ''Developer Package'' and ''Distribution Package''.'''
       
    The command below allows to check for Internet access through http/https protocols:
    +
    The command below enables checking internet access through http/https protocols:
      {{PC$}} wget -q www.google.com && echo "Internet access over HTTP/HTTPS is OK !" || echo "No internet access over HTTP/HTTPS ! You may need to set up a proxy."
    +
      {{PC$}} wget -q www.google.com && echo "Internet access over HTTP/HTTPS is OK !" || echo "No internet access over HTTP/HTTPS ! You might need to set up a proxy."
       
    If a 'OK' message is returned, the network is well configured.  
    +
    If an 'OK' message is returned, the network is well configured.  
    In such case, skip the rest of this section and jump to next one ([[#Install extra packages|Install extra packages]]).
    +
    In such case, skip the rest of this section and jump to [[#Install extra packages|Install extra packages]].
       
    Any other situation likely indicates the need for a proxy for http/https protocols.<br>
    +
    Any other situation likely indicates that a proxy is required for http/https protocols.
     
    The best solution to set a proxy for http/https protocols is via the shell variables http_proxy and https_proxy:
     
    The best solution to set a proxy for http/https protocols is via the shell variables http_proxy and https_proxy:
     
      {{PC$}} export http_proxy=http://''<MyProxyLogin>'':''<MyProxyPassword>''@''<MyProxyServerUrl>'':''<MyProxyPort>''
     
      {{PC$}} export http_proxy=http://''<MyProxyLogin>'':''<MyProxyPassword>''@''<MyProxyServerUrl>'':''<MyProxyPort>''
     
      {{PC$}} export https_proxy=http://''<MyProxyLogin>'':''<MyProxyPassword>''@''<MyProxyServerUrl>'':''<MyProxyPort>''
     
      {{PC$}} export https_proxy=http://''<MyProxyLogin>'':''<MyProxyPassword>''@''<MyProxyServerUrl>'':''<MyProxyPort>''
       
    {{ReviewsComments| 20180907, AntonioB : We need to explain the case of unusual characters (e.g. space in the username is very common in ST). The suggestion here is to use HTML hexadecimal escape for all the unusual characters (e.g. replace space with '%20', '#' with '%23' and so on). It is supposed to not work if the username contains a ':' because the proxy takes it as separator between username and password. }}
    +
    Since your password (<MyProxyPassword>) might contain "special characters", translate it into ASCII hexacode. To do this, use the command below:
      +
    :{{PC$}} echo -n " <MyProxyPassword>" | od -A n -t x1 -w128 | head -1 | tr " " "%"
      +
     
       
    Check again the Internet access with command:
    +
    Check again the Internet access by using the following command:
      {{PC$}} wget -q www.google.com && echo "Internet access over HTTP/HTTPS is OK !" || echo "No internet access over HTTP/HTTPS ! You may need to set up a proxy."
    +
      {{PC$}} wget -q www.google.com && echo "Internet access over HTTP/HTTPS is OK !" || echo "No internet access over HTTP/HTTPS ! You might need to set up a proxy."
       
    * Internet access for ''sudo'' commands
    +
     
      +
    * <u>'''Internet access for ''sudo'' commands'''</u>
     
    '''Required for ''Distribution Package''.'''
     
    '''Required for ''Distribution Package''.'''
       
     
    {{InternalInfo|In case of ST-Ubuntu (Linux native provided by ICT) please do not set the sudo alias}}
     
    {{InternalInfo|In case of ST-Ubuntu (Linux native provided by ICT) please do not set the sudo alias}}
    ''sudo'' commands are executed in the ''root'' user environment; by default, no Internet proxy settings are applied for ''root'' user.<br>
    +
    By default, ''sudo'' commands are executed in the ''root'' user environment; no Internet proxy settings are applied for ''root'' users.<br>
    ''Root'' user should be able to browse Internet, after creation of an alias passing the proxy settings on ''sudo'' command:<br>
    +
    ''Root'' users must be able to browse Internet after having created an alias passing the proxy settings on ''sudo'' commands:<br>
     
      {{PC$}} alias sudo{{=}}'sudo http_proxy{{=}}$http_proxy'
     
      {{PC$}} alias sudo{{=}}'sudo http_proxy{{=}}$http_proxy'
       
    Check that the ''sudo'' commands is successful (requires Internet access):
    +
    Check that the ''sudo'' commands are successful (requires Internet access):
     
      {{PC$}} sudo apt-get update
     
      {{PC$}} sudo apt-get update
       
    * Internet over git://, ssh:// and others specifics protocols
    +
     
      +
    * <u>'''Internet over git://, ssh:// and others specifics protocols'''</u>
     
    '''Required for ''Distribution Package''.'''<br>
     
    '''Required for ''Distribution Package''.'''<br>
    In addition to http/https protocols (used in 90% of the Internet traffic), some other protocols like git:// or ssh:// may be required.  
    +
    In addition to http/https protocols (used in 90% of the Internet traffic), other protocols such as git:// or ssh:// might be required.  
       
    For example in the context of the ''Distribution Package'', some "git fetch" commands could require "git:// protocols".<br>
    +
    For example, in the context of the ''Distribution Package'', some "git fetch" commands might require "git:// protocols".<br>
    In order to support these protocols through a proxy, the best way is to directly setup the proxy in the $HOME/.gitconfig file (core.gitproxy) and use a tool like ''cockscrew''<ref>  https://en.wikipedia.org/wiki/Corkscrew_(program) </ref> in order to tunnel the git:// flow into the http flow:
    +
    To support these protocols through a proxy, directly setup the proxy in the $HOME/.gitconfig file (core.gitproxy) and use a tool such as ''cockscrew''<ref>  https://en.wikipedia.org/wiki/Corkscrew_(program) </ref> to tunnel the git:// flow into the http flow:
     
      {{PC$}} sudo apt-get update
     
      {{PC$}} sudo apt-get update
     
      {{PC$}} sudo apt-get install corkscrew
     
      {{PC$}} sudo apt-get install corkscrew
     
       
     
       
     
      {{PC$}} git config --replace-all --global core.gitproxy "$HOME/bin/git-proxy.sh"
     
      {{PC$}} git config --replace-all --global core.gitproxy "$HOME/bin/git-proxy.sh"
      {{PC$}} git config --add --global core.gitproxy "none for <MyPrivateNetworkDomain>" (optionnal and for example .st.com, localhost, ...)
    +
      {{PC$}} git config --add --global core.gitproxy "none for <MyPrivateNetworkDomain>" (optional, for example .st.com or localhost)
     
      {{PC$}} echo <nowiki>'</nowiki>exec corkscrew ''<MyProxyServerUrl>'' ''<MyProxyPort>'' $* $HOME/.git-proxy.auth<nowiki>'</nowiki> > $HOME/bin/git-proxy.sh
     
      {{PC$}} echo <nowiki>'</nowiki>exec corkscrew ''<MyProxyServerUrl>'' ''<MyProxyPort>'' $* $HOME/.git-proxy.auth<nowiki>'</nowiki> > $HOME/bin/git-proxy.sh
     
      {{PC$}} chmod 700 $HOME/bin/git-proxy.sh
     
      {{PC$}} chmod 700 $HOME/bin/git-proxy.sh
    Line 149: Line 123:
     
      {{PC$}} chmod 600 $HOME/.git-proxy.auth
     
      {{PC$}} chmod 600 $HOME/.git-proxy.auth
       
    Here is a command to test this proxy settings:
    +
    Use the command below to test the proxy settings:
     
      {{PC$}} git ls-remote git://git.openembedded.org/openembedded-core > /dev/null && echo OK || echo KO
     
      {{PC$}} git ls-remote git://git.openembedded.org/openembedded-core > /dev/null && echo OK || echo KO
       
    The command should return 'OK', else proxy settings are wrong.
    +
    The command returns 'OK' if the proxy settings are correct.
       
    === Install extra packages ===
    +
    === Installing extra packages ===
     
    '''Required for ''Developer Package'' and ''Distribution Package''.'''
     
    '''Required for ''Developer Package'' and ''Distribution Package''.'''
       
    In order to do basic development tasks, basic cross-compilation (via ''Developer Package'') or more complex cross-compilation as OpenEmbedded does (via ''Distribution Package''), some extra Ubuntu packages should be installed:
    +
    <section begin=InstallExtraPackages/>
      +
    Additional Ubuntu packages must be installed to perform basic development tasks, basic cross-compilation (via ''Developer Package'') or more complex cross-compilation such as OpenEmbedded does (via ''Distribution Package''):
      +
     
      +
    * Packages required by OpenEmbedded/Yocto ({{DocSource | domain=Yocto Project | path=mega-manual/mega-manual.html#required-packages-for-the-build-host | text=details here}}):
     
      {{PC$}} sudo apt-get update
     
      {{PC$}} sudo apt-get update
      {{PC$}} sudo apt-get install sed wget curl cvs subversion git-core coreutils unzip texi2html texinfo docbook-utils gawk python-pysqlite2 diffstat help2man make gcc build-essential g++ desktop-file-utils chrpath libxml2-utils xmlto docbook bsdmainutils iputils-ping cpio python-wand python-pycryptopp python-crypto
    +
      {{PC$}} sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint3 pylint xterm
    {{ReviewsComments| 10 Oct2018 E Combette: python-pycryptopp or python-pycrypto could you confirm ?<br>On VM Ubuntu, pycrypto is missing during the compilation. Compile is fine as soon as python-pycrypto installed<br>20181030, SebastienG : this is confirmed and has been added. In fact in last ubuntu 16.04 revision (16.04.5) python-pycryptopp do not have python-crypto as dependence anymore}}
    +
      {{PC$}} sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
      {{PC$}} sudo apt-get install libsdl1.2-dev xterm corkscrew nfs-common nfs-kernel-server device-tree-compiler mercurial u-boot-tools libarchive-zip-perl
    +
     
      {{PC$}} sudo apt-get install ncurses-dev bc linux-headers-generic gcc-multilib libncurses5-dev libncursesw5-dev lrzsz dos2unix lib32ncurses5 repo libssl-dev
    +
    * Packages needed for some "Developer Package" use cases:
    {{ReviewsComments| 14 Jan2019 mcc:
    +
      {{PC$}} sudo apt-get install libncurses5 libncurses5-dev libncursesw5-dev libssl-dev linux-headers-generic u-boot-tools device-tree-compiler bison flex g++ libyaml-dev
    please could you add java install command (useful for CubeMx)
    +
     
    as we spent a lot of time finding the correct command :<br>
    +
    * Package for repo (used to download the "Distribution Package" source code):
    sudo apt-get install default-jre
    +
    Please follow the installation instructions described in [https://source.android.com/setup/develop#installing-repo repo].
      +
    '' For Ubuntu 16.04, use the legacy repo [https://source.android.com/setup/develop#old-repo-python2 old-repo-python2 chapter]''
       
    }}
    +
    * Useful tools:
      +
    {{PC$}} sudo apt-get install coreutils bsdmainutils sed curl bc lrzsz corkscrew cvs subversion mercurial nfs-common nfs-kernel-server libarchive-zip-perl dos2unix texi2html diffstat libxml2-utils
       
    ==== Install extra packages for Android ====
    +
    You can also install a Java Runtime Engine that is required for [[STM32CubeMX]] and [[STM32CubeProgrammer]]
      +
    {{ReviewsComments|-- ECO 20/Nov~<br />Not needed for CubeProg 2.6.0 }}
      +
    {{PC$}} sudo apt-get install default-jre
      +
    <section end=InstallExtraPackages />
      +
    ==== Installing extra packages for Android<sup>TM</sup> ====
     
    {{Android|{{:PC prerequisites about STM32MPU distribution for Android}}}}
     
    {{Android|{{:PC prerequisites about STM32MPU distribution for Android}}}}
       
    === Additionnal configurations ===
    +
    === Additional configurations ===
       
     
    {{InternalInfo|
     
    {{InternalInfo|
    '''For ST user with ST-Ubuntu only ! (Linux native provided by ICT):'''<br>
    +
    '''For ST users using ST-Ubuntu 16.04 only ! (Linux native provided by ICT):'''<br>
    ST-Ubuntu are Linux machines with restricted admin rights.<br>However in order to ease and to improve ST-Ubuntu exprience, the required additionnals configurations have been packaged by ST-UBUNTU team in some packages:
    +
    ST-Ubuntu are Linux machines with restricted administrator rights.<br>However to ease and improve ST-Ubuntu experience, additional configurations are required. They are provided by ST-Ubuntu team in the following packages:
    * st-settings : to be able to deal with more than 8 partitons per microSD card
    +
    * st-settings: to handle more than 8 partitons per microSD card
    * st-sudoers : to allow a set of sudo commands, the ones needed to use Packages
    +
    * st-sudoers: to be able to use the set of sudo commands required to use Packages
    * st-udev : to allow user to format microSD card and usb stick
    +
    * st-udev: to format microSD cards and USB sticks
    * st-nfs : enable nfs server which can be used by distribution Package
    +
    * st-nfs : to enable nfs server, which can be used by the Distribution Package.
       
    Please proceed in the installation of them, if any:
    +
    Proceed as follows to install one of the above packages:
       
     
      {{PC$}} sudo apt-get install st-sudoers st-nfs st-settings st-udev
     
      {{PC$}} sudo apt-get install st-sudoers st-nfs st-settings st-udev
       
    After that you can skip this section and jump to next one [[#Setup Git user information| Setup Git user information]]
    +
    Then skip this section and jump to [[#Setup Git user information| Setup Git user information]].
     
    }}
     
    }}
    * Allow up to 16 partitions per mmc
    +
    * Allowing up to 16 partitions per MMC
    By default, on Linux system, a maximum of 8 partitions are allowed on mmc.
    +
    By default a maximum of 8 MMC partitions are allowed on Linux systems.  
    All Packages (Starter Package, ...) need more than 10 partitons for the storage device. In order to extend the number of partitions per device to 16, the following options must be added to modprobe:
    +
    All Packages (such as Starter Package) need more than 10 partitons for the storage device. To extend the number of partitions per device to 16, the following options must be added to modprobe:
     
      {{PC$}} echo 'options mmc_block perdev_minors=16' > /tmp/mmc_block.conf
     
      {{PC$}} echo 'options mmc_block perdev_minors=16' > /tmp/mmc_block.conf
     
      {{PC$}} sudo mv /tmp/mmc_block.conf /etc/modprobe.d/mmc_block.conf
     
      {{PC$}} sudo mv /tmp/mmc_block.conf /etc/modprobe.d/mmc_block.conf
       
    * Check for ''locale'' setup
    +
    * Checking for ''locale'' setup
     
    '''Required for ''Distribution Package''.'''
     
    '''Required for ''Distribution Package''.'''
       
    Line 203: Line 186:
     
      LANG=en-US.UTF-8
     
      LANG=en-US.UTF-8
       
    In case the ''locale'' command returns a different configuration than the one shown above, it must be reconfigured as follows:
    +
    If the ''locale'' command returns a different configuration than the one shown above, reconfigure it as follows:
     
      {{PC$}} sudo update-locale LANG=en_US.UTF-8
     
      {{PC$}} sudo update-locale LANG=en_US.UTF-8
    Then '''reboot''' the PC.
     
       
    * Add user in basics groups  
    +
    * Adding users in basics groups  
    The ''user'' login should belong to the basic Linux groups such as '''disk''', '''tty''', '''dialout''' or '''plugdev'''<br>
    +
    The ''user'' login must belong to the basic Linux groups such as '''disk''', '''tty''', '''dialout''' or '''plugdev'''<br>
    Use the command ''groups'' to list groups for the current user:
    +
    Use the ''groups'' command to list groups for the current user:
     
      {{PC$}} groups
     
      {{PC$}} groups
    If needed add ''user'' to the missing ''<groups>'':
    +
    If needed, add ''user'' to the missing ''<groups>'':
     
      {{PC$}} sudo adduser $USER <group>
     
      {{PC$}} sudo adduser $USER <group>
       
    === Setup ''Git'' user information  ===
    +
    Then '''reboot''' the PC.
      +
     
      +
    === Seting up ''Git'' user information  ===
     
    '''Required for ''Developer Package'' and ''Distribution Package''.'''<br>  
     
    '''Required for ''Developer Package'' and ''Distribution Package''.'''<br>  
    The User Information is needed by git<ref> [[Git]] </ref> in case ''commit'' and/or ''push'' commands are being used :  
    +
    The user Information are needed by git<ref> [[Git]] </ref> if ''commit'' and/or ''push'' commands are used:  
       
    {{InternalInfo|If you have used the [[File:stenv.sh]] script please skip this section}}
    +
    {{InternalInfo|If you have used the [https://citools.st.com/artifacts/artifactory/oeivi-codex-st-com/HostEnv/stenv/stenv.sh stenv.sh] script please skip this section}}
     
      {{PC$}} git config --global user.name "Your Name"
     
      {{PC$}} git config --global user.name "Your Name"
     
      {{PC$}} git config --global user.email "you@example.com"
     
      {{PC$}} git config --global user.email "you@example.com"
    Line 226: Line 210:
     
    '''''Developer Package'' and ''Distribution Package'' require a Linux environment.'''
     
    '''''Developer Package'' and ''Distribution Package'' require a Linux environment.'''
       
    {{Warning|ST solutions, while reportedly functional when running on a Linux Virtual machine, are only validated for Linux native setups ...}}<br />
    +
    {{Warning|ST solutions, while reportedly functional when running on a Linux Virtual machine, are only validated for Linux native setups.}}<br />
       
    There are several ways to run Linux system on top of a Windows host PC, ST recommends to use a Virtual Machine System:
    +
    There are several ways to run Linux system on top of a Windows host PC. ST recommends to use a [[#Virtual Machine System|Virtual Machine System]]:
     
    # Install a virtual machine such as  VMWare <ref> http://vmware.com </ref>
     
    # Install a virtual machine such as  VMWare <ref> http://vmware.com </ref>
    # Setup a '''64 bits''' Ubuntu image compatible with your virtual machine
    +
    # Setup a '''64-bit''' Ubuntu image compatible with your virtual machine
       
      +
    ST, in an experimental way, has also run ''Developer Package'' and ''Distribution Package'' on WSL2 (Windows Subsystem for Linux 2). Refer to [[#WSL2 (experimental)|WSL2 chapter]].
       
    ===Virtual Machine installation===
    +
    ===Virtual machine system===
    {{InternalInfo|For ST employees you must use VMware Workstation player, other virtual machines are forbidden (VirtualBox, ...)}}
    +
    ====Installing the virtual machine====
      +
    {{InternalInfo|ST employees must use VMware Workstation player. Other virtual machines (such as VirtualBox) are forbidden.}}
       
     
    ST has selected VMWare as Linux virtual machine solution.
     
    ST has selected VMWare as Linux virtual machine solution.
    Line 248: Line 234:
     
    {{InternalInfo|PCs from ICT are delivered with virtualization deactivated in the BIOS, please call 8787 to enable it}}
     
    {{InternalInfo|PCs from ICT are delivered with virtualization deactivated in the BIOS, please call 8787 to enable it}}
       
    ===Download the Ubuntu image for the virtual machine===
    +
     
      +
    ====Downloading the Ubuntu image for the virtual machine====
     
    The "osboxes.org" <ref> http://osboxes.org </ref> website provides virtual machine images compatible with VMWare(*.vmdk).<br>
     
    The "osboxes.org" <ref> http://osboxes.org </ref> website provides virtual machine images compatible with VMWare(*.vmdk).<br>
       
    {{highlight|Only Ubuntu 16.04 (64bit) has been validated and tested.}}
    +
    '''{{EcosystemRelease | revision=2.1.0}}:''' {{highlight|Setup have been validated and tested on Ubuntu 18.04 (64bits)}}<span style="color: #D4007A;"> and Ubuntu 20.04 (64bits).</span><br/>
      +
    '''{{EcosystemRelease | revision=2.0.0}}:''' {{highlight|Setup have been validated and tested on Ubuntu 18.04 (64bits)}}<span style="color: #D4007A;"> and Ubuntu 16.04 (64bits).</span>
       
    Download the 64 bits Ubuntu image available at <ref> http://www.osboxes.org/ubuntu/#ubuntu-16-04-vmware </ref> and:
    +
    Download the 64-bit Ubuntu image available at <ref> https://www.osboxes.org/ubuntu/#ubuntu-1804-vmware </ref>, then:
     
    # Unzip the downloaded file
     
    # Unzip the downloaded file
    # In VMware create a virtual machine using the Ubuntu virtual disk downloaded from osboxes.org.<br>
    +
    # In VMware, create a virtual machine using the Ubuntu virtual disk downloaded from osboxes.org.<br>
     
    The recommended usage is to dedicate, at least, half of the host machine to the virtual machine:
     
    The recommended usage is to dedicate, at least, half of the host machine to the virtual machine:
     
      - CPU: 2 cores at least,
     
      - CPU: 2 cores at least,
      - RAM: 6 Gbytes or more is a good choice (the more RAM allocated to Virtual Machine the better - the RAM allocated to Virtual Machine must be 2GB minimum),
    +
      - RAM: 6 Gbytes or more is a good choice (the more RAM allocated to Virtual Machine the better - the RAM allocated to Virtual Machine must be at least 4 Gbytes),
      - Network: NAT is good and an easy way to benefit form a network connection within the virtual machine.
    +
      - Network: NAT is a good easy way to benefit from a network connection within the virtual machine.
       
    {{highlight|Virutal size of virtual disk downloaded from osboxes.org is about 500GB. Even if the real size of the file of the virtual disk is less at beginning, the size could growth up to 500GB over compiling distribution package or development package.}}
    +
    {{highlight|The virtual size of the virtual disk downloaded from osboxes.org is about 500 Gbytes. Even if,  at beginning, the real size of the file of the virtual disk is less, the size can grow up to 500 Gbytes over distribution package compiling or package development.}}
    {{info|{{highlight|For VMware}}, you need first to create a default virtual machine then add the ''.vmdk'' file, previously downloaded.<br>
    +
    {{info|{{highlight|For VMware}}, first create a default virtual machine, then add the previously downloaded ''.vmdk'' file.<br>
     
    Please refer to the [[media:VMwarePlayerHelp.pdf|VMwarePlayer screenshot tutorial]].}}
     
    Please refer to the [[media:VMwarePlayerHelp.pdf|VMwarePlayer screenshot tutorial]].}}
       
    ===Launch of Ubuntu image===
    +
    ====Launching Ubuntu image====
     
    {{Warning | For "AZERTY" keyboard users:<br>
     
    {{Warning | For "AZERTY" keyboard users:<br>
     
    The default keyboard configuration is "QWERTY".<br>
     
    The default keyboard configuration is "QWERTY".<br>
    In order to configure the keyboard for "AZERTY", start by opening a session (take care that the keyboard layout is QWERTY).<br>
    +
    To configure the keyboard to "AZERTY", start by opening a session (take care that the keyboard layout is QWERTY).<br>
     
    TIP: the password for the default user "''osboxes.org''" is "''osboxes.org''".<br>
     
    TIP: the password for the default user "''osboxes.org''" is "''osboxes.org''".<br>
     
    TIP: the '.' character is obtained by clicking ':' on an AZERTY keyboard configured in QWERTY.<br>
     
    TIP: the '.' character is obtained by clicking ':' on an AZERTY keyboard configured in QWERTY.<br>
    Once the session is opened, click the 'En' icon on top/right of the screen, select the French ('Fr') keyboard layout and move it to the first position in the list.<br>
    +
    Once the session is open, click the 'En' icon on top/right of the screen, select the French ('Fr') keyboard layout and move it to the first position in the list.<br>
     
    Optionally the 'En' keyboard can be completely removed. If the 'Fr' option is not present, it can be added with the 'Text entry setting' menu.}}
     
    Optionally the 'En' keyboard can be completely removed. If the 'Fr' option is not present, it can be added with the 'Text entry setting' menu.}}
    Default '''Credentials''' of the Ubuntu ''' are set to "osboxes.org" for both login and password.'''
    +
    Default 'Ubuntu ''Credentials''' ''' are set to "osboxes.org" for both login and password.'''
       
    {{Warning | Adjust screen resolution:<br>
    +
    {{Warning | Adjusting screen resolution:<br>
     
    The (default) resolution used by the virtual machine is 800x600 (smallest available). It is not automatically adjusted to the display resolution.
     
    The (default) resolution used by the virtual machine is 800x600 (smallest available). It is not automatically adjusted to the display resolution.
    In order to adjust the resolution, click the "settings" icon ('toothed wheel' on top/right of the screen), then "system&#xa0;settings&#xa0;..."&#xa0;>&#xa0;"display" and select the appropriate resolution for the display (do not to forget to click the "Apply" button on bottom/left of the "Screen Resolution Setting" window).}}
    +
    To adjust the resolution, click the "settings" icon ('toothed wheel' on top/right of the screen), then "system&#xa0;settings&#xa0;..."&#xa0;>&#xa0;"display" and select the appropriate resolution for the display (do not to forget to click the "Apply" button on bottom/left of the "Screen Resolution Setting" window).}}
       
     
    For a better experience with the VMware virtual machine, install "vmware-tools" in order to be able to use the clipboard to drag-and-drop and copy/paste files between VMware and Windows.
     
    For a better experience with the VMware virtual machine, install "vmware-tools" in order to be able to use the clipboard to drag-and-drop and copy/paste files between VMware and Windows.
    A step-by-step installation procedure of '''vmware-tools''' is available in the document: [[media:PreRequisite-Vmware-tools.pdf|PreRequisite-Vmware-tools.pdf]]
    +
    A step-by-step installation procedure of '''vmware-tools''' is available in [[media:PreRequisite-Vmware-tools.pdf|PreRequisite-Vmware-tools.pdf]].
       
       
    The virtual machine is up and running!
    +
    The virtual machine is now up and running!
       
     
    {{highlight|The Ubuntu setup must be finalized according recommendations provided in [[#Linux PC |Linux PC ]] chapter}}
     
    {{highlight|The Ubuntu setup must be finalized according recommendations provided in [[#Linux PC |Linux PC ]] chapter}}
      +
      +
    {{Warning | USB connection  speed:<br>
      +
    A USB connection is required to access STLink (debugger and serial port) and by STM32CubeProgrammer. The speed of the USB connection  between Linux running in the virtual machine and the external USB devices can be severely impacted by the following factors:
      +
    * the virtual machine USB setup
      +
    * the USB controller in the host PC
      +
    * the USB device connected to host PC
      +
    * any USB hub between the USB host and the USB device.
      +
    If the speed of your USB connection is too low:
      +
    * try different USB configurations of the virtual machine;
      +
    * connect the USB device directly to the host USB port (without any USB hub);
      +
    * try connecting the USB device to another USB port of the host (some PC have different USB controller on different USB port).
      +
    }}
      +
      +
    ===WSL2 (experimental)===
      +
    Even if STMicroelectronics strongly recommends to use a Linux<sup>&reg;</sup> environment, the ''Developer Package'' and ''Distribution Package'' work on WSL2 (Windows Sub-system Linux 2) environment. WSL is a feature provided by '''Windows 10<sup>&reg;</sup>'''.<br/>
      +
    WSL2 is a new version of the architecture that powers the Windows subsystem for Linux to run ELF64 Linux binaries on Windows (more details on [http://aka.ms/wsl2 aka.ms/wsl2]). It is available on Windows 10 since build 18917.
      +
    The  ''Developer Package'' successfully runs on WSL2 but unsuccessfully on WSL.
      +
      +
    * <u>Installing WSL2</u> :
      +
    ** To install WSL2, read [https://docs.microsoft.com/fr-fr/windows/wsl/wsl2-install https://docs.microsoft.com/fr-fr/windows/wsl/wsl2-install]
      +
    ** Once WSL2 is installed, jump to [[#Linux_PC]] to make your WSL2 ready to run ''Developer Package'' and/or ''Distribution Package''.
      +
    * <u>WSL2 limitations</u> :
      +
    ** Up to now (September 2019), WSL2 does not support hardware such as USB or serial devices ([https://docs.microsoft.com/fr-fr/windows/wsl/wsl2-faq#can-i-access-the-gpu-in-wsl-2-are-there-plans-to-increase-hardware-support more details]).
      +
    **: This means that STM32CubeProgrammer must be used through native Windows.
      +
    ** WSL2 files are not browsable from Windows native file explorer.
      +
    **: To share files between WSL2 and Windows, it is recommend to use the mount point ''/mnt/c'' from WSL2 and perform copies.
      +
    * <u>Tips for using WSL2</u> :
      +
    ** Launching graphical application : on ''wiki.ubuntu.com'', go to [https://wiki.ubuntu.com/WSL WSL] page and read the chapter [https://wiki.ubuntu.com/WSL#Running_Graphical_Applications Running Graphical Applications].
       
     
    ===References===
     
    ===References===
     
    <references/>
     
    <references/>
      +
      +
    <noinclude>
      +
    [[Category:Prerequisites]]
      +
    [[Category:STM32 MPU boards]]
      +
    {{PublicationRequestId | 18175| 2020-11-19| previeous PR  8347has been treated by BrunoB}}
      +
    </noinclude>