3. Software Installation

This document describes how to setup the host machine for development of foxBMS 2.

Note

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.

Note

Some programs are installed into a specific foxBMS 2 prefix. This is mostly then done, when the installers do not support side-by-side or versioned installations by themself.

Warning

• All commands shall be run in PowerShell 7 or later.

• All commands shall be run in the root of the repository.

Warning

These are the installation instructions for the host machine. These are NOT the instructions for installing (i.e., flashing) the created binary on the target. Flashing the binary requires a hardware debugger/flashing tool.

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 TI Code Composer Studio (required for compiling)

4. Install TI HALCoGen (required for code generation)

5. Install Python (required for tools)

6. Install virtual Python environment (required for tools)

7. Install Ruby (required for unit testing)

8. Install Ruby gems (required for unit testing)

9. Install mingw-w64 (required for unit testing)

10. Install Doxygen (required for building the documentation)

11. Install Graphviz (required for building the documentation)

12. Install drawio-desktop (required for building the documentation)

13. Install VS Code (required developing)

14. Check the installation

Note

No software installation here should change 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.

The installation steps are described below in detail.

3.1. Install Git

1. Download the latest version of Git at https://git-scm.com/ and run the installer.

2. Optional: Let the installer add Git to the PATH variable.

3.2. Get the foxBMS 2 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

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.

Good	Bad
C:\Users\vulpes\foxbms-2	C:\Users\my user name\foxbms-2
/opt/devel/foxbms-2	/opt/bad directory name/foxbms-2

Clone the repository by running

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

3.3. Install TI Code Composer Studio

Download Code Composer Studio (CCS) version 12.8.1 and run the installer (chose the single file (offline) installer for Code Composer Studio IDE (all features, devices) depending on your host platform).

WindowsLinux

When running the installer:

1. 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\ccs1281 for CCS 12.8.1).

2. Select the Hercules™ Safety MCUs option during the installation.

Installing TI Code Composer Studio may take a while.

3.4. Install TI HALCoGen

WindowsLinux

Download TI HALCoGen version 04.07.01 from https://www.ti.com/tool/HALCOGEN and run the installer. When running 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 TI HALCoGen 04.07.01 that means into C:\ti\Hercules\HALCoGen\v04.07.01).

Installing TI HALCoGen may take a while.

3.5. Install Python

WindowsLinux

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

   Note

   The required Python version is exactly 3.12.x.

2. Open a terminal and run py -3.12 --version, this should print something like Python 3.12.8 or similar:

   py -3.12 --version
   Python 3.12.8
   

3.6. Install virtual Python environment

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

   WindowsLinux

   PowerShellGit bash

   py -3.12 -m venv C:\foxbms\envs\2025-03-pale-fox
   

2. Activate the virtual environment by running:

   WindowsLinux

   PowerShellGit bash

   C:\foxbms\envs\2025-03-pale-fox\Scripts\activate.ps1
   

3. Install the required packages by running:

   Note

   pip requires a correct proxy setup.

   python -m pip install -r requirements.txt
   

The virtual environment includes the pre-commit framework (https://pre-commit.com/). The pre-commit framework installs its dependencies defined in .pre-commit-config.yaml by itself when it is run and dependencies are missing.

3.7. Install Ruby

Note

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

WindowsLinux

1. Download the zip-archive Ruby 3.4.2-1 (x64).

2. Extract the archive to C:\foxbms\Ruby\Ruby34-x64.

3.8. Install Ruby gems

Install the required Ruby packages, i.e., Ruby gems by running:

WindowsLinux

PowerShellGit bash

C:\foxbms\Ruby\Ruby34-x64\bin\gem.cmd install --install-dir C:\foxbms\Ceedling\1.0.1 ceedling

3.9. Install mingw-w64

WindowsLinux

Note

Installing mingw-w64 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 this 7z-archive).

2. Extract the archive.

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

4. Verify that gcc.exe is available at C:\foxbms\mingw-w64\x86_64-8.1.0-release-posix-seh-rt_v6-rev0\bin\gcc.exe.

3.10. Install Doxygen

WindowsLinux

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

2. Extract the archive.

3. Copy the extracted archive to C:\foxbms\Doxygen\1.13.2.

4. Verify that doxygen.exe is available at C:\foxbms\Doxygen\1.13.2\doxygen.exe.

3.11. Install Graphviz

WindowsLinux

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

2. Extract the archive.

3. Copy the extracted archive to C:\foxbms\Graphviz\12.2.1.

4. Verify that dot.exe is available at C:\foxbms\Graphviz\12.2.1\bin\dot.exe.

3.12. Install drawio-desktop

WindowsLinux

1. Download drawio-desktop version 26.0.9 from https://github.com/jgraph/drawio-desktop/releases (use this installer).

2. Run the installer and use the default installation directory.

3. Verify that draw.io.exe is available at C:\Program Files\draw.io\draw.io.exe.

3.13. Install VS Code

foxBMS 2 supports development using Visual Studio Code.

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

2. Run the installer.

3. Optional: Let the installer add VS Code to the PATH variable.

3.14. Installation Check

Check that all required software is installed by running:

WindowsLinux

PowerShellGit bash

.\fox.ps1 install --check

After following these steps, the check shall succeed and all required software has been successfully installed.

3.15. 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:

   WindowsLinux

   PowerShellGit bash

   py -3.12 -m venv C:\foxbms\envs\<name-of-the-new-env>
   

2. Activate the virtual environment by running:

   WindowsLinux

   PowerShellGit bash

   C:\foxbms\envs\<name-of-the-new-env>\Scripts\activate.ps1
   

3. Install the required packages by running:

   Note

   pip requires a correct proxy setup.

   python -m pip install -r requirements.txt
   

3.16. 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.