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 installation process is different depending on your operating system.

The recommended way for installing the required tools on Windows is to use Chocolatey, a package manager for Windows. Chocolatey installs the tools so that you can use them from a Windows command prompt.

To install the required tools, complete the following steps:

  1. Install chocolatey.

  2. Open a cmd.exe window as Administrator. To do so, press the Windows key, type “cmd.exe”, right-click the result, and choose Run as Administrator.

  3. Disable global confirmation to avoid having to confirm the installation of individual programs:

    choco feature enable -n allowGlobalConfirmation

  4. Use choco to install the required dependencies:

    choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
choco install ninja gperf python git dtc-msys2

  5. Close the window and open a new cmd.exe window as a regular user to continue.

Installing the toolchain

To be able to cross-compile your applications for ARM targets, you must install version 10-2020-q4-major of the GNU Arm Embedded Toolchain.

Important

Make sure to install the version that is mentioned above. Other versions might not work with this version of Bridle.

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

To set up the toolchain, complete the following steps:

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

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

    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 Arm Embedded toolchain. Depending on your operating system:

    Open a command prompt and enter the following commands (assuming that you have installed the toolchain to c:\gnuarmemb; if not, change the value for GNUARMEMB_TOOLCHAIN_PATH):

    set ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
set GNUARMEMB_TOOLCHAIN_PATH=c:\gnuarmemb

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

    Add the environment variables as system environment variables or define them in the %userprofile%\zephyrrc.cmd file as described in Setting up the build environment. This will allow you to avoid setting them every time you open a command prompt.

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:

for /f "delims=" %A in ('python --version') do set PV=%A
python -m venv --clear --copies --prompt="%CD%[%PV%]" .env
.envScriptsactivate
python -m pip install --upgrade pip
python -m pip install --upgrade setuptools

Installing west

Install west by entering the following command:

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:

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, v2.7.1). 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 v2.7.1 release, enter the following command:

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

    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 a Zephyr CMake package. This allows CMake to automatically load the boilerplate code required for building Bridle applications:

    west zephyr-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 v2.7.1 of Bridle, enter the following commands in the workspace/bridle directory:

git fetch origin
git checkout v2.7.1
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.

Open a command prompt 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

Setting up the build environment

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

Setting up executables

The process is different depending on your operating system.

Make sure the locations of tools are added to the PATH variable. On Windows, … 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 Setting 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:

Navigate to the workspace folder and enter the following command: zephyr\zephyr-env.cmd

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