Skip to content
Client (PC-software) for Famicom Dumper/Programmer
C# Lua
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Properties
Resources Some new features May 13, 2017
mappers-cs Fixes and clean up of mapper scripts Aug 4, 2019
mappers-lua Support for new COOLBOY version, flash memory info, fixes Aug 25, 2018
.gitignore Support for new COOLBOY version, flash memory info, fixes Aug 25, 2018
CommonHelper.cs Support for new COOLBOY version, flash memory info, fixes Aug 25, 2018
CoolboyWriter.cs Fixed --badsectors option May 12, 2019
CoolgirlWriter.cs Fixed --badsectors option May 12, 2019
FTD2XX_NET.cs Huge update May 17, 2018
FamicomDumperConnection.cs Support for new COOLBOY version, flash memory info, fixes Aug 25, 2018
IMapper.cs
LICENSE Support for new COOLBOY version, flash memory info, fixes Aug 25, 2018
NesFile.cs Some new features May 13, 2017
Program.cs Acceleration disabled for now, typo fix. Sep 27, 2018
README.md Update README.md Aug 26, 2018
TilesExtractor.cs Huge update May 17, 2018
UnifFile.cs Huge update May 17, 2018
famicom-dumper.csproj Last fixes Aug 27, 2018
famicom-dumper.csproj.user New version Nov 14, 2018
packages.config Huge update May 17, 2018

README.md

Client (PC-software) for Famicom Dumper/Programmer

This is the client for the Famicom Dumper/Programmer hardware:

You need Windows and .NET Framework 3.5 but it works fine on *nix using Mono.

Features

It can be used to:

  • Dump Famicom/NES cartridges using C# or Lua scripts to describe any mapper, also it's bundled with scripts for some popular mappers
  • Dump/write battery backed PRG RAM to transfer game saves
  • (Re)write ultra cheap COOLBOY cartridges using both soldering (for old revisions) and soldering-free (new ones) versions, also it supports both COOLBOY (with $600x registers) and COOLBOY2 (with $500x registers)
  • (Re)write COOLGIRL cartridges
  • Test hardware in cartridges
  • Reverse engineer unknown mappers using interactive Lua console

Usage

It's a command-line application.

Usage: famicom-dumper.exe <command> [options]

Available commands:

  • list-mappers - list built in mappers
  • dump - dump cartridge
  • dump-tiles - dump CHR data to PNG file
  • reset - simulate reset (M2 goes low for a second)
  • read-prg-ram - read PRG RAM (battery backed save if exists)
  • write-prg-ram - write PRG RAM
  • write-coolboy-gpio - write COOLBOY cartridge using GPIO
  • write-coolboy-direct - write COOLBOY cartridge directly
  • write-coolgirl - write COOLGIRL cartridge
  • write-eeprom - write EEPROM-based cartridge
  • console - start interactive Lua console
  • test-prg-ram - run PRG RAM test
  • test-chr-ram - run CHR RAM test
  • test-battery - test battery-backed PRG RAM
  • test-prg-ram-coolgirl - run PRG RAM test for COOLGIRL cartridge
  • test-chr-ram-coolgirl - run CHR RAM test for COOLGIRL cartridge
  • test-coolgirl - run all RAM tests for COOLGIRL cartridge
  • test-bads-coolgirl - find bad sectors on COOLGIRL cartridge
  • read-crc-coolgirl - shows CRC checksum for COOLGIRL
  • info-coolboy - show information about COOLBOY's flash memory
  • info-coolgirl - show information about COOLGIRL's flash memory

Available options:

  • --port <com> - serial port of dumper or serial number of FTDI device, default - auto
  • --mapper <mapper> - number, name or path to LUA script of mapper for dumping, default is 0 (NROM)
  • --file <output.nes> - output filename (.nes, .png or .sav)
  • --psize <size> - size of PRG memory to dump, you can use "K" or "M" suffixes
  • --csize <size> - size of CHR memory to dump, you can use "K" or "M" suffixes
  • --luafile "<lua_code>" - execute Lua code from file first
  • --lua "<lua_code>" - execute this Lua code first
  • --unifname <name> - internal ROM name for UNIF dumps
  • --unifauthor <name> - author of dump for UNIF dumps
  • --reset - do reset first
  • --badsectors - comma separated list of bad sectors for COOLBOY/COOLGIRL flashing
  • --sound - play sounds
  • --check - verify COOLBOY/COOLGIRL checksum after writing
  • --lock - write-protect COOLBOY/COOLGIRL sectors after writing

Examples

Dump NROM-cartridge using dumper on port "COM14" to file "game.nes". PRG and CHR sizes are default.

  > famicom-dumper.exe dump --port COM14 --mapper nrom --file game.nes
  PRG reader initialization... OK
  CHR reader initialization... OK
  Using mapper: #0 (NROM)
  Dumping...
  PRG memory size: 32K
  Dumping PRG... OK
  CHR memory size: 8K
  Dumping CHR... OK
  Mirroring: Horizontal (00 00 01 01)
  Saving to game.nes...
  Done in 3 seconds

Dump MMC1-cartridge (iNES mapper #1) using dumper with serial number "A9Z1A0WD". PRG size is 128 kilobytes, CHR size is 128 kilobytes too.

>famicom-dumper.exe dump --port A9Z1A0WD --mapper 1 --psize 128K --csize 128K --file game.nes
PRG reader initialization... OK
CHR reader initialization... OK
Using mapper: #1 (MMC1)
Dumping...
PRG memory size: 128K
Reading PRG bank #0... OK
Reading PRG bank #1... OK
Reading PRG bank #2... OK
Reading PRG bank #3... OK
...

Autodetect FTDI device (port is not specified) by description, simulate reset and dump cartridge using Lua script:

>famicom-dumper.exe dump --mapper mappers-lua\MMC3.lua --reset --psize 128K --csize 128K --file game.nes
Searhing for dumper (FTDI device with name "Famicom Dumper/Programmer")...
Number of FTDI devices: 1

Device Index: 0
Flags: 0
Type: FT_DEVICE_232R
ID: 4036001
Location ID: 62
Serial Number: A9Z1A0WD
Description: Famicom Dumper/Programmer

PRG reader initialization... OK
CHR reader initialization... OK
Reset... OK
Using mapper: #4 (MMC3)
Dumping...
PRG memory size: 128K
Reading PRG banks #0 and #1...
Reading PRG banks #2 and #3...
Reading PRG banks #4 and #5...
Reading PRG banks #6 and #7...
Reading PRG banks #8 and #9...
Reading PRG banks #10 and #11...
...

Dump 32K of PRG and 8K of CHR as simple NROM cartridge but execute Lua script first:

>famicom-dumper.exe dump --port COM14 --mapper 0 --psize 32K --csize 8K --file game.nes --lua "Reset() ; WriteCpu(0x8000, {0x00})"
PRG reader initialization... OK
CHR reader initialization... OK
Executing LUA script...
Reset... OK
CPU write $00 => $8000
Using mapper: #0 (NROM)
Dumping...
PRG memory size: 32K
Dumping PRG... OK
CHR memory size: 8K
Dumping CHR... OK
Mirroring: Horizontal (00 00 01 01)
Saving to game.nes...
Done in 5 seconds

Dump 32MBytes of COOLBOY cartridge using Lua script and save it as UNIF file with some extra info:

>famicom-dumper.exe dump --port COM14 --mapper mappers-lua\coolboy.lua --psize 32M --file coolboy.unf --unifname "COOLBOY 400-IN-1" --unifauthor "John Smith"
PRG reader initialization... OK
CHR reader initialization... OK
Using mapper: COOLBOY
Dumping...
PRG memory size: 32768K
Reading PRG banks #0/0 and #0/1...
Reading PRG banks #0/2 and #0/3...
Reading PRG banks #0/4 and #0/5...

Read battery-backed save from MMC1 cartridge:

>famicom-dumper.exe read-prg-ram --port COM14 --mapper mmc1 --file "zelda.sav"
PRG reader initialization... OK
CHR reader initialization... OK
Using mapper: #1 (MMC1)
Reading PRG-RAM...
Done in 2 seconds

Write battery-backed save back to MMC1 cartridge:

>famicom-dumper.exe write-prg-ram --port COM14 --mapper mmc1 --file "zelda_hacked.sav"
PRG reader initialization... OK
CHR reader initialization... OK
Using mapper: #1 (MMC1)
Writing PRG-RAM... Done in 1 seconds

Rewrite ultracheap chinese COOLBOY cartridge using GPIO pins on /OE-/WE and play sound when it's done:

>famicom-dumper.exe write-coolboy-gpio --port COM14 --file "CoolBoy 400-in-1 (Alt Version, 403 games)(Unl)[U][!].nes" --sound
PRG reader initialization... OK
CHR reader initialization... OK
Reset... OK
Erasing sector... OK
Writing 1/2048 (0%, 00:00:02/00:40:53)...

You need to unsolder pins /OE and /WE and connect them to TCK and TDO pins on JTAG connector.

Same for new COOLBOY where /OE and /WE are connected to mapper, soldering not required:

>famicom-dumper.exe write-coolboy-direct --port COM14 --file "CoolBoy 400-in-1 (Alt Version, 403 games)(Unl)[U][!].nes" --sound
PRG reader initialization... OK
CHR reader initialization... OK
Reset... OK
Erasing sector... OK
Writing 1/2048 (0%, 00:00:02/00:40:53)...

Also you can rewrite COOLGIRL cartridges:

>famicom-dumper.exe write-coolgirl --file multirom.unf --port COM14
PRG reader initialization... OK
CHR reader initialization... OK
Reset... OK
Erasing sector... OK
Writing 1/114 (0%, 00:00:02/00:00:02)... OK
Writing 2/114 (0%, 00:00:02/00:00:02)... OK
Writing 3/114 (1%, 00:00:02/00:00:02)... OK
Writing 4/114 (2%, 00:00:02/00:00:02)... OK
Erasing sector... OK
Writing 5/114 (3%, 00:00:03/00:00:29)... OK

Lua scripting

You can write Lua scripts to add support for more mappers. You must declare those constants:

MapperName = "NROM"

to define mapper name.

DefaultPrgSize = 32 * 1024

and

DefaultChrSize = 8 * 1024

to define default PRG and CHR size.

You need to define mapper number for iNES file:

MapperNumber = 7

or mapper name for UNIF-mappers:

MapperUnifName = "COOLBOY"

Of course you need to declare dumping functions:

function DumpPrg(size)
	print("Reading PRG...")
	ReadAddPrg(0x8000, size)
end

function DumpChr(size)
	print("Reading CHR...")
	ReadAddChr(0x0000, size)
end

And function to enable PRG-RAM, so we can write and read battery-backed saves:

function EnablePrgRam(size)
	WriteCpu(0x8000, {0x80})
	WriteMMC1(0xE000, 0x00)
end

Available functions:

  • ReadPrg(address, length) - read PRG data, returns table of data
  • ReadCpu(address, length) - alias for ReadPrg
  • WriteCpu(address, table_of_data) - write data to CPU bus
  • WritePrg(address, table_of_data) - alias for WriteCpu
  • AddPrg(table_of_data) - add data to dumped PRG
  • AddPrgResult(table_of_data) - alias for AddPrg
  • ReadAddPrg(address, length) - it's like AddPrg(ReadPrg(address, length)) but faster
  • ReadChr(address, length) - read CHR data, returns table of data
  • ReadPpu(address, length) - alias for ReadChr
  • WritePpu(address, table_of_data) - write data to PPU bus
  • WriteChr(address, table_of_data) - alias for WriteChr
  • AddChr(table_of_data) - add data to dumped CHR
  • AddChrResult(table_of_data) - alias for AddChr
  • ReadAddChr(address, length) - it's like AddChr(ReadChr(address, length)) but faster
  • WriteFile(filename, data) - write table of data to file
  • WriteNes(filename, prg, chr, mapper, vertical) - create .nes file using this prg table chr table, mapper number and mirroring (vertical - boolean value)
  • Reset() - simulate reset (M2 goes low for a second)
  • Error(message) - generate exception (stop application with a message)

You can find examples in mappers-lua folder.

Also you can use those functions on command line. This simple command:

>famicom-dumper.exe dump --port COM14 --mapper 0 --psize 32K --csize 8K --file game.nes --lua "Reset() ; WriteCpu(0x8000, {0x00})"

writes $00 to $8000 before dumping.

And finally you can use interactive Lua console:

>famicom-dumper.exe console --port COM14
PRG reader initialization... OK
CHR reader initialization... OK
Executing Lua script myfunctions.lua...
Starting interactive Lua console, type "exit" to exit.
> Reset()
Reset... OK
> prg = ReadCpu(0x8000, 0x8000)
Reading 32768 bytes from CPU:$8000
> print(prg[1])
1
> print(prg[2])
2
> print(prg[3])
4
> WriteCpu(0x8000, {1})
CPU write $01 => $8000
> chr = ReadChr(0x0000, 0x2000)
Reading 8192 bytes from PPU:$0000
> WriteFile("prg.bin", prg)
Writing data to "prg.bin"... OK
> WriteNes("game1.nes", prg, chr, 0, false)
Writing data to NES file "game1.nes" (mapper=0, mirroring=horizontal)... OK
> WriteCpu(0x8001, {2})
CPU write $02 => $8001
> chr = ReadChr(0x0000, 0x2000)
Reading 8192 bytes from PPU:$0000
> WriteNes("game2.nes", prg, chr, 0, true)
Writing data to NES file "game2.nes" (mapper=0, mirroring=vertical)... OK
> p = ReadCpu
> prg = p(0x8000, 0x8000)
Reading 32768 bytes from CPU:$8000
> allp = function() return p(0x8000, 0x8000) end
> prg = allp()
Reading 32768 bytes from CPU:$8000
> w = function() WriteFile("prg.bin", prg) end
> w()
Writing data to "prg.bin"... OK
> dumpprg = function() prg = allp() ; w() end
> dumpprg()
Reading 32768 bytes from CPU:$8000
Writing data to "prg.bin"... OK
>

You can create and use a Lua script file with your own functions:

>famicom-dumper.exe console --port COM14 --luafile myfunctions.lua
PRG reader initialization... OK
CHR reader initialization... OK
Executing Lua script "myfunctions.lua"...
Starting interactive Lua console, type "exit" to exit.
> readprg()
Reading 32768 bytes from CPU:$8000
> readchr()
Reading 8192 bytes from PPU:$0000
> savenes()
Writing data to NES file "game.nes" (mapper=0, mirroring=horizontal)... OK
>

Building

  1. Install packages from NuGet
  2. Build the famicom-dumper.csproj project

Donation

PayPal: clusterrr@clusterrr.com

You can’t perform that action at this time.