FlexSEA Wiki

A WEARABLE ROBOTICS TOOLKIT

User Tools

Site Tools


manage:build_system

Dephy Build System

Overview

This page provides information on how to work with Dephy's codebase to build existing projects as well as create new ones that will play nicely within the ecosystem.

Tools

CMake

The most commonly used language in our codebase is C. This is because all the embedded software, as well as a large portion of our shared code is written in C. Traditionally C projects were primarily compiled and maintained with Makefiles. Makefiles can be a lot of work to maintain, and are often prone to user error. They also have limited functionality and people without Makefile experience can be in for trouble when first using them. However they do have fine grained control over how your project is built.

In recent years IDEs have taken over the job on some projects as they can manage the Makefiles for a developer and can be quick to get started with. Their main drawback is often portability. For instance, project properties in eclipse are in a large, primarily unreadable xml file that are difficult to share with large teams of developers. Eclipse will also generate a Makefile for you, and has been known to do some screwy things in the process. Overall IDEs provide convenience to developers but often lack the control and portability necessary for timely production releases of software.

CMake has a nice balance of control, portability, and ease of use. Essentially it has as much control as Makefiles but can be easier to use and has more features. It can be a bit harder to get started with than using IDEs, but its advantages over IDEs include control over what exactly gets built and portability for multiple developers to more easily work together.

For these reasons we have migrated all Dephy STM32 firmware as well as Plan Stack to a CMake build system.

The full CMake documentation can be found here: https://cmake.org/cmake/help/v3.15/manual/cmake.1.html

Every CMake project has a CMakeLists.txt file in the root directory of the project. This file then may include other CMake files, but is typically the starting point for how the project gets compiled. To learn more about how CMake is being used in a specific project the best starting point can be to open the CMakeLists.txt and see what types of actions it performs.

Ninja

You may notice our setup instructions say to install Ninja. We are currently using Ninja in conjunction with CMake. CMake can either generate Makefiles or Ninja files. Because we do not need to manually edit the Makefiles it does not make that much difference to us. We ran into issues running mingw-make in a bash terminal on Windows. Ninja has been much better at being cross platform and does not have this issue. It is also faster than make so essentially we have run into no downsides with Ninja and it has been faster and more cross platform than make so that was the extent of our decision to use Ninja with CMake.

Bash

We have set up bash scripts that can be used to compile various parts of the system including Manage, Habsolute, BMS, Plan Stack, and the GUI. They allow for the automation of these types of tasks where all those applications mentioned can be compiled for all their target hardware platforms with a single command. Bash scripts are also useful for automated testing and other tasks as we get more into production.

Our bash scripts for the STM32 devices take an APP and HW_PLATFORM as the only two necessary parameters. Based on these pieces of information it can then automatically call CMake and Ninja.

In addition to just compiling a single codebase for different targets it can also perform device configuration (like flashing an ID into flash) and running other scripts. Here are some examples of how our STM32 bash script can be used:

./manage_builder.sh ActPack-rigid1.0
./manage_builder.sh ActPack-rigid0.2 download
./manage_builder.sh Exo-rigid2.0
./manage_builder.sh ActPack-rigid3.0-left
./manage_builder.sh CycleExo-rigid1.0
./manage_builder.sh CycleTester-rigid0.1
./manage_builder.sh all
./manage_builder.sh f7 debug
./manage_builder.sh erase Exo-rigid2.0 download debug
./manage_builder.sh wireless-setup
./manage_builder.sh update
./manage_builder.sh Habsolute-habs0.3
./manage_builder.sh BMS-bms0.1
./manage_builder.sh sub-common
./manage_builder.sh Exo-spec
./manage_builder.sh Exo-id-5A63 download

Bash has pretty good support on Windows these days so is also now relatively cross platform.

CLion

The bash scripts mentioned in the previous section are all that is necessary to compile our projects. Using any text editor like VIM or Sublime Text is enough to get started, but often times IDE features are desired. We have added CLion support to provide a good interface for debugging, navigating the code in general, compiling, and all the other features you'd normally expect to have when using an IDE.

Starting a New Project

Example #1: Add rigid 1.0 board support for ActPack app

Now that we have covered why we decided to use some of the tools we are currently using we'll go into how to create a new project.

For most embedded software products a company will end up with similar but different set of build targets based on the chips, boards, and application usage. A good place to start with a new project is to consider what circuit board will be used. Often times there are different revisions of PCBs used for the same application. In our scenario let's consider we just created the Rigid 1.0 PCB and want to support our ActPack demonstration application. We already had a rigid0.2.cmake file that set some CMake variables and preprocessor definitions. However, we are now using a different microcontroller that has better performance so will need to change all the underlying drivers, and there will be various sections of our application code that needs to use the drivers differently even though they may be performing similar actions.

Because we have a new PCB we will create a rigid1.0.cmake file that will exist in the FlexSEA-Embedded-STM/cmake/board directory. The best place to start will be by duplicating the rigid0.2.cmake file.

# STM32 family
set(CHIP_DIRECTORY "f7")
# STM32 subset
set(STM32_CHIP_TYPE "777xx")
# STM32 part number
set(STM32_CHIP "STM32F777VI")
# board revision
add_definitions(-DHW_VER=10)

There are only 3 types CMake lines in this file

# This is a comment
set(CMAKE_VARIABLE "CMAKE_VARIABLE is being set to what is between these quotes")
add_definition(-DPREPROCESSOR_DEFINITION=I_AM_A_PREPROCESSOR_DEFINITION)

It is important to differentiate between CMake variables and preprocessor definitions. Preprocessor definitions set in CMake are essentially the same as what would be set in the symbols section of eclipse project properties. They are #defines declared prior to compiling anything. CMake variables are only used by CMake files and allow for CMake to have a logical evaluations, paths with variable names, and more.

Notice the line that has set(CHIP_DIRECTORY “f7”). On our rigid0.2 PCB we used a chip from the STM32F4 family. On rigid1.0 we are now using a chip from the STM32F7. These chips have entirely different drivers. Because we set this variable CMake can now automatically pull in the drivers we would like to use with a command like this:

# board settings will give us whether we are an f3, f4, or f7 chip
set(STM32Cube_DIR ${CMAKE_CURRENT_SOURCE_DIR}/stm32cube/${CHIP_DIRECTORY})

For simplicity sake let's assume we are attempting to create the ActPack application as similar as possible for each hardware platform. In FlexSEA-Embedded-STM/cmake/app you will find an ActPack.cmake file with these contents:

message(STATUS "Setting up CMake for an ActPack!")
set(ACTIVE_PROJECT_DIRECTORY "ActPack")
add_definitions(
	-DBOARD_TYPE_FLEXSEA_MANAGE
	-DINCLUDE_UPROJ_ACTPACK
	-DACTIVE_PROJECT=PROJECT_ACTPACK
)
include_directories(flexsea-projects/ActPack/inc)

# pull in necessary STM32 drivers and startup files
find_package(STM32HAL COMPONENTS iwdg usart spi adc gpio tim uart pcd dma rcc flash pwr i2c cortex REQUIRED)
find_package(CMSIS REQUIRED)
find_package(STM32LL COMPONENTS usb REQUIRED)
find_package(USBDevice COMPONENTS CDC REQUIRED)
# manage app source files
file(GLOB PROJECT_SOURCES 
	${CMAKE_CURRENT_SOURCE_DIR}/app/manage/${CHIP_DIRECTORY}/Src/*.c
	${CMAKE_CURRENT_SOURCE_DIR}/app/manage/common/Src/*.c
)
# include manage specific headers
include_directories(
	app/manage/${CHIP_DIRECTORY}/Inc
	app/manage/common/Inc
)
add_definitions(-DBOARD_SUBTYPE_RIGID)

As you can see in this file the CMake variable CHIP_DIRECTORY is used for some app specific files in addition to those driver specific files. This means if the application needs to use different drivers for a new hardware target, or perhaps there's an additional feature added to the new PCB the code to handle those changes can be in an entire separate directory.

Assuming this has already been done it may be possible to build the project now. If you would like to build this with the bash script the manage_builder.sh needs to be edited. The important part would be to look for all references to rigid0.2 and ActPack and to duplicate what is necessary to replicate this for rigid1.0.

If you are using CLion a CMake profile will need to be added. This menu can be accessed via File→Settings→Build,Execution,Deployment→CMake

You should see a list of profiles, or a blank list with +, -, ^, v, and copy options. If there is an existing profile for ActPack-rigid0.2 the easiest solution would be to use the duplicate button. Otherwise use the + button to add a new profile. You should then populate fields of the profile with something similar to what is in the picture below:

The key part are the CMake variables that are passed into CMake and are not found anywhere in the CMakeLists.txt or other CMake files. Here is a screenshot of what those parameters are for an ActPack-rigid2.0 app/board combo:

These parameters are primarily required for the STM32 CMake configuration this project was based off of. The project is located here on github: https://github.com/ObKo/stm32-cmake All of the files from this project that are used are located in the FlexSEA-Embedded-STM/cmake/obko directory.

After CLion is set up now would be a good time to try a build. It is important to be sure that CMake is run prior to compiling so the best way to make this happen for sure is to right click on the project in the left pane and click “Reload CMake Project”.

Now it is time to build, which is typically the hammer icon in CLion but if that is not around you should find another equivalent button or can enter the build menu from the top toolbar. Hopefully it doesn't build because if it does that would mean you're not adding enough new features to integrate!

Example #2: Creating a new CrazyExperiment app for the existing rigid 3.0 board

We have our nice rigid3.0 board that we are using for an Exo application, but what if we want to do something else with it? No need to stress about this situation you can make a new application as well. The best place to start would be to duplicate the ActPack.cmake file in the FlexSEA-Embedded-STM/cmake/app directory and rename it to CrazyExperiment.cmake.

This file will need to be edited to add any app specific features you would like to use. Note that there will be a CMake variable called APP_TYPE whose value will be CrazyExperiment so a convenient way to have a home for files just used by this app is to create a directory called FlexSEA-Embedded-STM/app/CrazyExperiment and put your new code in there. Another option that will likely be what you use to get started will be to leave this CMake file as is for now. What this will do is use all the normal ActPack code. If you are off in your own branch you can then make more minor tweaks and maybe just add some conditional compilation to the ActPack code to incorporate your features. If this will turn into a longer term project and will diverge from the ActPack it would be in everybody's best interest if you create a new home for CrazyExperiment though.

Now that we did some stuff let's make a new CMake profile targeting CrazyExperiment-rigid3.0.

If these instructions made any sense, are still valid, and you followed them correctly you should have (or are close to having) a great new CrazyExperiment app!

manage/build_system.txt · Last modified: 2019/10/07 12:48 by jfduval