For more, please see CONTRIBUTING.md and the various other Markdown files scattered throughout the monorepo.
This diagram governs the state of the car and represents the logical overview of processes on the car. This diagram must reflect the actual car operations and will help to confirm rules compliance.
If changes are made to the state machine, either in diagram or in implementation, then that PR with the change must update both representations.
The state machine runs on the ECU, but it maps to an enum which is transmitted over CAN. Again, changes to implementation must be reflected in the diagram and vice-versa.
%%{init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#ff6b6b',
'primaryTextColor': '#1f2328',
'lineColor': '#808080',
'edgeLabelBackground': 'rgba(255,255,255,0.8)',
'transitionLabelColor': '#1f2328',
'secondaryColor': '#4ecdc4',
'tertiaryColor': '#ffe66d',
'background': 'transparent',
'mainBkg': 'transparent',
'secondBkg': 'transparent',
'tertiaryBkg': 'transparent'
},
'themeCSS': '.transition { stroke: #808080; } marker path { fill: #808080; stroke: #808080; }'
}}%%
stateDiagram
[*] --> GLV_Off
%% Main horizontal flow (top row)
GLV_Off --> GLV_On : GLVMS On
GLV_On --> GLV_Off : GLVMS Off
GLV_On --> Precharge_Engaged : TS Active
Precharge_Engaged --> Precharge_Complete : Precharge OK
Precharge_Complete --> Drive_Active : Brake & RTD
%% Normal Operation Cycle (horizontal)
Drive_Active --> Precharge_Complete : RTD
%% Discharge state positioned below
GLV_Off
GLV_On
Precharge_Engaged
Precharge_Complete
Drive_Active
Tractive_System_Discharge
%% Downward transitions to discharge
Precharge_Engaged --> Tractive_System_Discharge : TS Active OR Comm Error
Precharge_Complete --> Tractive_System_Discharge : TS Active OR Critical Error
Drive_Active --> Tractive_System_Discharge : TS Active OR Critical Error
%% Return upward from discharge
Tractive_System_Discharge --> GLV_On : TS Voltage < 60V
%% State Descriptions
GLV_Off : GLV Off
GLV_On : GLV On
Precharge_Engaged : Precharge Engaged
Precharge_Complete : Precharge Complete
Drive_Active : Drive Active
Tractive_System_Discharge : Tractive System Discharge
classDef safeState fill:#4ecdc4,stroke:#808080,stroke-width:1px,color:#000
classDef hvState fill:#ff6b6b,stroke:#808080,stroke-width:1px,color:#fff
classDef transitionState fill:#ffe66d,stroke:#808080,stroke-width:1px,color:#000
classDef dischargeState fill:#ff9500,stroke:#808080,stroke-width:1px,color:#000
class GLV_Off,GLV_On safeState
class Drive_Active hvState
class Precharge_Engaged,Precharge_Complete transitionState
class Tractive_System_Discharge dischargeState
- 🟦 Blue: Low voltage
- 🟥 Red: HV charged
- 🟨 Yellow: HV precharge
- 🟧 Orange: HV discharge
Install Git on your specific platform, prefer using your platforms package manager (WinGet, Apt, Homebrew, DNF, Pacman, Pkg, ... etc) over other methods.
Authenticate your Sentinel profile with GitHub through sso.gauchoracing.com/settings/connected-accounts
There are numerous ways to authenticate your Git client with your GitHub credentials, one common option is to install the GitHub CLI and then running gh auth login. You can also use SSH Keys or other options.
Clone the repository by running gh repo clone Gaucho-Racing/Firmware or git clone http://github.com/Gaucho-Racing/Firmware.git or git clone git@github.com:Gaucho-Racing/Firmware.git depending on your chosen authentification strategy.
Download VS Code and install it on your system, you can use other editors or IDEs but under your own support.
Verify the following commands work without errors, if they fail please see the instructions below for your OS
cmake --versionninja --versionarm-none-eabi-gcc --versionopenocd --version
CMake (metabuild system) --> Ninja (build system) --> Arm Toolchain (provides tools to compile & link code)
OpenOCD is an on-chip debugger, which allows us to examine code line-by-line in Debug mode through our debugger GDB
winget install Ninja-build.Ninja Kitware.CMake Arm.GnuArmEmbeddedToolchain Microsoft.VisualStudioCode- OpenOCD -> Download the
.tar.gzfile, extract to directory, add the bin directory to yourPATH - Relaunch your terminal
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"brew install cmake ninja open-ocd gcc-arm-embedded visual-studio-code- Relaunch your terminal
Choose the below command given your specific flavor of Linux or BSD
sudo apt install cmake ninja gcc-arm-none-eabi openocdsudo dnf install cmake ninja openocd(Normally alsoarm-none-eabi-gcc-cs arm-none-eabi-newlibwhich worked on Fedora 42 but is broken on Fedora 43, use Arm's version instead for the moment)sudo pacman -S cmake ninja openocd arm-none-eabi-gccsudo pkg install cmake ninja openocd arm-none-eabi-gcc
If you run into issues verify that binutils and newlib are installed for arm-none-eabi
Note that you can also flash your executable binary files using STM32CubeProgrammer, you still have to compile your program using one of the below methods though.
You can compile using make <Preset> (such as make Debug) which will invoke CMake, or you can compile directly from CMake using cmake --preset <Preset> ; cmake --build --preset <Preset>.
The following presets are currently configured in CMakePresets.json
DebugReleaseMinSizeRelRelWithDebInfoHOOTLTest(see testing)
To compile specifically for one target you can use the below command
cmake --preset <Preset>
cmake --build --preset <Preset> --target <Target>After building, you will need to flash using OpenOCD, there are a variety of options for this, but the easiest will be to openocd -f interface/<interface>.cfg -f target/{series}.cfg -c "program {file}.elf <commands>". Often this will look like the following
openocd -f interface/stlink.cfg -f target/{Series}.cfg -c "program build/<Preset>/{Target}.elf verify reset exit"You can get more advanced and connect to your board using OpenOCD and then launch a debugging session using GDB, this is more complicated and we recommend using VS Code instead, but it is fun to do via the commandline.
Install the recommended extensions in .vscode/extensions.json, if you are using the extension tab (the icon looks like 3 squares with one square at a 45 degree angle) you can also search by @recommended and it will show what extensions you need.
Make sure that you select a configuration preset, you can type in the search bar >CMake: Select Configure Preset, or navigate to the CMake tab (the icon is the CMake triangle icon with a wrench) and ensure that "Configure" is set to one of Debug, Release, MinSizeRel, or RelWithDebInfo. More on the HOOTLTest option in testing.
On the run and debug tab (the icon looks like a triangle with a bug on it) select the drop down to choose the project you wish to run, and then click the green play triangle next to the drop down. If .vscode/launch.json is configured to open a Serial Wire Output (SWO) terminal it will open automatically for you.
At the top of the window you should see a series of options, you can use the different buttons to pause/resume, step into, step out of, step over, and stop debugging a program. You will see the run and debug window also populate with debugging information, and even more when the program is paused.
See the wiki which may be possibly outdated, eventually it should be ported into this
You may also have connection issues with LibUSB, try connecting through a dongle instead of directly to your board.
Rebase when possible for linear histories, please run git config pull.rebase true to set that as the default when you run git pull.
When able, please add VS Code comptatible doc comments! These will help debugging and appear on the tool tip (hover) of any known function.
Eventually, we may autogenerate documentation for the different programs and this will be key... maybe
If you do not want GitHub Action emails please turn off notifications on your side. See something like stackoverflow.com/q/66116203
DO NOT DELETE ANY LICENSE INFORMATION ON ANY COPIED FILE OR LINE OF CODE
See LICENSE.md for more.