Package: gp2040ce-binary-tools
GP2040-CE Binary ToolsTools for working with GP2040-CE binary dumps.DependenciesWhile not necessary for most tools, you may wantpicotoolas an alternative
way to dump binary data from the board. These dumps can be created withgp2040ce-binary-toolsnatively, but having an
alternative way to create a binary dump can be helpful, as these tools work as well (or better) with a binary dump as
over USB.Protobuf FilesAll tools take-P PATHflag(s) in order to import Protobuf files (either precompiled Python files or raw .proto files)
if you have them locally, in order to work with the latest (or development) version of the configuration. That said,
this tool also includes a precompiled fallback version of the config structure if you cannot supply these files. Be
aware, however, that they are a point in time snapshot, and may lag the real format in undesirable ways. Supply the
latest Protobuf files if you can.An example of this invocation is:visualize-storage -P ~/proj/GP2040-CE/proto -P ~/proj/GP2040-CE/lib/nanopb/generator/proto --filename memory.binInstallation% pip install gp2040ce-binary-toolsDevelopment Installation% git clone [URL to this repository]
% cd gp2040ce-binary-tools
% python -m venv venv
% source ./venv/bin/activate
% pip install -e .
% pip install -Ur requirements/requirements-dev.txtToolsIn all cases, online help can be retrieved by providing the-hor--helpflags to the below programs.Config EditorA terminal UI config editor, capable of viewing and editing existing configurations, can be launched viaedit-config. It supports navigation both via the keyboard or the mouse, and can view and edit either a binary file
made viapicotoolor configuration directly on the board in BOOTSEL mode over USB.Simple usage:Key(s)ActionUp, DownMove up and down the config treeLeft, RightScroll the tree left and right (when content is long)SpaceExpand a tree node to show its childrenEnterExpand a tree node, or edit a leaf node (bools toggle)Tab (in edit popup)Cycle highlight between input field and buttonsEnter (in edit popup)Choose dropdown option or activate buttonSSave the config to the opened fileQQuit without savingA quick demonstration of the editor is availableon asciinema.org.concatenateconcatenatecombines a GP2040-CE firmware .bin file (such as from a fresh build) with:a GP2040-CE board config, in the form ofa config section .bin (with footer) (optionally padded) (--binary-board-config-filename) ora JSON file representing the config (--json-board-config-filename)and/or a GP2040-CE user config, in the form ofa config section .bin (with footer) (optionally padded) (--binary-user-config-filename) ora JSON file representing the config (--json-user-config-filename)...and produces a properly-offset firmware file suitable for flashing to a board with the provided config(s). This may
be useful to ensure the board is flashed with a particular configuration, for instances such as producing a binary to
flash many boards with a particular configuration (specific customizations, etc.), creating a file suitable for the
initial install of a fresh board (a "board config"), or keeping documented backups of what you're testing with during
development.The--...-board-config-filenameflags allow for shipping a default configuration as part of the binary, replacing
the need for generating these board configurations at compile time. This allows for more custom builds and less
dependency on the build jobs, and is a feature in progress in the core firmware.The produced firmware + config(s) can be written to a file with--new-binary-filename FILENAMEor straight to a RP2040
in BOOTSEL mode with--usb. The output file is a direct binary representation by default, but ifFILENAMEends in
".uf2", it will be written in the UF2 format, which is generally more convenient to the end user.Sample usage:% concatenate build/GP2040-CE_foo_bar.bin --binary-user-config-filename storage-dump.bin \
    --new-binary-filename new-firmware-with-config.bindump-configdump-configreplaces the need for picotool in order to make a copy of the GP2040-CE configuration as a binary file.
This could be used with the other tools, or just to keep a backup.Sample usage:% dump-config `date +%Y%m%d`-config-backup.bindump-gp2040cedump-gp2040cereplaces the need for picotool in order to make a copy of a board's full GP2040-CE image as a binary file.
This could be used with the other tools, or just to keep a backup.Sample usage:% dump-gp2040ce `date +%Y%m%d`-backup.binvisualize-storagevisualize-storagereads a GP2040-CE board's configuration, either over USB or from a dump of the board's flash
storage section, and prints it out for visual inspection or diffing with other tools. It can also find the storage
section from a GP2040-CE whole board dump, if you have that instead. Usage is simple; just connect your board in BOOTSEL
mode or pass the tool your binary file to analyze along with the path to the Protobuf files.Sample output:% visualize-storage --usb
boardVersion: "v0.7.2"
gamepadOptions {
  inputMode: INPUT_MODE_HID
  dpadMode: DPAD_MODE_DIGITAL
  socdMode: SOCD_MODE_SECOND_INPUT_PRIORITY
  invertXAxis: false
  invertYAxis: false
  switchTpShareForDs4: true
  lockHotkeys: false
}
hotkeyOptions {
  hotkeyF1Up {
    dpadMask: 1
    action: HOTKEY_SOCD_UP_PRIORITY
  }
  hotkeyF1Down {
    dpadMask: 2
    action: HOTKEY_SOCD_NEUTRAL
  }
  ...[and so on]...
}
pinMappings {
  pinDpadUp: 19
  pinDpadDown: 18
  pinDpadLeft: 16
  pinDpadRight: 17
  pinButtonB1: 8
  pinButtonB2: 7
  pinButtonB3: 12
  pinButtonB4: 11
  pinButtonL1: 9
  pinButtonR1: 10
  pinButtonL2: 5
  pinButtonR2: 6
  pinButtonS1: 15
  pinButtonS2: 13
  pinButtonL3: 21
  pinButtonR3: 22
  pinButtonA1: 14
  pinButtonA2: 20
}
...[and so on]...
addonOptions {
  bootselButtonOptions {
    enabled: false
    buttonMap: 0
  }
  ...[and so on]...
  dualDirectionalOptions {
    enabled: true
    upPin: 23
    downPin: 27
    leftPin: 26
    rightPin: 24
    dpadMode: DPAD_MODE_DIGITAL
    combineMode: 3
  }
  ...[and so on]...
}
forcedSetupOptions {
  mode: FORCED_SETUP_MODE_OFF
}MiscellaneousVersion informationThe GP2040-CE configuration is still changing, so the tools are changing accordingly. This project doesn't currently make
a huge effort to be backwards compatible, so instead, refer to this:gp2040ce-binary-tools >=v0.5.1supportsGP2040-CE >=v0.7.5.gp2040ce-binary-tools <=v0.5.0supportedGP2040-CE <v0.7.5.Dumping the GP2040-CE board with picotoolSome of these tools require a dump of your GP2040-CE board, either the storage section or the whole board, depending on
the context. The storage section of a GP2040-CE board is a reserved 16 KB starting at0x101FC000. To dump your board's
storage with picotool:% picotool save -r 101FC000 10200000 memory.binAnd to dump your whole board:% picotool save -a whole-board.bin