gnwmanager/tutorials/filesystem.md

Filesystem Management

GnWManager supports interactions with a LittleFS partition on the Game & Watch's external SPI Flash.

In general, the external SPI flash layout is as follows:

If running multiple firmwares, typically:

1. Firmware 1 is the patched factory firmware.
2. Firmware 2 is retro-go

Format

Format a new filesystem partition.

gnwmanager format [OPTIONS]

Help string:

╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --size            INT_PARSER  Size of filesystem. Defaults to previous filesystem size.                           │
│ --offset          INT_PARSER  Distance in bytes from the END of the filesystem, to the END of flash. [default: 0] │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

If no --size is specified, and a previous filesystem existed, it will format to the old filesystem's size.

Shell

Enter an interactive unix-like shell. All commands in this tutorial are available in the interactive shell.

gnwmanager shell

For example:

$ gnwmanager shell
Interactive shell. Press Ctrl-D to exit.
gnw$ mkdir hello-world
gnw$ mkdir hello-world/foo/bar/baz
gnw$ tree
.
└── [      0B DIR                     ] hello-world
    └── [      0B DIR                     ] foo
        └── [      0B DIR                     ] bar

Note: * wildcard for files/folders will not be expanded by gnwmanager's shell. * wildcard expansion is handled by your computer's shell.

ls

List the contents of a directory

gnwmanager ls

Example:

$ gnwmanager ls hello-world
      0B DIR                      foo

tree

List contents of device directory and its descendants.

Help string:

$ gnwmanager tree --help

 Usage: gnwmanager tree [OPTIONS] [PATH]

 List contents of device directory and its descendants.

╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────────╮
│   path      [PATH]  On-device folder path to list. Defaults to root [default: .]                                  │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --depth           INT_PARSER  Maximum depth of the directory tree. [default: 2]                                   │
│ --offset          INT_PARSER  Distance in bytes from the END of the filesystem, to the END of flash. [default: 0] │
│ --help    -h                  Show this message and exit.                                                         │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Example:

$ gnwmanager tree hello-world
hello-world
└── [      0B DIR                     ] foo
    └── [      0B DIR                     ] bar
        └── [      0B DIR                     ] baz

mkdir

Creates a folder (and all necessary parenting folders) on-device.

gnwmanager mkdir my_directory_name

This is most equivalent to mkdir -p my_new_dir on Unix systems. If the directory already exists, no action is performed.

mv

Moves/Renames a file/folder on-device. Not for transferring data to/from computer.

gnwmanager mv src dst

cp

Copies a file/folder on-device. Not for transferring data to/from computer.

gnwmanager cp src dst

push

Pushes file(s) and folder(s) to device.

gnwmanager push

Help string:

$ gnwmanager push --help

 Usage: gnwmanager push [OPTIONS] GNW_PATH LOCAL_PATHS...

 Push file(s) and folder(s) to device.

╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    gnw_path         PATH            Game-and-watch file or folder to write to. [required]                       │
│ *    local_paths      LOCAL_PATHS...  Local file or folder to copy data from. [required]                          │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --offset          INT_PARSER  Distance in bytes from the END of the filesystem, to the END of flash. [default: 0] │
│ --help    -h                  Show this message and exit.                                                         │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Note that the destination gnw_path is the first argument. Pushing files follows the same rules as the unix cp -r outlined below:

1. Pushing a directory to another location without a target directory name specified:

   gnwmanager push /destination/ /source/directory
   

   This will push the /source/directory to /destination/directory. If /destination/directory does not already exist, it will be created. If it does exist, the contents of /source/directory will be merged into the existing /destination/directory.

2. Pushing a directory to another location with a target directory name specified:

   gnwmanager push /destination/newname /source/directory
   

   This will copy /source/directory to /destination/newname. If /destination/newname does not already exist, it will be created. If it does exist and is a directory, the contents of /source/directory will be merged into the existing /destination/newname. If /destination/newname exists and is a file, the command will fail.

3. Copying only the contents of a directory:

   gnwmanager push /destination/ /source/directory/*
   

   By using the * wildcard, you're selecting all items inside /source/directory. These items will be copied directly into /destination/. If /destination/ has some of the same named items, they will be overwritten by the ones from /source/directory. If /destination/ does not exist, it (and any required parents) will be created.

pull

Pulls file(s) and folder(s) from device.

gnwmanager pull

Help string:

$ gnwmanager pull --help

 Usage: gnwmanager pull [OPTIONS] GNW_PATH LOCAL_PATH

 Pull a file or folder from device.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    gnw_path        PATH  Game-and-watch file or folder to copy to computer. [required]                         │
│ *    local_path      PATH  Local file or folder to copy data to. [required]                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --offset          INT_PARSER  Distance in bytes from the END of the filesystem, to the END of flash. [default: 0]│
│ --help    -h                  Show this message and exit.                                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Note that the source gnw_path is the first argument.