<div align="center">
<img src="https://raw.githubusercontent.com/BrianPugh/gnwmanager/main/assets/screenshot.png">
</div>
<div align="center">
[](https://pypi.org/project/gnwmanager/)
</div>
# 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](tutorials/installation.md)
- [Device Unlocking](tutorials/unlock.md)
- [Binary Flashing](tutorials/flash.md)
- [Filesystem Management](tutorials/filesystem.md)
- [Extracting Screenshots](tutorials/screenshot.md)
Tutorials useful for developers
- [Device Locking](tutorials/lock.md)
- [Stdout Monitoring](tutorials/monitor.md)
- [Flash Erasing](tutorials/erase.md)
## Compatibility
GnWManager works with all major operating systems: Windows, Mac, and Linux.
GnWManager is also compatible with the following probes:
1. [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/) (Recommended)
2. [STLink](https://www.st.com/en/development-tools/st-link-v2.html)
3. [JLink](https://www.segger.com/products/debug-probes/j-link/#models)
4. [DAPLink](https://daplink.io)
5. [Raspberry Pi (GPIO)](https://projects.raspberrypi.org/en/projects/physical-computing/1)
#### Raspberry Pi Pico
All Raspberry Pi Picos can be transformed into programmers via the [picoprobe project](https://github.com/raspberrypi/picoprobe).
1. Download `picoprobe.uf2` from [picoprobe releases](https://github.com/raspberrypi/picoprobe/releases).
2. 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.
3. Hook up the 3 wires (GND, GP2, GP3) to (GND, SDCLK, SWDIO), respectively.
<div align="center">
<img width=512 src="https://raw.githubusercontent.com/BrianPugh/gnwmanager/main/assets/pi-pico.png">
</div>
#### STLink
Hook up your STLink to your game and watch as follows:
<div align="center">
<img width=512 src="https://raw.githubusercontent.com/BrianPugh/gnwmanager/main/assets/stlinkv2.png">
</div>
#### Raspberry Pi (GPIO)
Hook up your Raspberry Pi to your game and watch as follows:
<div align="center">
<img width=512 src="https://raw.githubusercontent.com/BrianPugh/gnwmanager/main/assets/raspberry-pi.png">
</div>
## Usage
To see available commands, run `gnwmanager --help`.
```console
$ 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](https://discord.gg/zBN3ex8v4p) 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](https://pre-commit.com/) to run linting, and [poetry](https://python-poetry.org/) for python management.
```bash
git clone git@github.com: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:
```bash
gnwmanager/firmware.bin
gnwmanager/unlock.bin
```
Raw data
{
"_id": null,
"home_page": "https://github.com/BrianPugh/gnwmanager",
"name": "gnwmanager",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Brian Pugh",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0b/67/cc9e8653d6d117bcfa3a7ab066bf9161fffc786084221edce8b39f0fe20f/gnwmanager-0.17.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/BrianPugh/gnwmanager/main/assets/screenshot.png\">\n</div>\n\n<div align=\"center\">\n\n\n[](https://pypi.org/project/gnwmanager/)\n\n</div>\n\n# GnWManager\n\nGnWManager is THE game-and-watch device manager. GnWManager is a command line tool\nwho's responsible for getting firmware onto your device, managing the filesystem,\nand other device administrative tasks.\n\nGnWManager accomplishes this via a small bundled pre-compiled firmware that gets\nexecuted from the STM32's RAM.\n\n## Features\n\n* Simple installation.\n* Works on all operating systems (Linux, MacOS, Windows).\n* Automatic debugging probe detection.\n * No need to specify if you have a stlink, jlink, CMSIS-DAP, or Raspberry Pi.\n* Fast internal and external flash firmware flashing.\n * Hardware-accelerated hashing for rapid duplicate discovery.\n * Only syncs changed data.\n * Minimizes flash erases and writes, extending flash lifespan.\n * Double buffered, asynchronous, LZMA-compressed transfers for maximum speed.\n* Complete filesystem management.\n * Backup and restore files.\n * Interactive filesystem explorer.\n* Automatic Real-Time-Clock (RTC) configuration.\n* Developer tools:\n * Easily monitor device ``printf`` statements and launch GDB sessions.\n * Capture screenshots, regardless of the running firmware.\n\n## Tutorials\nTutorials useful for typical end-users\n - [Installation](tutorials/installation.md)\n - [Device Unlocking](tutorials/unlock.md)\n - [Binary Flashing](tutorials/flash.md)\n - [Filesystem Management](tutorials/filesystem.md)\n - [Extracting Screenshots](tutorials/screenshot.md)\n\nTutorials useful for developers\n - [Device Locking](tutorials/lock.md)\n - [Stdout Monitoring](tutorials/monitor.md)\n - [Flash Erasing](tutorials/erase.md)\n\n## Compatibility\nGnWManager works with all major operating systems: Windows, Mac, and Linux.\nGnWManager is also compatible with the following probes:\n\n1. [Raspberry Pi Pico](https://www.raspberrypi.com/products/raspberry-pi-pico/) (Recommended)\n2. [STLink](https://www.st.com/en/development-tools/st-link-v2.html)\n3. [JLink](https://www.segger.com/products/debug-probes/j-link/#models)\n4. [DAPLink](https://daplink.io)\n5. [Raspberry Pi (GPIO)](https://projects.raspberrypi.org/en/projects/physical-computing/1)\n\n#### Raspberry Pi Pico\n\nAll Raspberry Pi Picos can be transformed into programmers via the [picoprobe project](https://github.com/raspberrypi/picoprobe).\n\n1. Download `picoprobe.uf2` from [picoprobe releases](https://github.com/raspberrypi/picoprobe/releases).\n2. 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.\n3. Hook up the 3 wires (GND, GP2, GP3) to (GND, SDCLK, SWDIO), respectively.\n\n<div align=\"center\">\n <img width=512 src=\"https://raw.githubusercontent.com/BrianPugh/gnwmanager/main/assets/pi-pico.png\">\n</div>\n\n\n#### STLink\nHook up your STLink to your game and watch as follows:\n\n<div align=\"center\">\n <img width=512 src=\"https://raw.githubusercontent.com/BrianPugh/gnwmanager/main/assets/stlinkv2.png\">\n</div>\n\n#### Raspberry Pi (GPIO)\nHook up your Raspberry Pi to your game and watch as follows:\n\n<div align=\"center\">\n <img width=512 src=\"https://raw.githubusercontent.com/BrianPugh/gnwmanager/main/assets/raspberry-pi.png\">\n</div>\n\n## Usage\nTo see available commands, run `gnwmanager --help`.\n\n```console\n$ gnwmanager --help\n\n Usage: gnwmanager [OPTIONS] COMMAND [ARGS]...\n\n Game And Watch Device Manager.\n Manages device flashing, filesystem management, peripheral configuration, and more.\n\n\u256d\u2500 Options \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 --version -v Print gnwmanager version. \u2502\n\u2502 --frequency -f INT_PARSER Probe frequency. [default: None] \u2502\n\u2502 --backend -b [pyocd] OCD Backend. [default: pyocd] \u2502\n\u2502 --help Show this message and exit. \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n\u256d\u2500 Commands \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 debug GnWManager internal debugging tools \u2502\n\u2502 disable-debug Disable the microcontroller's debug block. \u2502\n\u2502 erase Erase a section of flash. \u2502\n\u2502 flash Flash firmware to device. \u2502\n\u2502 format Format device's filesystem. \u2502\n\u2502 gdb Launch a gdbserver and connect to it with gdb. \u2502\n\u2502 gdbserver Launch a gdbserver. \u2502\n\u2502 install Install third party executables, like openocd. \u2502\n\u2502 lock Re-lock your device. \u2502\n\u2502 ls List contents of device directory. \u2502\n\u2502 mkdir Create a directory on device. \u2502\n\u2502 monitor Monitor the device's stdout logging buffer. \u2502\n\u2502 mv Move/Rename a file or directory. \u2502\n\u2502 pull Pull a file or folder from device. \u2502\n\u2502 push Push file(s) and folder(s) to device. \u2502\n\u2502 sdpush Push file(s) to SD Card connected to device. \u2502\n\u2502 screenshot Capture and transfer screenshots from device. \u2502\n\u2502 shell Launch an interactive shell to browse device filesystem. \u2502\n\u2502 start Start firmware at location. \u2502\n\u2502 tree List contents of device directory and its descendants. \u2502\n\u2502 unlock Backs up and unlocks a stock Game & Watch console. \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n```\n\n## Need Help?\nIf you need any help, either open up a github issue here, or join the [stacksmashing discord](https://discord.gg/zBN3ex8v4p) for live help.\nWhen sharing `gnwmanager` output, it is recommended to increase the verbosity level:\n\n* Via CLI argument: `gnwmanager --verbosity=debug`\n* Via environment variable `export GNWMANAGER_VERBOSITY=debug`\n\n## Developer Installation\nIf developing for GnWManager, perform the following steps to setup your local environment.\nWe use [pre-commit](https://pre-commit.com/) to run linting, and [poetry](https://python-poetry.org/) for python management.\n\n```bash\ngit clone git@github.com:BrianPugh/gnwmanager.git\ncd gnwmanager\npre-commit install # Ensures linting passes prior to committing\npoetry install\nmake -j4 # Builds stm32 firmware binaries.\n```\n\nWhen changing C sources, `make` must be re-ran to update the binaries located at:\n\n```bash\ngnwmanager/firmware.bin\ngnwmanager/unlock.bin\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": null,
"version": "0.17.0",
"project_urls": {
"Homepage": "https://github.com/BrianPugh/gnwmanager",
"Repository": "https://github.com/BrianPugh/gnwmanager"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "73e502d464e536e4829a8a59dba14b53431c22e55770cd0f022226905bf2be30",
"md5": "7e4b3a4772f0c1dc52c83d28ff2e0f26",
"sha256": "312351fc90145da578d68415cb22dc5291dda98bfa4ebabb1216ee3f1af55798"
},
"downloads": -1,
"filename": "gnwmanager-0.17.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7e4b3a4772f0c1dc52c83d28ff2e0f26",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 183587,
"upload_time": "2025-02-25T01:45:12",
"upload_time_iso_8601": "2025-02-25T01:45:12.676306Z",
"url": "https://files.pythonhosted.org/packages/73/e5/02d464e536e4829a8a59dba14b53431c22e55770cd0f022226905bf2be30/gnwmanager-0.17.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0b67cc9e8653d6d117bcfa3a7ab066bf9161fffc786084221edce8b39f0fe20f",
"md5": "5263f7cb161c7d073a83d153013ab048",
"sha256": "851da4ce476ed9047ada1145967712768ee22938f96aa2a916c85cee36924375"
},
"downloads": -1,
"filename": "gnwmanager-0.17.0.tar.gz",
"has_sig": false,
"md5_digest": "5263f7cb161c7d073a83d153013ab048",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 169344,
"upload_time": "2025-02-25T01:45:13",
"upload_time_iso_8601": "2025-02-25T01:45:13.949554Z",
"url": "https://files.pythonhosted.org/packages/0b/67/cc9e8653d6d117bcfa3a7ab066bf9161fffc786084221edce8b39f0fe20f/gnwmanager-0.17.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-25 01:45:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BrianPugh",
"github_project": "gnwmanager",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gnwmanager"
}
JSON
