Installing Bridle manually

The recommended way to get started with Bridle is to use the Desktop Installer. See the Installing Bridle through … t.b.d. (TBD) Desktop Installer section for information about how to install Bridle through Desktop Installer for Desktop.

Note

If you use the Desktop Installer to install Bridle, you can skip this section of the documentation. If you prefer to install the toolchain manually, or if you run into problems during the installation process, see the following documentation for instructions.

To manually install Bridle, you must install all required tools and clone the Bridle repositories. See the following sections for detailed instructions.

The first two steps, Installing the required tools and Installing the toolchain, are similar to the installation steps in Zephyr’s Getting Started Guide. If you already have your system set up to work with the Zephyr OS, you can skip these steps.

See Supported operating systems for information on the supported operating systems and Zephyr features.

Installing the required tools

The current minimum required version for the main dependencies are:

Tool	Min. Version
CMake	3.20
Python	3.8
Device tree compiler	1.4.6

The installation process is different depending on your operating system.

LinuxmacOSWindows

To install the required tools on Ubuntu, complete the following steps:

1. If using an Ubuntu version older than 22.04, it is necessary to add extra repositories to meet the minimum required versions for the main dependencies listed above. In that case, download, inspect and execute the Kitware archive script to add the Kitware APT repository to your sources list. A detailed explanation of kitware-archive.sh can be found here kitware third-party apt repository:

   wget https://apt.kitware.com/kitware-archive.sh
   sudo bash kitware-archive.sh
   

2. Use apt to install the required dependencies:

   sudo apt install --no-install-recommends git cmake ninja-build gperf \
     ccache dfu-util device-tree-compiler wget \
     python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \
     make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1
   

3. Verify the versions of the main dependencies installed on your system by entering:

   cmake --version
   python3 --version
   dtc --version
   

   Check those against the versions in the table in the beginning of this section. Refer to the Install Linux Host Dependencies page for additional information on updating the dependencies manually.

For additional information and instructions for other Linux operating systems, see the Install Requirements and Dependencies section in the Zephyr documentation.

Installing the toolchain

Important

Make sure to install the version that is mentioned below. Other versions might not work with this version of Bridle. Refere the list of required tools for the correct and tested version!

Note that other versions of Bridle might require a different toolchain version.

Preferred default toolchain

To be able to cross-compile your applications for all the various target architectures, you must install at least version 0.16.4 of the Zephyr SDK. Refere the list of required tools for the correct and tested version!

To set up the toolchain, complete the following steps (refere also Zephyr’s documentation in “Zephyr SDK installation”):

1. Download the Zephyr SDK bundle for your operating system.

   Operating System	Minimum version	Tested version
   Linux	0.16.4	0.16.5
   macOS	0.16.4	0.16.5
   Windows	0.16.4	0.16.5

2. Extract the bundle into a folder of your choice. We recommend to use the folder /opt on Linux or macOS and %PROGRAMFILES% on Windows.

   Make sure that the folder name does not contain any spaces or special characters.

3. Run the Zephyr SDK setup script found in this new folder: setup.sh on Linux or macOS and setup.cmd on Windows.

There are no further configuration steps required when compiling, as the Zephyr SDK is the preferred toolchain used by Bridle.

Alternative toolchain for ARM

Arm GNU toolchain

To be able to cross-compile your applications for ARM targets, you can use at least version 11.2-2022.02 of the Arm GNU Toolchain too. The Arm GNU Toolchain is the successor to the GNU Arm Embedded Toolchain, which has been considered obsolete since 2022 and should no longer be used. Refere the list of required tools for the correct and tested version!

For installation and handling of the Arm GNU Toolchain with Zephyr, the same steps apply as for the GNU Arm Embedded Toolchain. From Zephyr’s point of view, only the name has changed. Therefore the same variable prefixes will be used (GNUARMEMB). For more details, see the section GNU Arm Embedded in the Zephyr documentation.

To set up the toolchain, complete the following steps:

1. Download the Arm GNU Toolchain for your operating system.

   Operating System	Minimum version	Tested version
   Linux	11.2-2022.02	13.2.rel1
   macOS	11.2-2022.02	13.2.rel1
   Windows	11.2-2022.02	13.2.rel1

2. Extract the toolchain into a folder of your choice. We recommend to use the folder ~/gnuarmemb on Linux or macOS and c:\gnuarmemb on Windows.

   Make sure that the folder name does not contain any spaces or special characters.

3. If you want to build and program applications from the command line, define the environment variables for the Arm GNU toolchain. Depending on your operating system:

   LinuxmacOSWindows

   Open a terminal window and enter the following commands (assuming that you have installed the toolchain to ~/gnuarmemb; if not, change the value for GNUARMEMB_TOOLCHAIN_PATH):

   export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
   export GNUARMEMB_TOOLCHAIN_PATH="${HOME}/gnuarmemb"
   

1. Set the environment variables persistently. Depending on your operating system:

   LinuxmacOSWindows

   Define the environment variables in the ~/.zephyrrc file as described in Setting up the build environment. This will allow you to avoid setting them every time you open a terminal window.

GNU Arm Embedded toolchain

Warning

Obsolete and depricated since 2022! Do not use for new products.

To be able to cross-compile your applications for ARM targets, you can use at least version 10-2020-q4-major of the GNU Arm Embedded Toolchain too. Refere the list of required tools for the correct and tested version!

For installation and handling of the GNU Arm Embedded Toolchain with Zephyr, the same steps apply as for the Arm GNU Toolchain. For more details, see the section GNU Arm Embedded in the Zephyr documentation. The GNU Arm Embedded Toolchain is the discontinued predecessor of the Arm GNU Toolchain and should no longer be used.

To set up the toolchain, complete the steps above for Arm GNU Toolchain.

Operating System	Minimum version	Tested version
Linux	10-2020-q4-major	10.3-2021.10
macOS	10-2020-q4-major	10.3-2021.10
Windows	10-2020-q4-major	10.3-2021.10

STM32CubeCLT (GNU tools for STM32)

Warning

Special vendor specific toolchain for STM32 by STMicroelectronics.

To be able to cross-compile your applications for ARM targets or feel better to use a special vendor toolchain for STM32 based platforms maintained by STMicroelectronics, you can use at least version 1.11.1 (10.3.rel1) of the STM32CubeCLT (GNU tools for STM32) too. Refere the list of required tools for the correct and tested version!

The STM32CubeCLT (GNU tools for STM32) is an all-in-one multi-OS command-line toolset, which is part of the STM32Cube ecosystem. It is a toolset for third-party integrated development environment (IDE) providers, allowing the use of STMicroelectronics proprietary tools within their own IDE frameworks.

For installation the STM32CubeCLT (GNU tools for STM32), see the accompanying original documentation by STMicroelectronics. For handling the STM32CubeCLT (GNU tools for STM32) with Zephyr you have to choose the same way as for other common cross-compilers. For more details, see the section Other Cross Compilers in the Zephyr documentation.

To set up the toolchain, complete the following steps:

1. Download the STM32CubeCLT (GNU tools for STM32) for your operating system.

   Operating System	Minimum version	Tested version
   Linux	1.11.1 (10.3.rel1)	1.14.0 (11.3.rel1)
   macOS	1.11.1 (10.3.rel1)	1.14.0 (11.3.rel1)
   Windows	1.11.1 (10.3.rel1)	1.14.0 (11.3.rel1)

2. Extract the toolchain into a folder of your choice. We recommend to use the default as specified by STMicroelectronics, folder /opt/st/stm32cubeclt on Linux, /Applications/STM32CubeCLT on macOS and C:\ST\STM32CubeCLT on Windows.

   Make sure that the folder name does not contain any spaces or special characters.

3. If you want to build and program applications from the command line, define the environment variables for the GNU tools for STM32. Depending on your operating system:

   LinuxmacOSWindows

   Open a terminal window and enter the following commands (assuming that you have installed the toolchain to /opt/st/stm32cubeclt; if not, change the value for CROSS_COMPILE):

   export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
   export CROSS_COMPILE="/opt/st/stm32cubeclt/GNU-tools-for-STM32/bin/arm-none-eabi-"
   

4. Set the environment variables persistently, proceed as described above for the Arm GNU Toolchain.

MCUXpresso IDE (Arm GNU Toolchain)

Warning

Special vendor specific toolchain for General Purpose MCU by NXP.

To be able to cross-compile your applications for ARM targets or feel better to use a special vendor toolchain for i.MX (RT), Kinetis or LPC based platforms maintained by NXP, you can use at least version 11.9.0 (12.3.rel1) of the MCUXpresso IDE (Arm GNU Toolchain) too. Refere the list of required tools for the correct and tested version!

The MCUXpresso IDE (Arm GNU Toolchain) is the default integrated development environment for NXP MCUs based on Arm Cortex-M cores and comes with a rich set of tools for debug and compilation based on the standard Arm GNU toolchain.

For installation the MCUXpresso IDE (Arm GNU Toolchain), see the accompanying original documentation by NXP. For handling the MCUXpresso IDE (Arm GNU Toolchain) with Zephyr you have to choose the same way as for other common cross-compilers. For more details, see the section Other Cross Compilers in the Zephyr documentation.

To set up the toolchain, complete the following steps:

1. Download the MCUXpresso IDE (Arm GNU Toolchain) for your operating system.

   Operating System	Minimum version	Tested version
   Linux	11.9.0 (12.3.rel1)	11.9.0 (12.3.rel1)
   macOS	11.9.0 (12.3.rel1)	11.9.0 (12.3.rel1)
   Windows	11.9.0 (12.3.rel1)	11.9.0 (12.3.rel1)

2. Extract the toolchain into a folder of your choice. We recommend to use the default as specified by NXP, folder /usr/local/mcuxpressoide on Linux, /Applications/MCUXpressoIDE on macOS and C:\NXP\MCUXpressoIDE on Windows.

   Make sure that the folder name does not contain any spaces or special characters.

3. If you want to build and program applications from the command line, define the environment variables for the Arm GNU Toolchain. Depending on your operating system:

   LinuxmacOSWindows

   Open a terminal window and enter the following commands (assuming that you have installed the toolchain to /usr/local/mcuxpressoide; if not, change the value for CROSS_COMPILE):

   export ZEPHYR_TOOLCHAIN_VARIANT=cross-compile
   export CROSS_COMPILE="/usr/local/mcuxpressoide/ide/tools/bin/arm-none-eabi-"
   

4. Set the environment variables persistently, proceed as described above for the Arm GNU Toolchain.

Getting the Bridle code

Bridle consists of a set of Git repositories. Every Bridle release consists of a combination of these repositories at different revisions. The revision of each of those repositories is determined by the current revision of the main (or manifest) repository, tiac-bridle.

Note

The latest state of development is on the main branch of the tiac-bridle repository. To ensure a usable state, the tiac-bridle repository defines the compatible states of the other repositories. However, this state is not necessarily tested. For a higher degree of quality assurance, check out a tagged release.

Therefore, unless you are familiar with the development process, you should always work with a specific release of Bridle.

To manage the combination of repositories and versions, Bridle uses West (Zephyr’s meta-tool). The main repository, tiac-bridle, contains a west manifest file, west.yml, that determines the revision of all other repositories. This means that bridle acts as the manifest repository, while the other repositories are project repositories.

You can find additional information about the repository and development model in the development model section.

See the west documentation for detailed information about the tool itself.

Setup Python Virtual Environment

Create a new and complet empty workspace directory (e.g. workspace), change into this new folder and execute:

LinuxmacOSWindows

python3 -m venv --clear --copies --prompt="$(basename $(pwd))[$(python3 --version)]" .env
source .env/bin/activate
pip3 install --upgrade pip
pip3 install --upgrade setuptools

Installing west

Install west by entering the following command:

LinuxmacOSWindows

pip3 install west

You only need to do this once.

Like any other Python package, the west tool is updated regularly. Therefore, remember to regularly check for updates:

LinuxmacOSWindows

pip3 install --upgrade west

Cloning the repositories

To clone the repositories, complete the following steps:

1. Open a command window and go into the workspace directory. This folder will hold all Bridle repositories together with the Python Virtual Environment that is already created and setup as described above.

2. Determine what revision of Bridle you want to work with. The recommended way is to work with a specific release.

   • To work with a specific release, the revision is the corresponding tag (for example, v3.6.99). You can find the tag in the Release Notes of the release.

   • To work with a development tag, the revision is the corresponding tag (for example, 1.0.99-dev1)

   • To work with a branch, the revision is the branch name (for example, main to work with the latest state of development).

   • To work with a specific state, the revision is the SHA (for example, 4b44408145d4843f2bf13952a7723680240d0f95).

3. Initialize west with the revision of Bridle that you want to check out, replacing BRIDLE_revision with the revision:

   west init -m https://github.com/tiacsys/bridle --mr BRIDLE_revision

   For example, to check out the v3.6.99 release, enter the following command:

   west init -m https://github.com/tiacsys/bridle --mr v3.6.99

   To check out the latest state of development, enter the following command:

   west init -m https://github.com/tiacsys/bridle --mr main

   Note

   If you get an error message when running west, update west to the latest version. See Troubleshooting West if you need more information.

   Initializing west with a specific revision of the manifest file does not lock your repositories to this version. Checking out a different branch or tag in the tiac-bridle repository and running west update changes the version of Bridle that you work with.

   This will clone the manifest repository tiac-bridle into bridle.

4. Enter the following command to clone the project repositories:

   west update
   

5. Export the Zephyr CMake package and also for Bridle. This allows CMake to automatically load the boilerplate code required for building Bridle applications:

   west zephyr-export
   west bridle-export
   

Your directory structure now looks similar to this:

workspace
 ├── .env
 ├── .west
 ├── bridle
 ├── modules
 │   ├── fs
 │   │   └── fatfs
 │   ├── hal
 │   │   ├── altera
 │   │   ├── cmsis
 │   │   ├── espressif
 │   │   ├── stm32
 │   │   └── xtensa
 │   └── lib
 │       └── canopennode
 ├── tools
 │   └── net-tools
 ├── zephyr
 └── ...

Note that there are additional folders, and that the structure might change. The full set of repositories and folders is defined in the manifest file.

Updating the repositories

If you work with a specific release of Bridle, you do not need to update your repositories, because the release will not change. However, you might want to switch to a newer release or check out the latest state of development.

To manage the bridle repository (the manifest repository), use Git. To make sure that you have the latest changes, run git fetch origin to fetch the latest code from the tiac-bridle repository. Checking out a branch or tag in the bridle repository gives you a different version of the manifest file. Running west update will then update the project repositories to the state specified in this manifest file.

Note

If you get an error message when running west, update west to the latest version. See Troubleshooting West if you need more information.

For example, to switch to release v3.6.99 of Bridle, enter the following commands in the workspace/bridle directory:

git fetch origin
git checkout v3.6.99
west update

To update to a particular revision (SHA), make sure that you have that particular revision locally before you check it out (by running git fetch origin):

git fetch origin
git checkout 4b44408145d4843f2bf13952a7723680240d0f95
west update

To switch to the latest state of development, enter the following commands:

git fetch origin
git checkout origin/main
west update

Note

Run west update every time you change or modify the current working branch (for example, when you pull, rebase, or check out a different branch). This will bring the project repositories to the matching revision defined by the manifest file.

Installing additional Python dependencies

The Bridle requires additional Python packages to be installed.

Use the following commands to install the requirements for each repository.

LinuxmacOSWindows

Open a terminal window in the workspace folder and enter the following commands:

pip3 install --upgrade --requirement zephyr/scripts/requirements.txt
pip3 install --upgrade --requirement bridle/scripts/requirements.txt

Installing … t.b.d. (TBD) IDE

t.b.d.

Setting up the build environment

Before you start building and programming a sample application, you must set up your build environment.

Setting up the … t.b.d. (TBD) IDE environment

t.b.d.

Setting up executables

The process is different depending on your operating system.

LinuxmacOSWindows

Make sure the locations of tools are added to the PATH variable. On Linux, … t.b.d. (TBD) IDE uses the PATH variable to find executables if they are not set in … t.b.d. (TBD) IDE.

Setting up the command line build environment

If you want to build and program your application from the command line, you must set up your build environment by defining the required environment variables every time you open a new command prompt or terminal window.

See Environment Variables and Important Build System Variables information about the various relevant environment variables.

Define the required environment variables as follows, depending on your operating system:

LinuxmacOSWindows

Navigate to the workspace folder and enter the following command: source zephyr/zephyr-env.sh

If you need to define additional environment variables, create the file ~/.zephyrrc and add the variables there. This file is loaded automatically when you run the above command.