Skip to content

Development Setup Guide (DRAFT)

By ethan6138, Random121 · Last updated: October 8, 2026 · Created: October 4, 2026

This document describes instructions to setup an environment for developing and building the Ulysses firmware.

Table of contents

Installing the build toolchain

Installing ARM GNU Toolchain

The Arm GNU Toolchain is the GNU cross-compiler toolchain for Arm targets.

To download the cross-compiler, visit the website and scroll down to the list of releases. Click on the link for the release you want and expand the collapsible section for your host operating system (e.g. Windows, Linux, macOS). In the list of toolchains, choose the download for a arm-none-eabi target.

[!note] For Windows and macOS users You will have the option of downloading the cross-compiler toolchain in the form of an installer (i.e. .msi for Windows, .pkg for macOS). If you choose to use the installer, you must take note of the path where toolchain files are installed. For Windows, the installer will show the path during installation. For macOS, you will have to search for the files, although they likely will appear under /Applications/.

If you are not using the installer, download the archive for the toolchain and extract it to a known location. For example, under a /projects/devkits/ folder.

For both an installer and archive, you will have to add the toolchain binaries to your system path so that you can run it from the command line. In the extracted directory of your toolchain, you will see a bin/ folder. This bin/ folder must contain files named arm-none-eabi-* (e.g. arm-none-eabi-gdb). If you do not see these files, you are in the wrong folder! Go up 2 directory levels and look for the bin/ folder again. Take the full path of the bin/ folder and add it to your system path. How you set this will depend on your operating system, so consult online resources!

To verify you have installed the toolchain correctly, run the command for your operating system in a new terminal (ensure your current working directory is NOT in the bin/ folder).

# Windows
arm-none-eabi-gcc.exe --version

# macOS
arm-none-eabi-gcc --version

# Linux
arm-none-eabi-gcc --version

You should see an output that looks like the following if it is installed correctly.

arm-none-eabi-gcc (Arm GNU Toolchain 15.3.Rel1 (Build arm-15.149)) 15.3.1 20260627
Copyright (C) 2025 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Installing Ninja

Ninja is the build system we use for the firmware. You will not interact with it directly, but rather through CMake.

It can be installed by following the steps on the site.

You can verify your installation by running the command

ninja --version

Installing CMake

CMake is the meta-build system that we use for the firmware.

Follow the instructions on its site to download and install it for your host machine. Ensure that you are using a version greater or equal to 3.22.

You can verify your installation by running the command

cmake --version

Setting up VS Code

We use Visual Studio Code (VS Code) as our primary development editor.

Installing VS Code

Follow the steps provided by the official guide on Setting up Visual Studio Code.

Installing extensions

[!important] Unless you have your own working extension setup, you should definitely install these recommended extensions.

[!important] The Cortex-Debug extension on the VSCode marketplace is very outdated. Please download the latest pre-release for the extension from their release page. To install this extension, see the following VSCode guide for installing VSIX.

To view the recommended extensions, open the VS Code Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and run the Extensions: Show Recommended Extensions command. This will open up the WORKSPACE RECOMMENDATIONS section of the EXTENSIONS sidebar. To download all the recommended extensions, click the Install Workspace Recommended Extensions button (displayed as a cloud icon).

Alternatively, you can install the recommended extensions manually using the extension identifiers listed in .vscode/extensions.json.

Adding debugging support to VS Code

This section will describe how to setup remote debugging support in VS Code for the firmware.

Installing pyOCD

pyOCD is a Python command line tool that provides a bunch of debugging functionality for Arm Cortex MCUs. It is similar to tools like OpenOCD and J-Link.

Importantly for us, it provides a GDB server that allows us to debug the MCU over a console or GUI debugger.

pyOCD provides an official install guide that you should follow. It officially lists pip and pipx as the package installer you should use for the tool. However, I would also recommend you consider package managers like uv. If you are using uv, you can install pyOCD using the command

uv tool install pyocd

To verify that you installed pyOCD correctly, run the following command

pyocd --version

Fixing pyOCD USB permissions for Linux

[!note] This section is for Linux users only If you are not a Linux user, you can ignore this section.

As a rule of thumb, do not run pyOCD with sudo privileges.

Follow the official pyOCD installation guide for setting up udev rules. They have provided an official set of rules that you can use to get support for your specific debug probe.

Adding MCU support to pyOCD

For detailed information about pyOCD support for various targets, see the official target support documentation.

pyOCD has builtin support for a set of MCUs. You can list all the supported builtin targets using

pyocd list --targets -s builtin

If you don't see your MCU listed, you can add support for it through CMSIS Device Family Packs (DFP). To install a DFP for your MCU, first try searching for the exact DFP name using

pyocd pack find <family>

For our STM32H745ZIT6 MCU, you can use the command

pyocd pack find STM32H745Z

and receive the following list

  Part            Vendor               Pack                 Version   Installed  
---------------------------------------------------------------------------------
  STM32H745ZGTx   STMicroelectronics   Keil.STM32H7xx_DFP   4.1.3     True       
  STM32H745ZITx   STMicroelectronics   Keil.STM32H7xx_DFP   4.1.3     True

then you can install the DFP using the part name STM32H745ZITx

pyocd pack install STM32H745ZITx

If you have installed the DFP correctly, running

pyocd list --targets

should show the MCU you wanted to add (i.e. STM32H745ZITx).

Optional tools

These are tools that are not used regularly for development but may have a purpose for certain situations.

Installing STM32CubeMX

[!important] A third-party account is needed You will need a myST account to download and install this tool.

STM32CubeMX is a tool provided by ST for graphically configuring STM32 MCUs and MPUs, as well as provide generation of initialization code.

It can be installed by downloading and running the appropriate installer for your operating system in the Get Software section on its web page.

We use STM32CubeMX for configuring pins on our MCU as well as bootstrapping the initial project. Configuration files for STM32CubeMX have the extension .ioc.