3. Software Installation

Warning

Read the documentation carefully and follow every point exactly as described. Otherwise, the configuration workload in later points of the setup or the development will be significantly higher.

Getting started with foxBMS 2 requires getting the sources and installing all required software dependencies. These are the required steps:

  1. Install Git

  2. Get the foxBMS 2 sources

  3. Install the software dependencies:

    1. Install Texas Instruments (TI)’s Code Composer Studio (required for compiling)

    2. Install Texas Instruments (TI)’s HALCoGen (required for code generation)

    3. Install Python and an virtual environment (furnishes the Python environment used by foxBMS 2)

    4. Install Ruby and the Ceedling package (required for unit testing)

    5. Install GCC (required for unit testing)

    6. Install VS Code (required for developing)

    7. Check the installation

    8. (Optional) Install VS Code

These steps are described below in detail.

3.1. Install Git

Download the latest version of Git and run the installer.

3.2. Getting the Sources

The sources are available from a Git repository at https://github.com/foxBMS/ in https://github.com/foxBMS/foxbms-2. The following example shows how to clone the foxBMS 2 sources from GitHub.

In the case that you have been supplied with a “library-project” by a partner, please use this archive equivalent to the “cloned foxBMS 2 repository” in the later steps of this manual.

Note

The username in this installation manual is vulpes and needs to be replaced with the actual username.

Warning

If your user name contains whitespace (e.g., vulpes vulpes, you MUST clone the repository to another path, that does not contain whitespace, e.g., C:\foxbms-2).

git clone https://github.com/foxBMS/foxbms-2
cd foxbms-2

Note

git requires a correct proxy setup. This means that the environment variables http_proxy and https_proxy must be set accordingly to your network configuration.

Warning

Do not clone/download foxBMS 2 into a directory structure that includes whitespace.

Bad

C:\bad directory name\foxbms-2

Bad

/opt/bad directory name/foxbms-2

Good

C:\Users\vulpes\foxbms-2

Good

C:\foxbms-2

3.3. Software Prerequisites

General Hint

No software installation here should alter the PATH environment variable. When an installer asks during the setup to add something to PATH, always remove that option, whether it is explicitly mentioned in that step or not. The only exception to that rule MAY be Git and VS Code.

3.3.1. Install Code Composer Studio

Download Code Composer Studio (CCS) version 12.0.0 and run the installer (chose Windows single file installer for CCS IDE). Do not change the default installation directory chosen by the installer and let the installer proceed with the installation into the installation directory (e.g., C:\ti\ccs1031 for CCS 10.3.1). Select the Hercules™ Safety MCUs option during the installation.

Installing Code Composer Studio may take a while.

3.3.1.1. Install HALCoGen

Download HALCoGen version 04.07.01 and run the installer. Do not change the default installation directory chosen by the installer and let the installer proceed with the installation into the installation directory (i.e., C:\ti\... for HALCoGen 04.07.01 that means into C:\ti\Hercules\HALCoGen\v04.07.01).

Installing HALCoGen may take a while.

3.3.2. Install Python and Configuration

3.3.2.1. Install Python

  1. Install Python. If you have already installed Python from https://www.python.org this step can be skipped.

    Note

    The minimum required Python version is 3.10.

  2. Open a terminal and run py –version, this should print something like Python 3.12.4 or similar to the terminal:

    py --version
Python 3.12.4

3.3.2.2. Virtual Environment Creation

  1. Create a virtual environment 2025-01-pale-fox by running:

    py -m venv $env:USERPROFILE\foxbms-envs\2025-01-pale-fox

  2. Activate the virtual environment by running:

    &"$env:USERPROFILE\foxbms-envs\2025-01-pale-fox\Scripts\activate.ps1"

  3. Install the required packages by running:

    cd path\to\foxbms-2 # cd into the root of the repository
python -m pip install -r requirements.txt --no-deps

3.3.3. Install Ruby and Add Required Gems

  1. Download the installer version for Ruby 3.1.3-x64 without Devkit.

  2. Use C:\Ruby\Ruby3.1.3-x64 as installation directory

  3. Do NOT add Ruby to PATH.

  4. Install the required packages, i.e., Gems by running:

    cd path\to\foxbms-2 # cd into the root of the repository
cd tools\vendor\ceedling
C:\Ruby\Ruby3.1.3-x64\bin\bundle.bat install # install the Ruby Gems

3.3.4. Install GCC

Note

Installing MinGW64 requires 7-Zip to be installed. 7-Zip can be download from https://7-zip.org.

  1. Download MinGW-W64 version x86_64-posix-seh from sourceforge.net (use exactly this 7z-archive).

  2. Extract the archive.

  3. Copy the extracted mingw64 directory to C:\mingw64\x86_64-8.1.0-release-posix-seh-rt_v6-rev0.

  4. Verify that GCC is available at C:\MinGW64\x86_64-8.1.0-release-posix-seh-rt_v6-rev0\mingw64\bin\gcc.exe.

3.3.5. Install Doxygen

  1. Download Doxygen version 1.11.0 from GitHub. (use this zip-archive).

  2. Extract the archive.

  3. Copy the extracted archive to C:\Users\<username>\doxygen\1.11.0.

  4. Verify that doxygen.exe is available at C:\Users\<username>\doxygen\1.11.0\doxygen.exe.

3.3.6. Install Graphviz

  1. Download GraphViz version 11.0.0 from https://graphviz.org/download. (use this zip-archive).

  2. Extract the archive.

  3. Copy the extracted archive to C:\Users\<username>\graphviz\11.0.0.

  4. Verify that dot.exe is available at C:\Users\<username>\graphviz\11.0.0\bin\dot.exe.

3.3.7. Check Installation

Check that all required software is installed by running in cmd.exe or PowerShell.

cd path\to\foxbms-2 # cd into the root of the repository
.\fox.ps1 install --check

3.3.8. (Optional) Install VS Code

foxBMS 2 supports developing with Visual Studio Code (hereinafter code).

  1. Download code from the project website at Visual Studio Code.

  2. Install code: foxBMS 2 recommends installing code with the User Installer, which does not require elevated rights.

  3. Optional: Let the installer add code to the PATH variable.

3.3.9. Environment Updates

Sometimes it might be required to update the build environment. It that is the case, it is then mentioned in the Changelog.

To update the build environment the following steps must be done:

Note

The placeholder <name-of-the-new-env> must be replaced with the actual name of the new build environment, which is then documented in the Changelog.

  1. Create a virtual environment <name-of-the-new-env> by running:

    py -m venv $env:USERPROFILE\foxbms-envs\<name-of-the-new-env>

  1. Activate the virtual environment by running:

    &"$env:USERPROFILE\foxbms-envs\<name-of-the-new-env>\Scripts\activate.ps1"

  1. Install the required packages by running:

    cd path\to\foxbms-2 # cd into the root of the repository
python -m pip install -r requirements.txt --no-deps

3.4. Debugger toolchain setup

For the development of an embedded system both a way of downloading the software into the target and debugging the running software in the target is necessary. Since the setup is highly dependent on the selected toolchain, this manual does not give any details on the installation of such a debugger toolchain. The manuals of the tool vendors are exhaustive on the topic of installation and setup.

More details on the selection and usage of debugger toolchains can be found in Debugging the Application.