Difference between revisions of "PC prerequisites"

[quality revision] [quality revision]
m (Installing extra packages)
m (Installing extra packages)
Applicable for STM32MP13x lines, STM32MP15x lines

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 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 Starter Package Developer Package Distribution Package
Windows® (64 bits)
 Tested with Windows 7 and Windows 10
 Preferred version is Windows 10
native Virtual machine Virtual Machine
Linux (64 bits)
 Tested with Ubuntu®20.04 and 18.04 (with restrictions)
Native Native + additional packages (see Linux PC chapter )
Warning: 18.04 may not compatible
native + additional packages (see Linux PC chapter )


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 corresponds to the minimal validated configuration:

Hardware item Minimal validated configuration Comments / Recommendations
CPU core i5-2540M @ 2.6 GHz
2 cores (4 threads)
3-Mbyte cache
64-bit instruction set is mandatory
8 cores/threads or more is a good configuration for 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 320 Gbytes 1 Tbytes is the best suited configuration for Distribution Package

3 Linux® PC[edit]

A Linux PC with recent Ubuntu LTS (20.04 or 18.04 with restrictions) is the recommended setup. Other Ubuntu revisions could also supported (refer to Yocto reference manual[1]) .

Info white.png Information
ST solutions are tested and validated on a Linux PC running Ubuntu 20.04 LTS (Developer package may not work on Ubuntu 18.04 LTS).


3.1 Checking Internet access[edit]


  • Internet access through http and https protocols

Required at least for Developer Package and Distribution Package.

The command below enables checking internet access through http/https protocols:

 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 an 'OK' message is returned, the network is well configured. In such case, skip the rest of this section and jump to Installing extra packages.

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:

 export http_proxy=http://<MyProxyLogin>:<MyProxyPassword>@<MyProxyServerUrl>:<MyProxyPort>
 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:

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


Check again the Internet access by using the following command:

 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

Required for Distribution Package.

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

 alias sudo='sudo http_proxy=$http_proxy'

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

 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), other protocols such as git:// or ssh:// might be required.

For example, in the context of the Distribution Package, some "git fetch" commands might require "git:// protocols".
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[2] to tunnel the git:// flow into the http flow:

 sudo apt-get update
 sudo apt-get install corkscrew

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

Use the command below to test the proxy settings:

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

The command returns 'OK' if the proxy settings are correct.

3.2 Installing extra packages[edit]

Required for Developer Package and Distribution Package.

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):

 sudo apt-get update
 sudo apt-get install gawk wget git diffstat unzip texinfo gcc 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 xterm python3-subunit mesa-common-dev zstd liblz4-tool
 sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
 sudo apt-get install libmpc-dev libgmp-dev
  • Packages needed for some "Developer Package" use cases:
 sudo apt-get install build-essential libncurses5libncurses-dev libssl-dev 
  • Package for repo (used to download the "Distribution Package" source code):
Please follow the installation instructions described in repo.
 For Ubuntu 20.04, first set python3 as default:  sudo apt install python-is-python3

  • Useful tools:
 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

3.2.1 Installing extra packages for AndroidTM[edit]

Android logo.png Below information is related to the Android™ distribution
Warning white.png Warning
The STM32MPU distribution for Android™ is not available in the v4 ecosystem releases: refer to the PC prerequisites page for the v2 ecosystem releases (in archived wiki).


3.3 Additional configurations[edit]

  • Allowing up to 16 partitions per MMC

By default a maximum of 8 MMC partitions are allowed on Linux systems. 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:

 echo 'options mmc_block perdev_minors=16' > /tmp/mmc_block.conf
 sudo mv /tmp/mmc_block.conf /etc/modprobe.d/mmc_block.conf
  • 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:

 locale
LANG=en-US.UTF-8

If the locale command returns a different configuration than the one shown above, reconfigure it as follows:

 sudo update-locale LANG=en_US.UTF-8
  • Adding users in basics groups

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

 groups

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

 sudo adduser $USER <group>

Then reboot the PC.

3.4 Seting up Git user information[edit]

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


 git config --global user.name "Your Name"
 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-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 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 Downloading the Ubuntu image for the virtual machine[edit]

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

ecosystem release v4.0.0 More info.png : Setup have been validated and tested on Ubuntu 20.04 (64bits).

Download the 64-bit Ubuntu image available at [8], 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 at least 4 Gbytes),
- Network: NAT is a good easy way to benefit from a network connection within the virtual machine.

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 white.png Information
For VMware, first create a default virtual machine, then add the previously downloaded .vmdk file.

Please refer to the VMwarePlayer screenshot tutorial.

4.1.3 Launching Ubuntu image[edit]

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

The default keyboard configuration is "QWERTY".
To configure the keyboard 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 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.
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' are set to "osboxes.org" for both login and password.

Warning white.png Warning
Adjusting screen resolution:

The (default) resolution used by the virtual machine is 800x600 (smallest available). It is not automatically adjusted to the display resolution. 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 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

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 (March 2021), 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>{{ApplicableFor
|MPUs list=STM32MP13x, STM32MP15x
|MPUs checklist=STM32MP13x, STM32MP15x
}}</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 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="st-table" 
|-
! Host environment !! Starter Package !! Developer Package !! Distribution Package
|-
| '''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#Virtual Machine installation|Virtual machine]] || [[PC_prerequisites#Virtual machine installation|Virtual Machine]] 
|-
| '''Linux (64 bits)'''<br>&emsp;Tested with Ubuntu<sup>&reg;</sup> '''20.04''' and 18.04 (with restrictions)|| Native || Native + additional packages (see [[#Linux PC|Linux PC]] chapter )<br>{{highlight|Warning: 18.04 may not compatible}} || 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 requirements when using the ''Developer Package'' or ''Distribution Package''.

The table below corresponds to the minimal validated configuration:
{| class="st-table"
|-
! Hardware item !! Minimal validated configuration !! Comments / Recommendations
|-
| 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 || 8 Gbytes || '''16 Gbytes or more''' are recommended especially for ''Virtual machine'' setup, ''Developer Package'' and ''Distribution Package''.
|-
| Hard drive || 320 Gbytes || '''1 Tbytes''' is the best suited configuration for ''Distribution Package''  
|}

==Linux<sup>&reg;</sup> PC==
A Linux PC with recent '''Ubuntu LTS''' (20.04 or 18.04 with restrictions) is the recommended setup. Other Ubuntu revisions could 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|'''ST solutions are tested and validated on a Linux PC running Ubuntu 20.04 LTS''' (Developer package may not work on Ubuntu 18.04 LTS).}}

{{InternalInfo|ST employees who are connected to an ST network (ST-Ubuntu or VMWare) need to configure their environment first:
* Open a shell with bash:
The shell to use is bash, which might not be 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).
If the shell does not find the ''export'' command, there are two options:
:# Ask 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.

* Add some proxy and repo configuration functions to the bash shell. This has to be done once at first image startup:<br>

 $> mkdir -p $HOME/bin
 $> 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 code on codex/gerrit repository)
 $> echo 'source $HOME/bin/stenv.sh' >> $HOME/.bashrc
 $> exit (new terminal will source the stenv.sh)
 The proxy and git/github/repo is now correctly set when you open a new shell. 

* 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. 
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 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:
:* mount an ST network directory (such as your network home) into the virtual machine via '''sshfs''' 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/
}}

=== Checking Internet access===
{{InternalInfo|In case of use of stenv.sh, please skip that chapter}}

* <u>'''Internet access through http and https protocols'''</u>

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

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 might need to set up a proxy."

If an 'OK' message is returned, the network is well configured. 
In such case, skip the rest of this section and jump to [[#Installing extra packages|Installing extra packages]].

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:
 {{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 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 might need to set up a proxy."

* <u>'''Internet access for ''sudo'' commands'''</u>

'''Required for ''Distribution Package''.'''

By default, ''sudo'' commands are executed in the ''root'' user environment; no Internet proxy settings are applied for ''root'' users.<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'
Check that the ''sudo'' commands are 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), other protocols such as git:// or ssh:// might be required. 

For example, in the context of the ''Distribution Package'', some "git fetch" commands might require "git:// protocols".<br>

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 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>" (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

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

The command returns 'OK' if the proxy settings are correct.

=== Installing extra packages ===
'''Required for ''Developer Package'' and ''Distribution Package''.'''
<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=singleindex.html#build-host-packages| text=details here}}):
 {{PC$}} sudo apt-get update
 {{PC$}} sudo apt-get install gawk wget git diffstat unzip texinfo gcc 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 xterm python3-subunit mesa-common-dev zstd liblz4-tool
 {{PC$}} sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
 {{PC$}} sudo apt-get install libmpc-dev libgmp-dev

* Packages needed for some "Developer Package" use cases:
 {{PC$}} sudo apt-get install build-essential libncurses5libncurses-dev libssl-dev 
{{ReviewsComments|-- [[User:Kevin Huber|Kevin Huber]] ([[User talk:Kevin Huber|talk]]) 17:11, 28 July 2022 (CEST)<br />Added libncurses5 that disappeared with the edit [[https://wiki.st.com/stm32mpu/index.php?title=PC_prerequisites&oldid=85679 85679]] of the page. This package is needed to debug with CubeIde. See BZ: 132424  }}
* 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 20.04, first set python3 as default: {{PC$}} sudo apt install python-is-python3''

* 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
<section end=InstallExtraPackages />

==== Installing extra packages for Android<sup>TM</sup> ====
{{Android|{{:PC prerequisites about STM32MPU distribution for Android}}}}

=== Additional configurations ===
* Allowing up to 16 partitions per MMC
By default a maximum of 8 MMC partitions are allowed on Linux systems. 
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$}} sudo mv /tmp/mmc_block.conf /etc/modprobe.d/mmc_block.conf

* Checking 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

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

* Adding users in basics groups 
The ''user'' login must belong to the basic Linux groups such as '''disk''', '''tty''', '''dialout''' or '''plugdev'''<br>

Use the ''groups'' command 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.

=== Seting up ''Git'' user information  ===
'''Required for ''Developer Package'' and ''Distribution Package''.'''<br> 

The user Information are needed by git<ref> [[Git]] </ref> if ''commit'' and/or ''push'' commands are used: 

{{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.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-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 system===
====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.

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}}

====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>


'''{{EcosystemRelease | revision=4.0.0}}:''' {{highlight|Setup have been validated and tested on Ubuntu 20.04 (64bits).}}<br/>


Download the 64-bit Ubuntu image available at <ref>https://www.osboxes.org/ubuntu/#ubuntu-20-04-4-vmware </ref>, 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 at least 4 Gbytes),
 - Network: NAT is a good easy way to benefit from a network connection within the virtual machine.

{{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}}, first create a default virtual machine, then add the previously downloaded ''.vmdk'' file.<br>

Please refer to the [[media:VMwarePlayerHelp.pdf|VMwarePlayer screenshot tutorial]].}}

====Launching Ubuntu image====
{{Warning | For "AZERTY" keyboard users:<br>

The default keyboard configuration 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 '.' character is obtained by clicking ':' on an AZERTY keyboard configured in QWERTY.<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.}}
Default 'Ubuntu ''Credentials''' ''' are set to "osboxes.org" for both login and password.'''

{{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.
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 [[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}}

{{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 (March 2021), 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>
Line 141: Line 141:
   
 
* Packages needed for some "Developer Package" use cases:
 
* Packages needed for some "Developer Package" use cases:
  {{PC$}} sudo apt-get install build-essential libncurses5 libssl-dev  
+
  {{PC$}} sudo apt-get install build-essential libncurses-dev libssl-dev  
 
 
{{ReviewsComments|-- [[User:Kevin Huber|Kevin Huber]] ([[User talk:Kevin Huber|talk]]) 17:11, 28 July 2022 (CEST)<br />Added libncurses5 that disappeared with the edit [[https://wiki.st.com/stm32mpu/index.php?title=PC_prerequisites&oldid=85679 85679]] of the page. This package is needed to debug with CubeIde. See BZ: 132424  }}
 
   
 
* Package for repo (used to download the "Distribution Package" source code):
 
* Package for repo (used to download the "Distribution Package" source code):