Project Structure and Build System - ZadenRB/OpenGCC_Firmware GitHub Wiki
Overview
This page gives a high-level description of how the project is laid out and how functionality is grouped for contributors, as well as an explanation of the build system and configuration.
Project Structure
At the top level, the repository is broken into two main folders - opengcc and controllers. opengcc contains the shared code used for all controllers, while controllers contains controller-specific code and configuration.
The opengcc Folder
In general, changes should only be made to opengcc for the purposes of enabling functionality for all OpenGCC controllers, or to increase flexibility in order to support a new controller. See the header files within opengcc for detailed documentation of each function. Here, a high-level overview of what functionality each file (and header file) implements is given:
main- Bulk of OpenGCC functionality, including analog stick processing, trigger mode application, and button remapping.joybus- Functions for communication with the console. See also thepiofolder for the actual communication state machine.configuration- Helpers and structures for the persistent configuration of the controller, such as button mappings and calibration coefficients.state- Helpers and structures for the runtime state of the controller.calibration- Helpers and structures for handling the analog stick calibration process.curve_fitting- Functions for performing the best-fit calculation used in calibration.
The controllers Folder
controllers/<controller_name> contains the code and build file(s) for a controller. For controllers with multiple revisions, the structure controllers/<controller_name>/<revision_name> is used. Each controller's code must implement setup and reading of buttons, sticks, and triggers. The required functions and documentation can be found in opengcc/controller.hpp. Additionally, config.hpp within each controller's contains definitions of controller-specific configuration that control functionality in the shared OpenGCC code. See Build System for details.
Build System
Each controller (or controller revision) contains a CMakeLists.txt which declares that controller's executable and adds the controller-specific code as sources. It also links any RP2040 libraries required for reading the controller's sensors, and declares the relevant compile definitions for the controller. Each controller should call pico_add_extra_outputs to generate UF2 files for easy flashing. The top-level CMakeLists.txt has an add_subdirectory call for each controller. This combines OpenGCC and controller-specific code and compile definitions for compilation.
Compile definitions
The CMakeLists.txt within each controller's folder contains configuration constants (defined using target_compile_definitions) that are used by the core OpenGCC code. They are used when code is shared between controllers, but might require the use of different pins for I/O, or where multiple standard implementations may be used depending on controller hardware. Joybus makes use of both of these features, where the pins selected for I/O also affect which joybus implementation is used. Below is the current list compile defines.
PICO_FLASH_SIZE_BYTES- The number of bytes of flash on the controllerJOYBUS_IN_PIN- Pin used to read Joybus data being sent from the consoleJOYBUS_OUT_PIN- Pin used to write Joybus data being sent to the console- If
JOYBUS_IN_PIN == JOYBUS_OUT_PIN, thesingle_pin_joybus.pioimplementation is used, otherwisejoybus.piois used
- If
NORMALIZATION_ALGORITHM- Determines what equation is used to normalize sensor output- Valid values are
POLYNOMIAL,LINEAR, andNONE
- Valid values are