diff --git a/development/add-on-basics.mdx b/development/add-on-basics.mdx new file mode 100644 index 0000000..08466fe --- /dev/null +++ b/development/add-on-basics.mdx @@ -0,0 +1,17 @@ +--- +title: Basics +# tags: +# - +pagination_next: null +pagination_prev: null +description: "Documentation on the minimum requirements for a GP2040-CE add-on." +--- + +# Basics + +## General Process + +1. Complete core add-on functionality in the source file with directly hard-coded values based on `#define` macros in the add-on's header files +2. Once basic add-on functionality is confirmed, create necessary enumerations in `config.proto` for add-on options to be saved into protobuf and and then set them in `config_utils.cpp` +3. Replace directly hard-coded values using `#define` macros in source file with the values set in `config_utils.cpp` +4. Create Web Configurator pages, components, and interfaces to manipulate and save user set values to protobuf diff --git a/development/add-on-core-functionality.mdx b/development/add-on-core-functionality.mdx new file mode 100644 index 0000000..e2963e5 --- /dev/null +++ b/development/add-on-core-functionality.mdx @@ -0,0 +1,205 @@ +--- +title: Core Functionality +# tags: +# - +pagination_next: null +pagination_prev: null +description: "Documentation on the minimum requirements for a GP2040-CE add-on to function. Note: This does not include web configuration functionality and saving post-compile options to protobuf." +--- + +# Core Functionality + +### CMAKE + +The first thing to do is to make sure that CMAKE is able to see and add your add-on source files, link any libraries that you create, and include any subfolders for header files you added for add-on functionality. + +```cpp +add_executable(${PROJECT_NAME} +... +src/addons/addon_name.cpp +... +) + +target_link_libraries(${PROJECT_NAME} +... +AdditionalLibraryName +... +) + +target_include_directories(${PROJECT_NAME} PUBLIC +... +headers/folder/subfolder +... +) +``` + +#### Add-On + +Include all necessary files to `/CMakeLists.txt` + +1. Add Add-on executable (i.e. `src/addons/addon_name.cpp`) under `add_executable(${PROJECT_NAME}` + - If any .cpp files in folders outside of `src/addons/` were created for operation of the add-on, they must be included under `add_executable(${PROJECT_NAME}` as well, +2. Add any add-on header files and folders outside of `/headers/addons` (i.e. `/headers/folder/subfolder/addonHeader.h`) to `target_include_directories(${PROJECT_NAME} PUBLIC` + +#### Additional Libraries + +1. Add library to `CMakeLists.txt` +2. Add library to `lib/CMakeLists.txt` +3. Create `lib/AdditionalLibrary/CMakeLists.txt` +4. Add necessary source and header files to `lib/AdditionalLibrary/` + +### Main Program (gp2040.cpp) + +#### Add Add-on Include + +```cpp +#include "addons/addon_name.cpp" +``` + +#### Load Add-on + +```cpp +addons.LoadAddon(new AddonName(), CORE0_Input) +``` + +:::info CORE0_Input vs CORE1_Input + +- `CORE0_Input` is typically input or input-related tasks +- `CORE1_Input` tends to be auxillary output processes (Display, RGB LEDs, etc) and input that include additional USB processing. + +::: + +### Header Files + +You will need to create a header file for add-on in `/headers/addons/ADDON_NAME.h` + +```cpp +#ifndef ADDON_NAME_H +#define ADDON_NAME_H + +#include "gpaddon.h" +#include "GamepadEnums.h" +#include "BoardConfig.h" +#include "enums.pb.h" + +#ifndef ADDON_NAME_ENABLED +#define ADDON_NAME_ENABLED 0 +#endif + +#define ADDON_PIN -1 + +// IO Module Name +#define AddonName "Add-on Name" + +class AddonNameAddon : public GPAddon +{ +public: + virtual void bootProcess() {} + virtual bool available(); + virtual void setup(); + virtual void preprocess(); + virtual void process(); + virtual std::string name() { return AddonName; } + +private: + +}; + +``` + +### Source File + +You will need to create a source file for add-on in `/src/addons/ADDON_NAME..cpp`. This will be the majority of your add-ons functionality. + +```cpp +#include "addons/ADDON_NAME.h" +#include "storagemanager.h" +#include "config.pb.h" + +bool AddonNameAddon::available() +{ + return Storage::getInstance().getAddonOptions().addonNameOptions.enabled; +} + +void AddonNameAddon::setup() +{ +} + +void AddonNameAddon::preprocess() +{ +} + +void AddonNameAddon::process() +{ +} +``` + +#### `available()` + +This function is called once on create to determine whether the addon will be included in the processing loop. You would typically check if the addon's enabled flag is toggled in options and then return that boolean flag. There might be other options you'd want to look at, but that all depends on what's important to know before you turn the add-on on (e.g. checking if GPIO pins are set properly first). + +#### `setup()` + +This function is called once if `available()` returns true to set up any objects/variables that are needed prior to the main loop. Here you will want to prepare any GPIO pin assignments or create objects that the processing loop needs to function when `preprocess()` and `process()` are called. + +#### `preprocess()` + +This function is called on the `GP2040::run()` loop prior to processing the gamepad state. This is where you will want to change and modify the gamepad state according to the intended function of your add-on. + +#### `process()` + +This function is called on the `GP2040::run()` or `GP2040Aux::run()` loop after processing gamepad state. This is where you will want to change and modify the gamepad state according to the intended function of your add-on. + +### Protobuf + +:::warning + +Unless absolutely necessary, do not rename or reorder the enumerations in `config.proto` and `enums.proto`. Doing so will break compatibility with previous versions of the firmware. Simply append any new enumerations if more are necessary. + +::: + +#### `config.proto` + +Once you have the add-on working using the directly hardcoded `#define` macros in `addonName.h`, you will want to add the options to `/proto/config.proto` so that those options will be properly allocated memory space in protobuf. By doing so, you can later read and write values to be saved to protobuf using the Web Configurator and web interface. + +In addition to options specific to the add-on you are developing, you will need to add an enum for the new add-on to the `AddonOptions`. + +```cpp +message AddOnNameOptions { + optional bool enabled = 1; + optional uint32 addonSetting = 2; +} + +message AddonOptions { + ... + optional AddonOptions addonNameOptions = XX; +} +``` + +#### `enums.proto` + +When a variable can take certain values, it is useful to use enumerations. It encapsulates all possible values from a specific group. In order to use enumerations, it will be necessary to add these enumerations to `proto/enums.proto` so that they can be used in your add-on as well as potentially in other parts of the firmware. + +```cpp +enum AddonEnum +{ + options (nanopb_enumopt).long_names = false; + + ENUM_OPTION_1 = 0; + ENUM_OPTION_2 = 1; + ... +} +``` + +#### `configs_utils.cpp` + +- Add set properties to `src/configs_utils.cpp` + - Remember to add all properties to `config.proto` + +```cpp +#include "addons/addon_name.h" + +// addonOptions.addonNameOptions +INIT_UNSET_PROPERTY(config.addonOptions.addonNameOptions, enabled, ADDON_NAME_ENABLED); + +``` \ No newline at end of file diff --git a/development/firmware-development.mdx b/development/board-configuration.mdx similarity index 67% rename from development/firmware-development.mdx rename to development/board-configuration.mdx index f633f3f..c146bbe 100644 --- a/development/firmware-development.mdx +++ b/development/board-configuration.mdx @@ -1,267 +1,16 @@ --- -title: Firmware Development +title: Board Configuration # tags: # - pagination_next: null pagination_prev: null -description: "Documentation on building and developing for GP2040-CE Firmware" +description: "Documentation on creating a board configuration for GP2040-CE Firmware" --- import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; -# Firmware Development - -GP2040-CE is written in C++ and set up as a standard Pico SDK project. - -See [Getting Started with the Raspberry Pi Pico](https://rptl.io/pico-get-started). - -## Environment Setup - -Most of this will be parroting the above linked PDF from the Raspberry Pi Foundation. - - - - -1. Download and install [CMake](https://github.com/Kitware/CMake/releases/download/v3.27.4/cmake-3.27.4-windows-x86_64.msi). -2. Install [NodeJS](https://nodejs.org/en/download) -3. Install [NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) -4. Download and install [pico-setup-windows-x64-standalone](https://github.com/raspberrypi/pico-setup-windows/releases/). -5. Download and install VSCode. -6. Download and install [Windows Terminal](https://github.com/microsoft/terminal/releases/tag/v1.17.11461.0). -7. Open Windows Terminal. -8. Download the GP2040-CE-main repository by running the following commands in the Windows Terminal. This will download the folder to `C:\Users\user\GP2040-CE`. - - ```console - git clone https://github.com/OpenStickCommunity/GP2040-CE.git - cd GP2040-CE - git submodule update --init - ``` - -After installing the Raspberry Pi Pico SDK, you should now have a shortcut to "Pico-Visual Studio Code" (search for it using Windows Search). - -8. Open "Pico-Visual Studio Code" via Windows search. This is a shortcut with pre-configured environment variables (this will be explained later). -9. Navigate to the Extensions window by pressing `Ctrl+Shift+X`. -10. Install "CMake Tools" by Microsoft. -11. Open the GP2040-CE folder you downloaded earlier via "File > Open Folder." - - - - -1. Install the latest[Arm GNU Toolchain](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads) -2. Install latest version of [CMake](https://cmake.org/download/) -3. Install [Visual Studio Build tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022), or the full [Visual Studio Community Edition IDE](https://visualstudio.microsoft.com/downloads/#visual-studio-community-2022) - - Make sure to select the Desktop development with C++ workload - - Select the latest Windows 10 or Windows 11 SDK from the Individual Components -4. Install [Python 3.10](https://www.python.org/downloads/windows/) - - At the end of the installation, there is an option to disable max file path length. You want to select this. -5. Install [Visual Studio Code](https://code.visualstudio.com/) - Optional -6. Install git - - Set default editor to anything other than VIM, such as Visual Studio Code -7. Install [NodeJS](https://nodejs.org/en/download) and NPM -8. Clone the Pico SDK to your local computer - - ```console - git clone https://github.com/raspberrypi/pico-sdk.git - cd pico-sdk - git submodule update --init - cd .. - ``` - -9. From a command-prompt, Clone GP2040-CE to your local computer - - ```console - git clone https://github.com/OpenStickCommunity/GP2040-CE.git - cd GP2040-CE - ``` - - - - -#### Ubuntu - -This setup assumes an understanding of Linux terminal usage. - -1. Get the SDK - - ```bash - cd ~/ - mkdir pico - cd pico - git clone https://github.com/raspberrypi/pico-sdk.git --branch master - cd pico-sdk - git submodule update --init - cd .. - ``` - -2. Install the toolchain - - ```bash - sudo apt update - sudo apt install cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential - ``` - - - May additionally need to install `libstdc++-arm-none-eabi-newlib` - -3. Install NodeJS and NPM - - ```bash - curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - &&\ - sudo apt-get install -y nodejs - ``` - -4. Get GP2040-CE - - ```bash - git clone https://github.com/OpenStickCommunity/GP2040-CE.git - cd GP2040-CE - git submodule update --init - ``` - -#### Raspberry Pi - -This setup script requires approximately 2.5GB of disk space on your SD card. - -1. Download the setup script - - ```bash - wget https://raw.githubusercontent.com/raspberrypi/pico-setup/master/pico_setup.sh - ``` - -2. Make script executable and Run it. - - ```bash - chmod +x pico_setup.sh - ``` - -3. Install NodeJS and NPM - - ```bash - curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - &&\ - sudo apt-get install -y nodejs - ``` - -4. Reboot your Pi - - ```bash - sudo reboot - ``` - -5. Get GP2040-CE - - ```bash - git clone https://github.com/OpenStickCommunity/GP2040-CE.git - cd GP2040-CE - git submodule update --init - ``` - - - - -## Building - -### Environment Variables - -A number of new environment variables have been setup to control parts of the build flow. - -| Name | Default | Description | -| ------------------ | ------- | ------------------------------------------------------------------------------------------------------- | -| GP2040_BOARDCONFIG | Pico | The boards.h config file to use for the build. | -| SKIP_WEBBUILD | FALSE | Determines whether the web configurator is built during the cmake configuration step. | -| SKIP_SUBMODULES | FALSE | Determines whether the submodule init command is run automatically during the cmake configuration step. | - -#### SDK Variables - -There are a few SDK variables we take advantage of for our builds. - -| Name | Default | Description | -| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| PICO_BOARD | pico | This is the embedded board that the RP2040 chip is part of. By default, it assumes the Pico. This variable would match the `` file in the board's configs folder. | - - - - -After installing the Raspberry Pi Pico SDK, you should now have a shortcut to "Pico-Visual Studio Code" (search for it using Windows Search). This shortcut should already have everything configured, **allowing you to skip to step 7**. If you're experiencing compilation issues, consider following the manual steps outlined here. - -Ensure the `PICO_SDK_PATH` environment variable is set: - -1. Search for "Edit environment variables for your account" in Windows. -2. Under "User Variables," click "New...". -3. In the dialog that appears, enter `PICO_SDK_PATH` for the Variable Name. -4. Click "Browse Directory" and navigate to `C:\Program Files\Raspberry Pi\Pico SDK v1.5.1\pico-sdk` for the Variable Value. -5. Create another new variable. -6. Enter `GP2040_BOARDCONFIG` for the Variable Name. -7. Enter `Pico` (or the name of your edited config folder) for the Variable Value. - -You can also set the variable within VSCode: - -1. Press `Ctrl + ,` to open the settings. -2. Use the search bar to find "CMake." -3. Scroll until you see "CMake: Configure Environment." -4. Click "Add Item." -5. Key: `GP2040_BOARDCONFIG` -6. Value: `Pico` (or your working folder name). - -When prompted, choose `GCC 10.3.1 ARM NONE EABI` for "Select a kit for GP2040-CE" - -From inside VSCode: - -1. Click the CMake icon on the left sidebar of VSCode. -2. You'll see three icons at the top-right corner of the CMake project outline. Click the "Configure All Projects" icon (looks like a page with an arrow). -3. Wait for the configuration process to complete. If progress isn't visible, open a new terminal in VSCode by clicking on the "Terminal" menu, then "New Terminal". A new terminal window will open at the bottom, navigate the "Output" tab. -4. Click "Build All Projects" in the CMake project outline. -5. The files should be in a new folder named "build" inside the GP2040-CE folder - - - - -Start in the GP2040-CE folder. **From a Developer Powershell or Developer Command Command Prompt**: - -:::note - -A new Powershell or Command Prompt session will be required after setting an environment variable. - -::: - -1. Ensure you have the `PICO_SDK_PATH` environment variable set to the path to your pico-sdk folder. -2. (optional) Set the `GP2040_BOARDCONFIG` environment variable to the folder name for your board configuration. - - - Default value is `Pico` - -3. Create a build directory, configure the build, and execute the build. - - ```console - mkdir build - cd build - cmake -G "NMake Makefiles" .. - nmake - ``` - -4. Your UF2 file should be in the build directory. - - - - -Start in the GP2040-CE folder - -1. Ensure you have the `PICO_SDK_PATH` environment variable set to the path to your pico-sdk folder. -2. (optional) Set the `GP2040_BOARDCONFIG` environment variable to the folder name for your board configuration. - - Default value is `Pico` -3. Create a build directory, configure the build, and execute the build. - - ```bash - mkdir build - cd build - cmake .. - make - ``` - -4. Your UF2 file should be in the build directory. - - - - -## Configuration +# Configuration :::note @@ -271,18 +20,18 @@ We're looking to move away from compile time configuration, in favor of runtime There are two simple options for building GP2040-CE for your board. You can either edit an existing board definition, or create your own. Several example configurations are located in the repository **[configs](https://github.com/OpenStickCommunity/GP2040-CE/tree/main/configs)** folder. This document will outline setting up a new build configuration. -### Board Configuration Folder +## Board Configuration Folder Each subfolder in [`configs`](https://github.com/OpenStickCommunity/GP2040-CE/tree/main/configs) contains a separate board configuration, which consists of the following: -| Name | Required? | Description | -| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `BoardConfig.h` | Yes | The configuration file used when building GP2040-CE for a specific controller/board. Contains initial pin mappings, LED configuration, etc. | -| `README.mdx` | No | Provides information related to this board configuration. Not required for the build process, but suggested for pull requests of new board configurations. | -| `assets/` | No | Folder for containing assets included in the `README.mdx`. Not required for the build process. | -| '\' | No | Board definition file, named after the board itself, used by the Pico SDK for configuring board specific SDK features. [Pico Example](https://github.com/raspberrypi/pico-sdk/blob/master/src/boards/include/boards/pico.h) | +| Name | Required? | Description | +| --------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `BoardConfig.h` | Yes | The configuration file used when building GP2040-CE for a specific controller/board. Contains initial pin mappings, LED configuration, etc. | +| `README.mdx` | No | Provides information related to this board configuration. Not required for the build process, but suggested for pull requests of new board configurations. | +| `assets/` | No | Folder for containing assets included in the `README.mdx`. Not required for the build process. | +| `` | No | Board definition file, named after the board itself, used by the Pico SDK for configuring board specific SDK features. [Pico Example](https://github.com/raspberrypi/pico-sdk/blob/master/src/boards/include/boards/pico.h) | -### Board Configuration (`BoardConfig.h`) +## Board Configuration (`BoardConfig.h`) The following board options are available in the `BoardConfig.h` file: @@ -325,7 +74,7 @@ Create `configs/NewBoard/BoardConfig.h` and add your pin configuration and optio #define BUTTON_LAYOUT BUTTON_LAYOUT_ARCADE ``` -#### RGB LEDs +### RGB LEDs GP2040-CE supports per-button WS2812 and similar RGB LEDs. @@ -378,7 +127,7 @@ An example RGB LED setup in the `BoardConfig.h` file: #define LEDS_BUTTON_L2 11 ``` -#### Player LEDs +### Player LEDs GP2040-CE supports PWM and RGB player LEDs (PLEDs) and can be configured in the `BoardConfig.h` file. @@ -412,7 +161,7 @@ An example PLED setup in the `BoardConfig.h` file: #define PLED4_PIN 15 ``` -#### I2C Displays +### I2C Displays GP2040-CE supports 128x64 monochrome displays that run on the SSD1306, SH1106 or SH1107 drivers. The following options are available for displays: @@ -439,9 +188,9 @@ An example I2C display setup in the `BoardConfig.h` file: #define I2C_SPEED 800000 ``` -### I2C Display Custom Button Layouts +#### I2C Display Custom Button Layouts -As of v0.7.9 you have the ability to create a custom `left` and `right` display layout through the boardconfig.h as `DEFAULT_BOARD_LAYOUT_A` and `DEFAULT_BOARD_LAYOUT_B`. +As of v0.7.9 you have the ability to create a custom `left` and `right` display layout through the boardconfig.h as `DEFAULT_BOARD_LAYOUT_A` and `DEFAULT_BOARD_LAYOUT_B`. You can find an example of how to set this up in the [Zero Rhythm BoardConfig.h](https://github.com/OpenStickCommunity/GP2040-CE/blob/main/configs/ZeroRhythm/BoardConfig.h#L90) file. diff --git a/development/build-environment.mdx b/development/build-environment.mdx new file mode 100644 index 0000000..c4f8a3c --- /dev/null +++ b/development/build-environment.mdx @@ -0,0 +1,262 @@ +--- +title: Set Up Build Environment +# tags: +# - +pagination_next: null +pagination_prev: null +description: "Documentation on setting up the build environment for GP2040-CE firmware development" +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Firmware Development + +GP2040-CE is written in C++ and set up as a standard Pico SDK project. + +See [Getting Started with the Raspberry Pi Pico](https://rptl.io/pico-get-started). + +## Environment Setup + +Most of this will be parroting the above linked PDF from the Raspberry Pi Foundation. + + + + +1. Download and install [CMake](https://github.com/Kitware/CMake/releases/download/v3.27.4/cmake-3.27.4-windows-x86_64.msi). +2. Install [NodeJS](https://nodejs.org/en/download) +3. Install [NPM](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) +4. Download and install [pico-setup-windows-x64-standalone](https://github.com/raspberrypi/pico-setup-windows/releases/). +5. Download and install VSCode. +6. Download and install [Windows Terminal](https://github.com/microsoft/terminal/releases/tag/v1.17.11461.0). +7. Open Windows Terminal. +8. Download the GP2040-CE-main repository by running the following commands in the Windows Terminal. This will download the folder to `C:\Users\user\GP2040-CE`. + + ```console + git clone https://github.com/OpenStickCommunity/GP2040-CE.git + cd GP2040-CE + git submodule update --init + ``` + +After installing the Raspberry Pi Pico SDK, you should now have a shortcut to "Pico-Visual Studio Code" (search for it using Windows Search). + +8. Open "Pico-Visual Studio Code" via Windows search. This is a shortcut with pre-configured environment variables (this will be explained later). +9. Navigate to the Extensions window by pressing `Ctrl+Shift+X`. +10. Install "CMake Tools" by Microsoft. +11. Open the GP2040-CE folder you downloaded earlier via "File > Open Folder." + + + + +1. Install the latest[Arm GNU Toolchain](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads) +2. Install latest version of [CMake](https://cmake.org/download/) +3. Install [Visual Studio Build tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022), or the full [Visual Studio Community Edition IDE](https://visualstudio.microsoft.com/downloads/#visual-studio-community-2022) + - Make sure to select the Desktop development with C++ workload + - Select the latest Windows 10 or Windows 11 SDK from the Individual Components +4. Install [Python 3.10](https://www.python.org/downloads/windows/) + - At the end of the installation, there is an option to disable max file path length. You want to select this. +5. Install [Visual Studio Code](https://code.visualstudio.com/) - Optional +6. Install git + - Set default editor to anything other than VIM, such as Visual Studio Code +7. Install [NodeJS](https://nodejs.org/en/download) and NPM +8. Clone the Pico SDK to your local computer + + ```console + git clone https://github.com/raspberrypi/pico-sdk.git + cd pico-sdk + git submodule update --init + cd .. + ``` + +9. From a command-prompt, Clone GP2040-CE to your local computer + + ```console + git clone https://github.com/OpenStickCommunity/GP2040-CE.git + cd GP2040-CE + ``` + + + + +#### Ubuntu + +This setup assumes an understanding of Linux terminal usage. + +1. Get the SDK + + ```bash + cd ~/ + mkdir pico + cd pico + git clone https://github.com/raspberrypi/pico-sdk.git --branch master + cd pico-sdk + git submodule update --init + cd .. + ``` + +2. Install the toolchain + + ```bash + sudo apt update + sudo apt install cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential + ``` + + - May additionally need to install `libstdc++-arm-none-eabi-newlib` + +3. Install NodeJS and NPM + + ```bash + curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - &&\ + sudo apt-get install -y nodejs + ``` + +4. Get GP2040-CE + + ```bash + git clone https://github.com/OpenStickCommunity/GP2040-CE.git + cd GP2040-CE + git submodule update --init + ``` + +#### Raspberry Pi + +This setup script requires approximately 2.5GB of disk space on your SD card. + +1. Download the setup script + + ```bash + wget https://raw.githubusercontent.com/raspberrypi/pico-setup/master/pico_setup.sh + ``` + +2. Make script executable and Run it. + + ```bash + chmod +x pico_setup.sh + ``` + +3. Install NodeJS and NPM + + ```bash + curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - &&\ + sudo apt-get install -y nodejs + ``` + +4. Reboot your Pi + + ```bash + sudo reboot + ``` + +5. Get GP2040-CE + + ```bash + git clone https://github.com/OpenStickCommunity/GP2040-CE.git + cd GP2040-CE + git submodule update --init + ``` + + + + +## Building + +### Environment Variables + +A number of new environment variables have been setup to control parts of the build flow. + +| Name | Default | Description | +| ------------------ | ------- | ------------------------------------------------------------------------------------------------------- | +| GP2040_BOARDCONFIG | Pico | The boards.h config file to use for the build. | +| SKIP_WEBBUILD | FALSE | Determines whether the web configurator is built during the cmake configuration step. | +| SKIP_SUBMODULES | FALSE | Determines whether the submodule init command is run automatically during the cmake configuration step. | + +#### SDK Variables + +There are a few SDK variables we take advantage of for our builds. + +| Name | Default | Description | +| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| PICO_BOARD | pico | This is the embedded board that the RP2040 chip is part of. By default, it assumes the Pico. This variable would match the `` file in the board's configs folder. | + + + + +After installing the Raspberry Pi Pico SDK, you should now have a shortcut to "Pico-Visual Studio Code" (search for it using Windows Search). This shortcut should already have everything configured, **allowing you to skip to step 7**. If you're experiencing compilation issues, consider following the manual steps outlined here. + +Ensure the `PICO_SDK_PATH` environment variable is set: + +1. Search for "Edit environment variables for your account" in Windows. +2. Under "User Variables," click "New...". +3. In the dialog that appears, enter `PICO_SDK_PATH` for the Variable Name. +4. Click "Browse Directory" and navigate to `C:\Program Files\Raspberry Pi\Pico SDK v1.5.1\pico-sdk` for the Variable Value. +5. Create another new variable. +6. Enter `GP2040_BOARDCONFIG` for the Variable Name. +7. Enter `Pico` (or the name of your edited config folder) for the Variable Value. + +You can also set the variable within VSCode: + +1. Press `Ctrl + ,` to open the settings. +2. Use the search bar to find "CMake." +3. Scroll until you see "CMake: Configure Environment." +4. Click "Add Item." +5. Key: `GP2040_BOARDCONFIG` +6. Value: `Pico` (or your working folder name). + +When prompted, choose `GCC 10.3.1 ARM NONE EABI` for "Select a kit for GP2040-CE" + +From inside VSCode: + +1. Click the CMake icon on the left sidebar of VSCode. +2. You'll see three icons at the top-right corner of the CMake project outline. Click the "Configure All Projects" icon (looks like a page with an arrow). +3. Wait for the configuration process to complete. If progress isn't visible, open a new terminal in VSCode by clicking on the "Terminal" menu, then "New Terminal". A new terminal window will open at the bottom, navigate the "Output" tab. +4. Click "Build All Projects" in the CMake project outline. +5. The files should be in a new folder named "build" inside the GP2040-CE folder + + + + +Start in the GP2040-CE folder. **From a Developer Powershell or Developer Command Command Prompt**: + +:::note + +A new Powershell or Command Prompt session will be required after setting an environment variable. + +::: + +1. Ensure you have the `PICO_SDK_PATH` environment variable set to the path to your pico-sdk folder. +2. (optional) Set the `GP2040_BOARDCONFIG` environment variable to the folder name for your board configuration. + + - Default value is `Pico` + +3. Create a build directory, configure the build, and execute the build. + + ```console + mkdir build + cd build + cmake -G "NMake Makefiles" .. + nmake + ``` + +4. Your UF2 file should be in the build directory. + + + + +Start in the GP2040-CE folder + +1. Ensure you have the `PICO_SDK_PATH` environment variable set to the path to your pico-sdk folder. +2. (optional) Set the `GP2040_BOARDCONFIG` environment variable to the folder name for your board configuration. + - Default value is `Pico` +3. Create a build directory, configure the build, and execute the build. + + ```bash + mkdir build + cd build + cmake .. + make + ``` + +4. Your UF2 file should be in the build directory. + + + \ No newline at end of file diff --git a/development/compile-firmware.mdx b/development/compile-firmware.mdx new file mode 100644 index 0000000..9ec4b97 --- /dev/null +++ b/development/compile-firmware.mdx @@ -0,0 +1,114 @@ +--- +title: Compile Firmware +# tags: +# - +pagination_next: null +pagination_prev: null +description: "Documentation on creating a board configuration for GP2040-CE Firmware" +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Building + +## Environment Variables + +A number of new environment variables have been setup to control parts of the build flow. + +| Name | Default | Description | +| ------------------ | ------- | ------------------------------------------------------------------------------------------------------- | +| GP2040_BOARDCONFIG | Pico | The boards.h config file to use for the build. | +| SKIP_WEBBUILD | FALSE | Determines whether the web configurator is built during the cmake configuration step. | +| SKIP_SUBMODULES | FALSE | Determines whether the submodule init command is run automatically during the cmake configuration step. | + +### SDK Variables + +There are a few SDK variables we take advantage of for our builds. + +| Name | Default | Description | +| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| PICO_BOARD | pico | This is the embedded board that the RP2040 chip is part of. By default, it assumes the Pico. This variable would match the `` file in the board's configs folder. | + + + + +After installing the Raspberry Pi Pico SDK, you should now have a shortcut to "Pico-Visual Studio Code" (search for it using Windows Search). This shortcut should already have everything configured, **allowing you to skip to step 7**. If you're experiencing compilation issues, consider following the manual steps outlined here. + +Ensure the `PICO_SDK_PATH` environment variable is set: + +1. Search for "Edit environment variables for your account" in Windows. +2. Under "User Variables," click "New...". +3. In the dialog that appears, enter `PICO_SDK_PATH` for the Variable Name. +4. Click "Browse Directory" and navigate to `C:\Program Files\Raspberry Pi\Pico SDK v1.5.1\pico-sdk` for the Variable Value. +5. Create another new variable. +6. Enter `GP2040_BOARDCONFIG` for the Variable Name. +7. Enter `Pico` (or the name of your edited config folder) for the Variable Value. + +You can also set the variable within VSCode: + +1. Press `Ctrl + ,` to open the settings. +2. Use the search bar to find "CMake." +3. Scroll until you see "CMake: Configure Environment." +4. Click "Add Item." +5. Key: `GP2040_BOARDCONFIG` +6. Value: `Pico` (or your working folder name). + +When prompted, choose `GCC 10.3.1 ARM NONE EABI` for "Select a kit for GP2040-CE" + +From inside VSCode: + +1. Click the CMake icon on the left sidebar of VSCode. +2. You'll see three icons at the top-right corner of the CMake project outline. Click the "Configure All Projects" icon (looks like a page with an arrow). +3. Wait for the configuration process to complete. If progress isn't visible, open a new terminal in VSCode by clicking on the "Terminal" menu, then "New Terminal". A new terminal window will open at the bottom, navigate the "Output" tab. +4. Click "Build All Projects" in the CMake project outline. +5. The files should be in a new folder named "build" inside the GP2040-CE folder + + + + +Start in the GP2040-CE folder. **From a Developer Powershell or Developer Command Command Prompt**: + +:::note + +A new Powershell or Command Prompt session will be required after setting an environment variable. + +::: + +1. Ensure you have the `PICO_SDK_PATH` environment variable set to the path to your pico-sdk folder. +2. (optional) Set the `GP2040_BOARDCONFIG` environment variable to the folder name for your board configuration. + + - Default value is `Pico` + +3. Create a build directory, configure the build, and execute the build. + + ```console + mkdir build + cd build + cmake -G "NMake Makefiles" .. + nmake + ``` + +4. Your UF2 file should be in the build directory. + + + + +Start in the GP2040-CE folder + +1. Ensure you have the `PICO_SDK_PATH` environment variable set to the path to your pico-sdk folder. +2. (optional) Set the `GP2040_BOARDCONFIG` environment variable to the folder name for your board configuration. + - Default value is `Pico` +3. Create a build directory, configure the build, and execute the build. + + ```bash + mkdir build + cd build + cmake .. + make + ``` + +4. Your UF2 file should be in the build directory. + + + \ No newline at end of file diff --git a/docs/assets/images/gpc-settings-ps4.png b/docs/assets/images/gpc-settings-ps4.png index 29220e8..11d346f 100644 Binary files a/docs/assets/images/gpc-settings-ps4.png and b/docs/assets/images/gpc-settings-ps4.png differ diff --git a/docs/assets/images/gpc-settings-ps5.png b/docs/assets/images/gpc-settings-ps5.png index 6d23325..de2183d 100644 Binary files a/docs/assets/images/gpc-settings-ps5.png and b/docs/assets/images/gpc-settings-ps5.png differ diff --git a/docs/faq/faq-console-compatibility.mdx b/docs/faq/faq-console-compatibility.mdx index 7101027..2ea9ef1 100644 --- a/docs/faq/faq-console-compatibility.mdx +++ b/docs/faq/faq-console-compatibility.mdx @@ -197,7 +197,49 @@ For the MagicBoots Adapter and N5 listed above, there is an indicator light on t Playstation consoles repeatedly send authorization requests every 30 seconds or so. If the request fails (i.e. there is no passthrough authentication device plugged in), in about 8 minutes, the controller will stop responding. Once this happens, the only option is to either reset the controller or unplug and then plug the controller back into the console. -## Xbox +## Xbox 360 + +### How do I get my GP2040-CE unit to work on an Xbox 360? + +For Xbox 360 compatibility, you will need to use the [XInput](../web-configurator/menu-pages/01-settings.mdx). XInput mode will change to Xbox 360 automatically when a appropiate Xbox 360 dongle is connected. + +### What is the Xbox 360 Input Mode? + +:::caution Additional Hardware Required + +- [USB Host Port](../controller-build/usb-host.mdx) +- Xbox 360 Authentication Device + +::: + +Xbox 360 Mode through XInput grants GP2040-CE compatibility with the Xbox 360 by using a dongle to answer authentication + +For more information, refer to [Xbox 360 Input Mode](../web-configurator/menu-pages/01-settings.mdx) in the `Web Configurator - Add-ons` section of the documentation. + +### What dongle do I use for Xbox 360 Input Mode? + +Currently there is only one dongle that will work for Xbox 360 input mode: +- [MagicBoots FPS Adapter Joystick Converter for Xbox 360](https://www.mayflash.com/product/MAG360.html) + +Because your experience and purchased products may vary, GP2040-CE will not provide additional specific recommendations beyond these known working devices. + +:::caution Xbox 360 Controllers + +Xbox 360 Wireless Controllers, Xbox 360 Wired Controllers, and other licensed Xbox 360 controllers will not work with this add-on. + +::: + +### How do I know the Xbox 360 Input Mode add-on is working? + +Because of the numerous devices to be used for passthrough authentication, there is not just one way to verify that the input mode is working without plugging the controller into a console and attempting to use it. + +For the MagicBoots Adapter listed above, there is an indicator light on the dongle that should flash on boot and then become solid after a moment. If the indicator light is on and solid, your controllers _should_ be compatible and you may use your controller as intended. + +### Can I remove the Xbox 360 authentication device once I have plugged in my controller? + +Xbox 360 consoles only perform the authentication process once when the controller is plugged into the console. Once this occurs, the passthrough authentication device can be removed. However, it is still recommended to keep the device plugged in. + +## Xbox One, Xbox Series S, and Xbox Series X ### How do I get my GP2040-CE unit to work on a Xbox One, Xbox Series S, or Xbox Series X? @@ -242,3 +284,25 @@ For the Magic-X Adapter listed above, there is an indicator light on the dongle ### Can I remove the Xbox One authentication device once I have plugged in my controller? Xbox One, Xbox Series S, and Xbox Series X consoles only perform the authentication process once when the controller is plugged into the console. Once this occurs, the passthrough authentication device can be removed. However, it is still recommended to keep the device plugged in. + +## Experimental USB Hub Support + +As of v0.7.10 GP2040-CE now includes experimental support for USB hubs which will allow you to connect multiple dongles along with a keyboard at the same time. Please note the following cautions. + +:::caution Not all USB hubs are supported + +Please note that USB hub support is still very experimental and as such we cannot provide a list of known good USB hubs. + +::: + +:::caution Be mindful of power draw + +A USB hub and multiple connected USB dongles may add considerable load to your setups overall power draw. + +::: + +:::caution USB Hub Support and the RP2040 Advanced Breakout Board + +Through testing we have found that on the RP2040 Advanced Breakout Board it is recommended to disable RGB LEDs via web-config if you are planning to use a USB hub. RGB LEDs can be disabled by changing the GPIO pin to `-1` and saving. + +::: \ No newline at end of file diff --git a/docs/hotkeys.mdx b/docs/hotkeys.mdx index 2fd5a6d..dbd7d7d 100644 --- a/docs/hotkeys.mdx +++ b/docs/hotkeys.mdx @@ -149,6 +149,10 @@ It is recommended that multiple `Load Profile` hotkeys be configured so as to pr ::: +## Next Profile + +This hotkey cycles through pin mapping profiles set in [Profile Settings](./web-configurator/menu-pages/02-pin-mapping.mdx#profiles) in the Web Configurator. For example, if Profile 1 is selected, pressing the hotkey will cycle it to Profile 2, then Profile 3, Profile 4, and back to Profile 1. + ## L3 Button This hotkey emulates a press of the button as not all controllers may have this button natively on the controller. diff --git a/docs/web-configurator/menu-pages/01-settings.mdx b/docs/web-configurator/menu-pages/01-settings.mdx index 8c8d819..24cef70 100644 --- a/docs/web-configurator/menu-pages/01-settings.mdx +++ b/docs/web-configurator/menu-pages/01-settings.mdx @@ -29,6 +29,12 @@ Here you can remap the GP2040-CE buttons to different keyboard keycodes that wil ![GP2040-CE Configurator - Additional PS4 Settings](../../assets/images/gpc-settings-ps4.png) - `Switch Touchpad and Share` - Share will now be mapped to A2 rather than S1, Touchpad will be now mapped to S1 rather than A2 +- `Identification Mode` is an option to allow for situations where a true DualShock 4 would be required. This doesn't make it a real DS4 for technical reasons, but it does make the firmware behave more like one. + - `Console` - This is what everyone is used to. It works on PS4/PS5 with the same restrictions you would expect for authorization. + - `Remote/Emulation` - This is used in situations where the only controller you can use is a DualShock 4, but doesn't necessarily require any sort of passthrough authorization. PS Remote Play only allows "authentic" DualShock 4/DualSense controllers, but does not (currently) seem to require auth. Open PS2 Loader (OPL) versions with the PADEMU USB controller driver will only look for "authentic" DualShock 3/4 controllers, but do not require auth to function. +When playing directly on a PS4/PS5 console, using Console mode will allow the controller to behave as expected. This is the default. When using Remote/Emulation directly on a console, the controller will not be detected for technical reasons. +When playing via PS Remote Play specifically, since Console mode does not appear as an authentic DualShock 4 controller, it will not be detected. Using an alternate Remote Play client, such as Chiaki, does not have this limitation. +Unless something changes specifically in PS Remote Play, authorization is not required in Remote/Emulation mode. - `Authentication Settings` - `Uploaded Key File` - Upload key files obtained from a Dualshock 4 to authenticate and bypass the PS4's 8-minute time out - `Host USB` - Use a dongle, converter, or licensed PS4 controller to authenticate your GP2040-CE device @@ -68,6 +74,12 @@ In order to use this setting, a USB Peripheral must be configured in [Web Config ![GP2040-CE Configurator - Additional PS5 Settings](../../assets/images/gpc-settings-ps5.png) - `Switch Touchpad and Share` - Share will now be mapped to A2 rather than S1, Touchpad will be now mapped to S1 rather than A2 +- `Identification Mode` is an option to allow for situations where a true DualShock 4 would be required. This doesn't make it a real DS4 for technical reasons, but it does make the firmware behave more like one. + - `Console` - This is what everyone is used to. It works on PS4/PS5 with the same restrictions you would expect for authorization. + - `Remote/Emulation` - This is used in situations where the only controller you can use is a DualShock 4, but doesn't necessarily require any sort of passthrough authorization. PS Remote Play only allows "authentic" DualShock 4/DualSense controllers, but does not (currently) seem to require auth. Open PS2 Loader (OPL) versions with the PADEMU USB controller driver will only look for "authentic" DualShock 3/4 controllers, but do not require auth to function. +When playing directly on a PS4/PS5 console, using Console mode will allow the controller to behave as expected. This is the default. When using Remote/Emulation directly on a console, the controller will not be detected for technical reasons. +When playing via PS Remote Play specifically, since Console mode does not appear as an authentic DualShock 4 controller, it will not be detected. Using an alternate Remote Play client, such as Chiaki, does not have this limitation. +Unless something changes specifically in PS Remote Play, authorization is not required in Remote/Emulation mode. - `Authentication Settings` - `Host USB` - Use a dongle, converter, or licensed PS4 controller to authenticate your GP2040-CE device @@ -87,6 +99,38 @@ In order to use this setting, a USB Peripheral must be configured in [Web Config In order to use this setting, a USB Peripheral must be configured in [Web Configurator > Peripheral Mapping > USB Host](./03-peripheral-mapping.mdx#usb-host) +### Experimental USB Hub Support + +GP2040-CE now has experimental support for USB hubs. A USB hub will now let you connect multiple authentication dongles as well as a keyboard. + +There are no settings to change for USB hub support, it is simply plug and play. + +As an example, you could have the following connected to a USB hub: +1 - USB keyboard +2 - Mayflash MagicBoots PS4 v1.1 dongle +3 - Mayflash MagicBoots Xbox 1 dongle +4 - Mayflash MagicBoots Xbox 360 dongle + +So long as the USB hub is compatible this combination should let switch between PS5 / Xbox / Xbox360 mode without physically switching the dongles around. + +This will also, for the first time, allow you to use a keyboard in PS5 / Xbox / Xbox360 mode (without authentication issues so long as an appropriate dongle is used). + +:::caution + +USB Hub Support is currently experimental. We do not recommend that it be used for commercial applications. + +We do not guarantee that any combination of devices and hubs will work and we will not accept support tickets or GitHub issues about combinations that do not work at this time. + +We have seen issues with some USB hubs. We do not guarantee that any single hub will or will not work and we have no plans to introduce a list of known good hubs. + +We have also seen issues with some dongles when added to a USB hub setup like the Mayflash Magic-X. When the Mayflash Magic-X is added to a USB hub it may not work as intended and also may cause other dongles not to work as intended. + +We leave it to the user to explore various combinations and see what works and does not work for them. + +Please be mindful of power draw if you are adding multiple dongles and a USB hub to devices and setups that use LEDs. If you are finding issues with your setup try turning off LEDs. + +::: + ## Gamepad Settings ![GP2040-CE Configurator - Gamepad Settings](../../assets/images/gpc-settings-gamepad.png) diff --git a/docs/web-configurator/menu-pages/02-pin-mapping.mdx b/docs/web-configurator/menu-pages/02-pin-mapping.mdx index 714e966..ea8298d 100644 --- a/docs/web-configurator/menu-pages/02-pin-mapping.mdx +++ b/docs/web-configurator/menu-pages/02-pin-mapping.mdx @@ -53,11 +53,11 @@ If you do not know what pins are mapped to which button on your device, there is You can configure profiles that will change the GPIO to GP2040-CE button mappings based on what profile number you have set. This means that you can have button layouts for different use cases and change between them without the need to enter the Web Configurator and remap GPIO pins. -The profile number either using the Web Configurator on the [Settings page](../../web-configurator/menu-pages/01-settings.mdx) or using a [hotkey shortcut](../../hotkeys.mdx#load-profile-1-4). There is not a default input combination associated with these `Load Profile #1-4` hotkey shortcuts so you will likely need to set them up in the Settings page under [Hotkey Settings](../../web-configurator/menu-pages/01-settings.mdx#hotkey-settings). +The profile number can be changed by either using the Web Configurator on the [Settings page](../../web-configurator/menu-pages/01-settings.mdx) or using a [hotkey shortcut](../../hotkeys.mdx#load-profile-1-4). There is not a default input combination associated with these `Load Profile #1-4` or `Next Profile` hotkey shortcuts so you will likely need to set them up in the Settings page under [Hotkey Settings](../../web-configurator/menu-pages/01-settings.mdx#hotkey-settings). The default is profile #1 on first boot, but will remember the last set profile between boots. :::info -At this time, profiles are limited to changing GPIO pin assignment can cannot be used to change other settings and add-ons that are not directly related to GPIO pin assignment and available to set. This includes, but is not limited to, settings and add-ons such as +At this time, profiles are limited to changing GPIO pin assignment and cannot be used to change other settings and add-ons that are not directly related to GPIO pin assignments available to set. This includes, but is not limited to, settings and add-ons such as - Boot Input Modes - Hotkeys diff --git a/sidebarsDevelopment.json b/sidebarsDevelopment.json index 7e50bde..5b9f86d 100644 --- a/sidebarsDevelopment.json +++ b/sidebarsDevelopment.json @@ -3,12 +3,9 @@ "contribution-guide", { "type": "category", - "label": "Firmware Development", + "label": "Firmware", "collapsed": false, - "items": [ - "modifying-gamepad-state", - "debugging" - ] + "items": ["firmware-development"] }, { "type": "category",