MIDI Adapter Firmware Flashing

The adapter's firmware can be updated over the same USB-C cable you normally use. It takes a couple of minutes. You need a free tool, and which one depends on your computer:

  • Windows — WCHISPTool, free, from the chip maker
  • Mac — wchisp, free and open source

If an update goes wrong, the worst case is that you do it again. See If something goes wrong at the end.

Before you start

  1. The firmware file. A file ending in .bin — for example midi_adapter_0.3.0.0.bin. Save it somewhere you can find again, such as your Downloads folder.
  2. A USB-C cable that carries data. Some cables are charge-only and will not work. If your computer already talks to the adapter with a cable, that cable is fine.
  3. The adapter, unplugged for now.
  4. A spudger or a thin blade to open the case, and somewhere to put three small parts down. The button you need is inside — see the next section.

Opening the case

The button that starts a firmware update is inside the enclosure, so the adapter has to come apart first. It goes back together in a couple of minutes.

Unplug the USB cable before you start.

  1. Unscrew and remove the silver 6.35 mm jack insert from the front.
  2. Prise off the back cover — the USB end — using a spudger or a thin blade.
  3. Carefully remove the PCB from the enclosure.

To reassemble, do the same three steps in reverse.

A few things worth knowing:

  • Take your time with step 2. Work gently round the edge.
  • Hold the board by its edges where you can, and avoid touching the components.
  • The board can be plugged in and used while it is out of the case, which is exactly what you are about to do.

The one thing to understand first

Normally, plugging in the adapter starts its firmware: it appears as a MIDI device and the browser configurator can see it.

To update the firmware, you have to start it in flashing mode instead. There is one way to do that:

Hold the button down, then plug in the USB cable, then let go.

The button has to be held before the cable goes in. Pressing it afterwards does nothing at all.

The button is on the circuit board, so this only works with the case open — see Opening the case above.

In flashing mode the adapter looks like a completely different device to your computer. It will not appear as a MIDI device, and the browser configurator will not see it. That is normal, and it is how you know you did it right.

If you plug in without holding the button, the adapter just starts up as usual. No harm done — unplug it and try again.

Windows

One-off: install WCHISPTool

  1. Go to https://www.wch-ic.com/downloads/WCHISPTool_Setup_exe.html
  2. Download and run the installer, accepting the defaults.
  3. Start WCHISPTool. Depending on the version, the window may be titled WCHISPStudio — it is the same program.

The installer also sets up the USB driver the tool needs, which is why this is the easier route on Windows.

Each time you update

  1. In WCHISPTool, set these three boxes:

    • Chip Series — CH32V20x
    • Chip Model — CH32V203G6U6
    • Download Method (some versions say Interface) — USB

  2. Hold the adapter's button down, plug in the USB cable, then release the button.

  3. The adapter should appear in the tool's USB device list, usually as one entry with a long number. If the list stays empty, see If something goes wrong.

  4. Next to Object File 1 (some versions say Firmware File), click Browse and pick your .bin file.

  5. Click Download.

  6. Wait for the progress bar. You want a green success message — the wording varies, but it will say something like Download Success.

  7. Unplug the adapter, then plug it back in, this time without touching the button. It starts up on the new firmware.

Leave every other setting alone. WCHISPTool can also change protection and configuration options on the chip, and there is no reason to touch any of them here. In particular, never tick anything about read protection.

Mac

This uses Terminal. You can copy and paste every command — you do not need to understand them.

To open Terminal: press Command + Space, type terminal, press Return.

One-off: get wchisp

  1. Go to https://github.com/ch32-rs/wchisp/releases and open the newest release.

  2. Download the Mac build. There may be two — pick the one for your Mac:

    • Apple Silicon (M1, M2, M3, M4 and later) — the file with aarch64 or arm64 in the name
    • Intel — the file with x86_64 in the name

    Not sure which you have? Apple menu, then About This Mac. If it mentions "Apple M", it is Apple Silicon.

  3. Unzip the download by double-clicking it. You get a file called wchisp.

  4. Move wchisp into your Downloads folder, next to the firmware .bin file. Keeping both in one place makes the commands below simpler.

  5. Paste this into Terminal and press Return. It tells macOS the file is allowed to run, which macOS blocks by default for anything downloaded from the internet:

    cd ~/Downloads && chmod +x wchisp && xattr -d com.apple.quarantine wchisp

    If it says there is no such xattr, that is fine — there was nothing to remove.

  6. Check that it runs:

    ./wchisp --version

    A version number means you are ready. If instead it complains about libusb, install that once:

    brew install libusb

    If brew is not found, install Homebrew first using the one-line command on https://brew.sh, then run brew install libusb again.

Each time you update

  1. Hold the adapter's button down, plug in the USB cable, then release the button.

  2. In Terminal:

    cd ~/Downloads
./wchisp probe

    You should see the chip listed, mentioning CH32V203. If it says no device was found, see If something goes wrong.

  3. Flash it. Use these three commands, in this order, replacing the filename with your actual file:

    ./wchisp erase
./wchisp flash -E -R midi_adapter_0.3.0.0.bin
./wchisp reset

    Rather than typing the filename, you can drag the .bin file from Finder into the Terminal window and it will fill in the path for you.

  4. The second command should finish by saying it verified successfully. The third starts the new firmware.

Do not use wchisp flash on its own

wchisp's own documentation shows wchisp flash yourfile.bin as the normal way to use it. On this chip that command works once and then locks itself out. Every later attempt fails with a read protection error.

The reason: its built-in erase clears a protection setting on the chip and never puts it back. The three commands above avoid that — erase as a separate step, then flash with -E, which means "do not erase again".

If you have already run into this, it is recoverable. See the table below.

Checking it worked

Plug the adapter in normally, without holding the button, and open the browser configurator. The firmware version is shown at the top right of the device panel, and that number should have changed.

Your settings — mode, CC number, calibration, ranges, thresholds — are kept across an update.

If something goes wrong

Each of these is the symptom first, then what it means and what to do.

  • The device list is empty, or "no device found." The adapter started its normal firmware instead of flashing mode. Unplug it, hold the button down first, plug in while still holding, then release.
  • The adapter appears as a MIDI device. Same thing — it is running normally rather than in flashing mode. As above.
  • Nothing happens at all when you plug it in. Most likely a charge-only cable, or a dead USB port. Try the cable you normally use with the adapter, and a different port.
  • "Read protection is enabled", or erase fails (Mac). wchisp flash was used on its own at some point. Run ./wchisp config unprotect — but read the next section first, because the adapter will go completely quiet and that is meant to happen.
  • Flashing failed part way through. The write was interrupted. Unplug the adapter completely, then start again from the beginning. A reset is not enough here; it has to lose power.
  • It flashed, but the adapter does nothing afterwards. The new firmware may not have started. Unplug and plug back in without the button. If it still does nothing, flash it again.

Recovering from "read protection is enabled"

This is the one repair that looks worse than it is, so here is what to expect.

./wchisp config unprotect wipes the adapter completely and restarts it. Because there is now no firmware on it, the adapter will disappear from your computer entirely — no MIDI device, no flashing mode, nothing. That is exactly what should happen. It is not broken.

Then:

  1. Unplug the adapter.

  2. Hold the button down, plug in the USB cable, then release the button — the usual way into flashing mode.

  3. Check it is there with ./wchisp probe.

  4. Flash as normal:

    ./wchisp erase
./wchisp flash -E -R midi_adapter_0.3.0.0.bin
./wchisp reset

The adapter comes back to life at the last command. Your settings are lost in this case — the wipe takes them with it — so mode, CC number and calibration will need setting again in the configurator.

None of these is permanent. As long as you can get the adapter into flashing mode — button held, then plug in — you can always put working firmware back on it.