gnwmanager

GnWManager

GnWManager is THE game-and-watch device manager. GnWManager is a command line tool who's responsible for getting firmware onto your device, managing the filesystem, and other device administrative tasks.

GnWManager accomplishes this via a small bundled pre-compiled firmware that gets executed from the STM32's RAM.

Features

• Simple installation.
• Works on all operating systems (Linux, MacOS, Windows).
• Automatic debugging probe detection.
  • No need to specify if you have a stlink, jlink, CMSIS-DAP, or Raspberry Pi.
• Fast internal and external flash firmware flashing.
  • Hardware-accelerated hashing for rapid duplicate discovery.
    • Only syncs changed data.
    • Minimizes flash erases and writes, extending flash lifespan.
  • Double buffered, asynchronous, LZMA-compressed transfers for maximum speed.
• Complete filesystem management.
  • Backup and restore files.
  • Interactive filesystem explorer.
• Automatic Real-Time-Clock (RTC) configuration.
• Developer tools:
  • Easily monitor device printf statements and launch GDB sessions.
  • Capture screenshots, regardless of the running firmware.

Tutorials

Tutorials useful for typical end-users

• Installation
• Device Unlocking
• Binary Flashing
• Filesystem Management
• Extracting Screenshots

Tutorials useful for developers

• Device Locking
• Stdout Monitoring
• Flash Erasing

Compatibility

GnWManager works with all major operating systems: Windows, Mac, and Linux. GnWManager is also compatible with the following probes:

• Raspberry Pi Pico (Recommended)
• STLink
• JLink
• DAPLink
• Raspberry Pi (GPIO)

Raspberry Pi Pico

All Raspberry Pi Picos can be transformed into programmers via the picoprobe project.

• Download picoprobe.uf2 from picoprobe releases.
• Hold BOOT button on the pico and plug it into the computer. It should show up as a USB drive. Drag and drop picoprobe.uf2 to it.
• Hook up the 3 wires (GND, GP2, GP3) to (GND, SDCLK, SWDIO), respectively.

STLink

Hook up your STLink to your game and watch as follows:

Raspberry Pi (GPIO)

Hook up your Raspberry Pi to your game and watch as follows:

Usage

To see available commands, run gnwmanager --help.

$ gnwmanager --help

 Usage: gnwmanager [OPTIONS] COMMAND [ARGS]...

 Game And Watch Device Manager.
 Manages device flashing, filesystem management, peripheral configuration, and more.

╭─ Options ──────────────────────────────────────────────────────────────────────────╮
│ --version    -v                  Print gnwmanager version.                         │
│ --frequency  -f      INT_PARSER  Probe frequency. [default: None]                  │
│ --backend    -b      [pyocd]     OCD Backend. [default: pyocd]                     │
│ --help                           Show this message and exit.                       │
╰────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────╮
│ debug             GnWManager internal debugging tools                              │
│ disable-debug     Disable the microcontroller's debug block.                       │
│ erase             Erase a section of flash.                                        │
│ flash             Flash firmware to device.                                        │
│ format            Format device's filesystem.                                      │
│ gdb               Launch a gdbserver and connect to it with gdb.                   │
│ gdbserver         Launch a gdbserver.                                              │
│ install           Install third party executables, like openocd.                   │
│ lock              Re-lock your device.                                             │
│ ls                List contents of device directory.                               │
│ mkdir             Create a directory on device.                                    │
│ monitor           Monitor the device's stdout logging buffer.                      │
│ mv                Move/Rename a file or directory.                                 │
│ pull              Pull a file or folder from device.                               │
│ push              Push file(s) and folder(s) to device.                            │
│ sdpush            Push file(s) to SD Card connected to device.                     │
│ screenshot        Capture and transfer screenshots from device.                    │
│ shell             Launch an interactive shell to browse device filesystem.         │
│ start             Start firmware at location.                                      │
│ tree              List contents of device directory and its descendants.           │
│ unlock            Backs up and unlocks a stock Game & Watch console.               │
╰────────────────────────────────────────────────────────────────────────────────────╯

Need Help?

If you need any help, either open up a github issue here, or join the stacksmashing discord for live help. When sharing gnwmanager output, it is recommended to increase the verbosity level:

• Via CLI argument: gnwmanager --verbosity=debug
• Via environment variable export GNWMANAGER_VERBOSITY=debug

Developer Installation

If developing for GnWManager, perform the following steps to setup your local environment. We use pre-commit to run linting, and poetry for python management.

git clone [e-mail]:BrianPugh/gnwmanager.git
cd gnwmanager
pre-commit install  # Ensures linting passes prior to committing
poetry install
make -j4  # Builds stm32 firmware binaries.

When changing C sources, make must be re-ran to update the binaries located at:

gnwmanager/firmware.bin
gnwmanager/unlock.bin