Skip to main content

Configuration

note

We're looking to move away from compile time configuration, in favor of runtime configuration.

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 folder. This document will outline setting up a new build configuration.

Board Configuration Folder​

Each subfolder in configs contains a separate board configuration, which consists of the following:

NameRequired?Description
BoardConfig.hYesThe configuration file used when building GP2040-CE for a specific controller/board. Contains initial pin mappings, LED configuration, etc.
README.mdxNoProvides information related to this board configuration. Not required for the build process, but suggested for pull requests of new board configurations.
assets/NoFolder for containing assets included in the README.mdx. Not required for the build process.
<boardname.h>NoBoard definition file, named after the board itself, used by the Pico SDK for configuring board specific SDK features. Pico Example

Board Configuration (BoardConfig.h)​

The following board options are available in the BoardConfig.h file:

NameDescriptionRequired?
PINDPADX
PINBUTTONX		The GPIO pin for the button. Replace the X with GP2040-CE button or DPad direction.Yes
DEFAULT_SOCD_MODEThe default SOCD mode to use, defaults to SOCD_MODE_NEUTRAL.
Available options are:
SOCD_MODE_NEUTRAL
SOCD_MODE_UP_PRIORITY
SOCD_MODE_SECOND_INPUT_PRIORITY		No
BUTTON_LAYOUTThe layout of controls/buttons for use with per-button LEDs and external displays.
Available options are:
BUTTON_LAYOUT_STICKLESS
BUTTON_LAYOUT_WASD		Yes

Create configs/NewBoard/BoardConfig.h and add your pin configuration and options. An example BoardConfig.h file:

// BoardConfig.h

#include <GamepadEnums.h>

#define PIN_DPAD_UP     2
#define PIN_DPAD_DOWN   3
#define PIN_DPAD_LEFT   4
#define PIN_DPAD_RIGHT  5
#define PIN_BUTTON_B1   6
#define PIN_BUTTON_B2   7
#define PIN_BUTTON_B3   8
#define PIN_BUTTON_B4   9
#define PIN_BUTTON_L1   10
#define PIN_BUTTON_R1   11
#define PIN_BUTTON_L2   26
#define PIN_BUTTON_R2   27
#define PIN_BUTTON_S1   16
#define PIN_BUTTON_S2   17
#define PIN_BUTTON_L3   18
#define PIN_BUTTON_R3   19
#define PIN_BUTTON_A1   20
#define PIN_BUTTON_A2   21
#define PIN_BUTTON_TURBO -1
#define PIN_SLIDER_LS    -1
#define PIN_SLIDER_RS    -1

#define DEFAULT_SOCD_MODE SOCD_MODE_NEUTRAL
#define BUTTON_LAYOUT BUTTON_LAYOUT_ARCADE

RGB LEDs​

GP2040-CE supports per-button WS2812 and similar RGB LEDs.

The following RGB LED options are available in the BoardConfig.h file:

NameDescriptionRequired?
BUTTON_LAYOUTThe layout of controls/buttons for use with per-button LEDs and external displays.
Available options are:
BUTTON_LAYOUT_STICKLESS
BUTTON_LAYOUT_WASD		Yes
BOARD_LEDS_PINData PIN for your LED strandYes
LED_FORMATThe color data format for the LED chain.
Available options are:
LED_FORMAT_GRB
LED_FORMAT_RGB
LED_FORMAT_GRBW
LED_FORMAT_RGBW		No, default value LED_FORMAT_GRB
LEDS_PER_PIXELThe number of LEDs per button.Yes
LED_BRIGHTNESS_MAXIMUMMax brightness value, uint8_t 0-255.Yes
LED_BRIGHTNESS_STEPSThe number of brightness steps when using the up/down hotkey.Yes
LEDSDPADX
LEDSBUTTONX		The index of the button on the LED chain. Replace the X with GP2040-CE button or DPad direction.Yes
LEDS_BASE_ANIMATION_INDEXThe default LED animation index.No, defaults to 1
LEDS_STATIC_COLOR_INDEXThe default color index for the static color themeNo, defaults to 2
LEDS_BUTTON_COLOR_INDEXThe default color index for the pressed button colorNo, defaults to 1
LEDS_THEME_INDEXThe default theme index for static themesNo, defaults to 0
LEDS_RAINBOW_CYCLE_TIMEThe color cycle time for rainbow cycle themeNo, defaults to 40
LEDS_CHASE_CYCLE_TIMEThe animation speed for the rainbow chase themeNo, defaults to 85

An example RGB LED setup in the BoardConfig.h file:

// BoardConfig.h

#include "gp2040.h"
#include "NeoPico.hpp"

#define BUTTON_LAYOUT BUTTON_LAYOUT_STICKLESS

#define BOARD_LEDS_PIN 22

#define LED_BRIGHTNESS_MAXIMUM 100
#define LED_BRIGHTNESS_STEPS 5
#define LED_FORMAT LED_FORMAT_GRB
#define LEDS_PER_PIXEL 2

#define LEDS_DPAD_LEFT   0
#define LEDS_DPAD_DOWN   1
#define LEDS_DPAD_RIGHT  2
#define LEDS_DPAD_UP     3
#define LEDS_BUTTON_B3   4
#define LEDS_BUTTON_B4   5
#define LEDS_BUTTON_R1   6
#define LEDS_BUTTON_L1   7
#define LEDS_BUTTON_B1   8
#define LEDS_BUTTON_B2   9
#define LEDS_BUTTON_R2   10
#define LEDS_BUTTON_L2   11

Player LEDs​

GP2040-CE supports PWM and RGB player LEDs (PLEDs) and can be configured in the BoardConfig.h file.

note

RGB PLEDs require RGB LEDs to be configured.

The following PLED options are available in the BoardConfig.h file:

NameDescriptionRequired?
PLED_TYPEConfigures the type of PLEDs.
Available options are: PLED_TYPE_PWM, PLED_TYPE_RGB		Yes
PLED1_PIN(PWM) The GPIO pin for PLED #1.
(RGB) The index of PLED #1 on the LED chain.		Yes
PLED2_PIN(PWM) The GPIO pin for PLED #2.
(RGB) The index of PLED #2 on the LED chain.		Yes
PLED3_PIN(PWM) The GPIO pin for PLED #3.
(RGB) The index of PLED #3 on the LED chain.		Yes
PLED4_PIN(PWM) The GPIO pin for PLED #4.
(RGB) The index of PLED #4 on the LED chain.		Yes

An example PLED setup in the BoardConfig.h file:

// BoardConfig.h

#include "PlayerLEDs.h"

#define PLED_TYPE PLED_TYPE_RGB
#define PLED1_PIN 12
#define PLED2_PIN 13
#define PLED3_PIN 14
#define PLED4_PIN 15

I2C Displays​

GP2040-CE supports 128x64 monochrome displays that run on the SSD1306, SH1106 or SH1107 drivers. The following options are available for displays:

NameDescriptionRequired?
BUTTON_LAYOUTThe layout of controls/buttons for use with per-button LEDs and external displays.
Available options are:
BUTTON_LAYOUT_STICKLESS
BUTTON_LAYOUT_WASD		Yes
HAS_I2C_DISPLAYFlag to indicate the controller contains an I2C display module.No
DISPLAY_I2C_ADDRThe I2C address of the display.No, defaults to 0x3C
I2C_SDA_PINThe GPIO pin for the I2C SDA line.If HAS_I2C_DISPLAY is enabled
I2C_SCL_PINThe GPIO pin for the I2C SCL line.If HAS_I2C_DISPLAY is enabled
I2C_BLOCKThe I2C block on the Pico. Refer to the Pico Pinout Diagram to identify which block is in use based on the SDA and SCL pins being used.
Available options are:
i2c0
i2c1		No, defaults to i2c0
I2C_SPEEDThe speed of the I2C bus. 100000 is standard mode, while 400000 is used for fast mode communication. Higher values may be used but will require testing the device for support.No, defaults to 400000
DISPLAY_FLIPFlag to flip the rendered display output. Set to 1 to enable.No, defaults to 0
DISPLAY_INVERTFlag to invert the rendered display output. Set to 1 to enable.No, defaults to 0

An example I2C display setup in the BoardConfig.h file:

#define BUTTON_LAYOUT BUTTON_LAYOUT_WASD
#define HAS_I2C_DISPLAY 1
#define I2C_SDA_PIN 0
#define I2C_SCL_PIN 1
#define I2C_BLOCK i2c0
#define I2C_SPEED 800000

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.

You can find an example of how to set this up in the Zero Rhythm BoardConfig.h file.

For a full breakdown of possibilties please see below.

BUTTON_GROUP structure
{
  {element, {x, y, w, h, stroke, fill, value, object, ...extra}},
  ...
}

element - one of the following types
GP_ELEMENT_WIDGET      - general use widget (needs to be expanded)
GP_ELEMENT_SCREEN      - screen (only defined as a root-level display navigation element)
GP_ELEMENT_BTN_BUTTON  - button (Gamepad button mask)
GP_ELEMENT_DIR_BUTTON  - button (Gamepad D-Pad mask)
GP_ELEMENT_PIN_BUTTON  - button (GPIO digital pin)
GP_ELEMENT_LEVER       - lever (uses D-Pad modes to determine action - dpad or analog)
GP_ELEMENT_LABEL       - text label (needs some love)
GP_ELEMENT_SPRITE      - sprite object (same - used for placing static images on the layout)
GP_ELEMENT_SHAPE       - shape object (similar to button elements but no reactivity)

object - one of the following types
GP_SHAPE_ELLIPSE
GP_SHAPE_SQUARE
GP_SHAPE_DIAMOND
GP_SHAPE_POLYGON
GP_SHAPE_ARC

x, y, w, h - depends on the object type

GP_SHAPE_ELLIPSE
x, y     center of the ellipse
w        radius

GP_SHAPE_SQUARE
x, y     left/top positions
w, h     right/bottom positions

GP_SHAPE_DIAMOND
x, y     center of shape
w        size

GP_SHAPE_POLYGON
x, y     center of the polygon
w        radius
h        number of sides
extra[0] rotation

GP_SHAPE_ARC
x, y     center of the arc (assume ellipse)
w        radius
extra[0] start point of angle (angle)
extra[1] end point of angle (angleEnd)
extra[2] draw to inner point of angle (closed)

I2C Display Splash​

The firmware also has a splash display feature. The default splash image has been defined in headers/add-ons/i2cdisplay.h. The data for the splash image are bytes representing the bitmap to be displayed on the OLED screen. The splash image can be set via the web-config. If you would like to change the default version of the splash image (to preserve it beyond data wipe), it can be customized with a C define named DEFAULT_SPLASH in the active BoardConfig.h file. The instructions on how to generate those bytes are as follows:

  1. Navigate to Bitmap Converter web utility

  2. Configure generated code

    • Select Marlin 2.x and Bitmap, untick all the rest.

  3. Upload the splash image file

    • Set the image file after clicking on "Choose file". The image file needs to be preprocessed to your liking and cropped to 128x64. This should populate a code block below.

  4. Use the generated code

    • Copy the hex numbers inside the curly braces from the code block.

    • Navigate to the BoardConfig.h of your choice and at the end of the file right before #endif. Create a C define like so:

      #define DEFAULT_SPLASH \

    • Then paste what you copied below what you just typed. Be sure to edit the array of bytes as follows:

      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \ // First line
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \ // Second line
      ... // All lines below previous ones end in \ similar to those above
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00 // Last line doesn't have an \ to escape the new line

    • Here's a sample entry from Pico BoardConfig.h:

      #define DEFAULT_SPLASH \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x20,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x40,0x80,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xE0,0xDF,0xC0, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x02,0xC1,0xFF,0xA0, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x1F,0xCF,0xFE,0x80, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x3F,0xFF,0xE0,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x7F,0xAB,0xC0,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x2C,0x00,0x00,0xFB,0x83,0xFF,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x0C,0x01,0xFF,0x00,0x01,0xF3,0x07,0xFC,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x1C,0x07,0xFF,0x00,0x03,0xE0,0x3F,0xF4,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x2C,0x38,0x0A,0xE7,0x80,0x03,0xC0,0x5F,0x80,0x00, \
      0x00,0x00,0x00,0x20,0x07,0x81,0xFF,0x39,0xC3,0xC7,0x01,0xD7,0x80,0x3F,0x00,0x00, \
      0x00,0x00,0x00,0xE0,0x1F,0xE7,0xFF,0x79,0xC7,0x87,0x9F,0xA7,0x80,0x6E,0x3C,0x00, \
      0x00,0x00,0xA0,0xC0,0x3F,0xEA,0xE7,0xF3,0xEF,0x07,0x7F,0xC7,0x01,0xCF,0xFF,0x80, \
      0x00,0x03,0x8F,0xFC,0x7F,0xC3,0xC7,0x7F,0xFE,0x0F,0x7E,0x8F,0x87,0xDF,0xFC,0x00, \
      0x00,0x0F,0xFF,0xFF,0x73,0xC7,0x87,0xFF,0xDE,0x0E,0x50,0x07,0x1F,0x1F,0xD0,0x00, \
      0x00,0x1F,0x57,0xFF,0xE7,0x8F,0x07,0xFF,0x1C,0x3E,0x00,0x0F,0xFF,0x7F,0x00,0x00, \
      0x00,0x7E,0x0B,0x8F,0x8F,0x8E,0x0F,0xFF,0x9E,0x7C,0x00,0x07,0xFD,0xFC,0x00,0x00, \
      0x00,0x7C,0x37,0x9F,0x1F,0x1E,0x0F,0x87,0x1E,0xF8,0x00,0x07,0xF0,0x30,0x00,0x00, \
      0x00,0xF1,0xF7,0xFE,0x1E,0x1C,0x3E,0x0E,0x1F,0xF0,0x00,0x01,0x40,0x28,0x00,0x00, \
      0x01,0xEF,0xE7,0xF8,0x3C,0x3E,0x7C,0x0F,0x1F,0xE0,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x03,0xFF,0x8F,0xF0,0x7F,0xFE,0xF8,0x0E,0x0F,0x80,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x03,0xFF,0xCF,0xC0,0xFF,0xFF,0xF0,0x0C,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x07,0x8B,0xFF,0x01,0xFF,0x8F,0xC0,0x06,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x07,0x87,0xFE,0x01,0xFE,0x0F,0x80,0x04,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x07,0x1F,0xDE,0x03,0xF0,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x07,0xBF,0x9E,0x01,0xC0,0x00,0x00,0x04,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x07,0xFF,0x9C,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x07,0xFB,0x38,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x03,0xE7,0x30,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x01,0x47,0x28,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x0E,0x20,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x0C,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x04,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x08,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00, \
      0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00

  5. Test and verify

    • Compile, if you did everything right, it should compile fine
    • Load the UF2 after the compile. Check and verify in the web-config, if you have set a custom image before, you might need to reset data.