LHRS Controls

Table of Contents

1. About the Project
2. Project Status
3. Getting Started
   1. Workspace Setup
   2. Build System
   3. Usage
   4. Running Tests
   5. Debugging
4. Toolset
   1. Renode Simulator
   2. Formatting
   3. Other
5. Release Process
   1. Versioning
6. Contributing
   1. Branch Convention
   2. Review Process
7. Documentation
8. License
9. Authors
10. Acknowledgments

About the Project

This repository contains all code related to Longhorn Racing Solar's Controls System, affiliated with the University of Texas at Austin. The Controls System is responsible for driver interactions, motor control, and lighting systems control. The system is built on custom hardware and an ARM Cortex-M4 Processor (STM32F413).

For more information, see:

• API documentation
• LHR Solar Wiki

Back to top

Project Status

The Controls System is currently on release M2.0 for the 2022-24 build cycle to compete in FSGP 2024. See our Versioning.

LHR Solar uses ClickUp as our project management tool. To access the our ClickUp board, make sure a system lead has added you as a member.

We also use GitHub Projects to track software releases. See our active projects.

Back to top

Getting Started

Please review Setting Up an Embedded Development Environment on our wiki. This should get you up and running with some sort of Linux machine.

Workspace Setup

1. Clone this repository via SSH: git clone --recurse-submodules git@github.com:lhr-solar/Controls.git. Make sure to include the --recurse-submodules flag, or run git submodule update --init --recursive to pull all necessary submodules.

2. In VSCode, remote into your Linux machine if needed. Click File → Open Workspace from File and select the workspace located in .vscode/LHR.code-workspace. The VSCode Workspace has many integrations that developers may find useful while debugging or writing code, including but not limited to integrations with Renode Simulator and the openocd on-chip debugger.

3. Run Embedded-Sharepoint/Scripts/install.sh to selectively install your packages. If you have not done the first step, this will not work, since the Embedded-Sharepoint is one of our submodules. For Controls development, you will need the following packages:

   • ARM Toolchain
   • build-essential
   • gdb-multiarch
   • openocd
   • stlink-tools
   • Renode Simulator
   • Documentation Tools (Sphinx, Doxygen, and Breathe)

The script will prompt for installation of each of these packages.

1. Add source /path/to/Controls/Scripts/load_env_vars.sh to the end of your ~/.bashrc file in order to load the necessary environment variables on shell startup. A typical example: source /${HOME}/LHR/Controls/Scripts/load_env_vars.sh

Build System

We use the GNU Make utility as our build system.

Examples:

make leader
make leader TEST=HelloWorld
make leader TEST=HelloWorld DEBUG=1
make flash
make docs
make clean

Usage

Follow our integration documentation to set up the Controls test rig, power the board with 12V, and use make flash to flash the board with your Objects/controls-leader.elf executable, either built from source using make leader or placed in the Objects folder from your intended release.

Running Tests

WIP: A formal test framework has yet to be defined for the Controls system.

For now, make leader TEST=TestName should build the Controls system excluding Apps/Src/main.c and including Tests/Test_TestName.c.

Debugging

OpenOCD is a debugger program that is open source and compatible with the STM32F413. GDB is a debugger program that can be used to step through a program as it is being run on the board. To use, you need two terminals open, as well as a USB connection to the ST-Link programmer (as if you were going to flash the program to the board).

1. Run openocd in one terminal. Make sure it does not crash and there are no errors. You should see that it tells you what port to connect to (usually :3333).
2. In the other terminal, start gdb with the command gdb-multiarch ./Objects/controls-leader.elf (assuming that you are doing this in the root of the project directory).
3. This will launch GDB and read in all of the symbols from the program that you are running on the board. In order to attach gdb to the board, execute the command target extended-remote :3333, which will connect to the openocd session started earlier.

Note: If you get an error message for permission denied, try giving openocd read/write permissions using chmod: chmod 764 openocd

Back to top

Toolset

The Controls toolset currently includes the Renode Simulator, formatting tools(WIP), and other.

Renode Simulator

The Renode simulator is a software tool developed by Antmicro that the Controls team uses to run unmodified binaries identical to the ones one would normally flash onto target hardware. Put simply, it simulates the hardware and allows us to run and debug tests in preparation for hardware testing. It supports GDB usage and is incredibly useful for ironing out our higher level software bugs.

Check out our Renode folder. See the Renode Documentation for more information on setup. To start Renode, run Scripts/start_renode.sh.

Formatting

WIP: clang-format and clang-tidy are in the process of being integrated into our workflow.

Other

• load_env_vars.sh is our script for loading environment variables.
• bps_sim_can.py is a program to control a CANDapter to simulate BPS CAN messages, as a black box isolated test for the Controls CarCAN system.
• See the Embedded Sharepoint for more of our shared toolset with the rest of the Solar Embedded systems.

Back to top

Release Process

Each release commit will be tagged with the version number (MX.X.X) and live on a production branch (production/MX.X). The controls-leader.elf binary corresponding to the release will also be uploaded to our Releases page on Github.

Versioning

Our versioning system does NOT follow semantic versioning, but instead is based around iterations of the Longhorn Racing Solar Car. Each major version change corresponds to a different iteration of the car for a different year of competition.

Current versions:

• M1 is for the FSGP 2022 Solar Car
• M2 is for the FSGP 2024 Solar Car
• M3 is for the FSGP 2025 Solar Car

Intermediate version names usually refer to a major change that exists for the same vehicle, such as breaking API changes or a rearchitecture.

Back to top

Contributing

Branch Convention

Feature branches (feature/*-###) are for features or bug fixes that are specifically associated with an existing issue ticket.

• Feature branches end with the issue ticket number that the feature is solving.
• Unit testing should be done on these feature branches to ensure that the feature works on an isolated level.

Development branches (dev/*) are for temporary development purposes or hotfixes.

• If a feature, bug, or enhancement starts being worked on without an existing issue ticket, a development branch can be created for it.
• Hotfixes without associated issue tickets can also be created on development branches and merged from a PR without the need for a feature branch, given that the change is small.
• Any other experimentation or temporary needs can live on a development branch.

Integration branches (integration/*-###) are for integration testing.

• This includes integration between Controls and other systems on the vehicle, as well as integration between our internal Applications/Drivers.
• Integration branches end with the issue ticket number for the specific integration being done.

Production branches (production/MX.X) are for specific versions of the codebase. master will always host the latest version.

Review Process

Commit frequently to your branch. A good rule of thumb is to push at natural stopping points + the end of each work session or workday, or more frequently that that if necessary. Create a pull request whenever you are ready to add you working code to the master branch. You must select 2 reviewers for approval. Any trained contributors are allowed to review and approve code. See our PR Template for more review guidelines.

Back to top

Documentation

Controls System

LHRS Controls ReadTheDocs LHRS Controls Wiki

RTOS

uCOS-III Documentation

FreeRTOS Developer Documentation

Hardware

STM32F413 Documentation

Controls Leaderboard Repo

GDB Cheatsheet

Simulator

Renode Simulator Documentation

Back to top

License

Copyright (c) 2024 Longhorn Racing Solar

This project is licensed under the MIT License - see LICENSE file for details.

Back to top

Authors

See the list of contributors who participated in this project.

Back to top