Command line reference

First determine how you've installed the application. If you installed the pre-built Windows package, then there will be a pm2hw.exe file in the base directory which you should use by either dragging it into a CMD/PowerShell window or by adding the folder to your PATH variable (search Environment Variables in your Windows search bar to find the configuration setting).

If you installed via pip you should use py -m pm2hw on Windows or python3 -m pm2hw on other systems. If you want to open the GUI from here, use pm2hw.gui instead.

If you installed via pipx and adjusted your PATH variable as it explains, then just py2hw is fine.

We will be referring to each of these as simply py2hw in this section.

Viewing the help

# Get common flags and a list of commands
pm2hw --help

# Get help on a specific command
pm2hw COMMAND --help

# Get help on a config option
pm2hw config --help OPTION

Selecting the linker

When you use any command which needs to connect to a linker, pm2hw will detect the connected linkers. If there's only one, it will connect to that. If there are multiple, it will ask you to select one (or all). To avoid this selection screen, you may either specify --all or --linker NAME to skip it.

# List supported linkgs
pm2hw --linker

# Fail if not using a DITTO mini Flasher / select that one if multiple different flashers are connected
pm2hw --linker dittoflash COMMAND ...

Common flags

• --all - Connect to all linkers. See dump section for its special handling.
• --linker NAME - Connect to linker by name. See above for list.
• --verbose - Print verbose information.
• -vv - Print debugging information.
• -vvv - Print protocol-level communications. HIGHLY recommended to redirect this to a log file.

flash

Flashing is the act of writing a ROM file to a flash card, usually via a linker. You may use f as a shorthand for this command.

# Typical flash command, just flash a ROM to the card
pm2hw flash path/to/file.min

# Flash to all connected cards
pm2hw flash -a path/to/file.min

# Flash contents of stdin to the card
pm2hw flash -

Other flags:

• --no-erase - Don't erase the cart before flashing. (NOT recommended! very slow)
• --no-verify - Don't verify the contents after flashing. (Bad idea but you can)

dump

Dumping is the act of reading a flash card and writing the contents as a ROM file on the computer, usually via a linker. You may use d as a shorthand for this command.

# Typical dump command, just dump the card to a ROM file
pm2hw dump path/to/file.min

# Dump all connected cards
pm2hw dump -a

# Dump to stdout
pm2hw dump -

When dumping from multiple cards at a time, you cannot specify a static filename (or it'll be overwritten!), so instead you may use a templated name. The filename may be templated as a Python format string using the following variables:

• i - Index of the linker (integer)
• linker - Linker name
• code - Four-character code in the ROM (ASCII)
• name - Internal name in the ROM (SHIFT-JIS)

By default uses the format: {i:02d}-{code}-{name}.min This would be rendered as, for example: 00-MPZE-Puzzle.min

Other flags:

• --partial SPEC - Dump only a partial segment from the card. This can be of the form SIZE or OFFSET:SIZE where both may be specified as natural sizes such as 256K:1024 to start 256 KiB in and dump 1024 bytes.

erase

Erasing is the act of clearing the contents of a flash card, usually via a linker. Usually you don't need to do this manually.

# Typical erase command
pm2hw erase

# Erase all connected cards
pm2hw erase -a

Other flags:

• --partial SPEC - Erase only a partial segment from the card. This can be of the form SIZE or OFFSET:SIZE where both may be specified as natural sizes such as 256K:1024 to start 256 KiB in and dump 1024 bytes.

info

Show information about a ROM file if one is specified, or otherwise connect to the linker and retrieve information from its card.

Example output:

$ py -m pm2hw info race_j.min
Internal code: MRCJ
Internal name: ﾎﾟｹﾓﾝﾚｰｽ
Developer: Jupiter Corporation
Genre: Racing
Size: 4 MBit
Players: 1~2
Features: rumble, infrared, clock, save
Save slots: 2
MINLIB version: 1.34
CRC32: 4433b736

config

Query and modify your config file. See Configuration for config options.

For linker-specific options, specify the linker name, then a period, then the option name. Such as DittoFlash.clock-divisor

# Show current config
pm2hw config --list

# See what the current language used is
pm2hw config --get language

# Set language preference order using two languages
pm2hw config --set language 'ja, en'

# Set PokeFlash's clock divisor to 1
pm2hw config --set PokeFlash.clock-divisor=1

# Get a description of what "box-languages" is
pm2hw config --help box-languages

test

Test if you card is faulty or not. This will erase your card!! It erases your card then performs a read test to check for read consistency. Then it writes random data to your card and verifies whether or not it was successful.

# Run the test on the connected card
pm2hw test

Natural size

Natural sizes are sizes in bytes or bits which we're more accustomed to as humans. Due to the size limits of Pokémon mini flash cards, this only supports bytes, kilobytes, and megabytes.

While programmers are usually familiar with a kilobyte as being 1024 bytes, the proper term for this is a kibibyte. Perhaps familiar to you from purchasing hard drives, a kilobyte follows the SI unit standards of being 1000 bytes. This distinction is mirrored in our notation, but not to worry, the single letter notations all follow powers of 2.

You may specify a value in bits or bytes. Not providing a unit implies bytes. For short-hand, since input is case-insensitive, there is no distinction between b and B, they both refer to bytes. Spaces are also optional.

Examples:

• 10 - 10 bytes
• 8 bits - 1 byte
• 11 bytes - 11 bytes
• 1 Kbits - 128 bytes
• 1 KB - 1000 bytes
• 1 KiB - 1024 bytes
• 1k - 1024 bytes
• 1 Mbits - 131,072 bytes
• 1 MB - 1,000,000 bytes
• 1 MiB - 1,048,576 bytes
• 1m - 1,048,576 bytes