KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #codex #ai-agents #claude-code #dsh #dsh-plugin #cli #macos #ai-agent #deepseek-harness #open-source

katana-midi-bridge

★ 89 Open GitHub ↗

Provides enhanced MIDI control capability to Boss Katana (tm) guitar amplifiers

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# katana-midi-bridge

# Introduction

The Katana (tm) amplifier responds to only a few MIDI program and
controller (PC and CC) messages. But dig a bit deeper and you'll
discover a rich sysex API on par with other Roland/Boss products like
the GT-100 guitar processor.  Roland has not made the Katana spec
public, but I was able to reverse-engineer and document a large
portion of it by observing USB communication between Boss Tone Studio
and the amplifier.

This program has three goals:

1. Make use of the sysex API to provide an almost unlimited number
     of user-defined presets beyond the five built in to the
     amplifier.

2. Make internal ("deep") parameters accessible through standard CC
     messages.

3. Permit communication from 5-pin MIDI to the Katana combo amps
     (also requires a low-cost USB/MIDI converter).

The software is written in Python, a powerful cross-platform scripting
language. I use a Ubuntu Precise desktop machine for primary
development but routinely test on Raspberry Pi and Beagelbone embedded
computers to ensure these remain viable deployment targets.

(Due to occasional issues with USB on the RPi I am recommending the
BBG for live performance use)

Special thanks to:

+ Robert Fransson (Codesmart) of Primova Sound for feedback,
  encouragement and general programming wizardry.

+ All the regulars on VGuitar Forum for providing positive energy,
  enthusiasm and concrete suggestions. In particular I salute Colin
  Willcocks (Gumtown) and Robin Van Boven (Beanow) for their
  invaluable contributions to Katana reverse-engineering.  And, as
  always, Steve Conrad (Elantric) for providing the most valuable
  forum on Earth for musical propellor-heads.

## For the non-techies

I have written a Wiki page here:

https://github.com/snhirsch/katana-midi-bridge/wiki/Install

that attempts a detailed walk-through of the installation process on
Raspberry Pi or Beaglebone.  It's hard to know what level of detail to
hit and suggestions or comments would be appreciated if I've omitted
or glossed over something critical.

# Status

New:

+ Preset capture/restore now preserves all relevant settings in the
    "patch data" area. This is a superset of what's available on the
    front panel, so knobs and color buttons are no longer directly
    captured.

Rationale:

Katana has numerous capabilities beyond what's exposed in the Boss
    Tone Studio or reachable from panel knobs. It's incredibly
    difficult to get sensible interaction between physical controls
    and a recalled patch, so for now I'm not even going to try.

+ The bridge now interrupts audio output in a distinctive pattern to
  acknowledge patch capture.  The previous approach of cycling the amp
  model LEDs was slow and resulted in undesirable side-effects.  This
  is discussed in more detail below.

The bridge software stores patches outside the amplifier and can
recall them upon receipt of a MIDI PC command.

Mapping of CC values is very limited at this point.  Robert Fransson
(Codesmart) and I have worked out a full specification that maps CC#
to almost all functions in the amplifier.  He has completely
implemented this in the Primova Sound MIDX-20 product.  I fully
intend to do the same in my code as time permits.

At this point, the only CC# mapping is:

CC# 70 (0-127) --> Amplifier Volume (0-100)

Previous versions of this application tied the MIDI volume controller
to the amplifier volume and used a complex approach to ensure pedal
toe-down never exceeded the setting at capture time.  CC# 70 in this
release is tied to the internal volume pedal controller where it
inherently behaves in the desired manner (this is what a volume pedal
connected to the GA-FC footswitch acts upon).

The vendor defined MIDI API is supported and will operate without any
change in behavior.

### IMPORTANT: Backwards Compatibility

If you wish to keep patches produced by earlier versions of this
program they must be converted to the new format using the
'katana_convert' program.  It may be run on a desktop PC or the
embedded computer you're using for performance (Beaglebone or RPi).

Install the new software first, then:

1. If running on your performance rig, disconnect the MIDI
  controller to ensure the bridge is not running.

2. Connect the amplifier

3. Determine the amplifier MIDI interface using the same method as
  during initial installation.  See Wiki for details.

4. Run the conversion (your parms may vary):

katana_convert "KATANA:KATANA MIDI 1 20:0" 1 <old_file> <new_file>

Where 'old_file' is the path of the existing patch file (usually
  /home/katana-user/preset.data) and 'new_file' is where you want to
  save the converted output.  Do not use the same name for both!

5. After the conversion runs, save a copy of the old file for
  safety, rename the new file to 'preset.data' and copy it into the
  /home/katana-user directory.

# High-Level Overview of Installation

(See Wiki for step-by-step instructions)
  
## Prerequisites

+ For Ubuntu Precise or Debian Jessie the following packages must be
    present.  Install this first set with 'apt-get':

- libasound2
    - librtmidi-dev
    - libusb-1.0-0-dev
    - libjack0 (Precise) 
    - libjackQ (Jessie)
    - at
    - python3
    - python3-dev
    - python3-pip

+ Then, use 'pip3' to install a couple of Python native modules:
```
$ pip3 install pyusb
$ pip3 install python-rtmidi
$ pip3 install mido
```
Would appreciate feedback on requirements for other distributions.

## Configuration

1. Update ```60-controller.rules``` with the USB VID (vendor id) and PID
(product id) of your controller.  This edit affects (2) lines.

2. Update ```50-katan.rules``` with the USB VID (vendor id) and PID
(product id) of your amp.  This requirement will go away once I learn the 
USB product ids for all Katana models

3. Edit ```katana_bridge_start``` to set values marked as user
edits.  In addition to setting the USB vender and device id, you need
to specify which MIDI channel to listen on and provide a couple of
strings to help the program find the MIDI interface.

## Installation

Run the ```install.sh``` script as root

## Communication Test

First, ensure that your controller is on and connected to the Katana
bridge computer. Then, connect the amp to that computer. If you have
configured everything correctly, the bridge will start automatically.

Wait about ten seconds for the software to initialize.

Check basic operation by sending PC# 1-5 while watching the "Tone
Settings" LEDs, which should change accordingly.  If you have a volume
control or pedal mapped to CC# 70, check to see if it is able to vary
the amplifier volume.  If the amp does not react, see section on
troubleshooting below.

When either the amp or controller is disconnected (or shut off), the
bridge will automatically be stopped.

## Use

To capture and store a user preset, start by dialing in a sound to
your liking.  This might involve connecting the amp to Boss Tone
Studio or Gumtown's Katana FxFloorboard application (required if you
want access to hidden settings). After you setup a tone to your
liking the next step depends on which application was used:

If you were connected to FxFloorboard (recommended), check the
rectangular "Connect" button at the top of the window.  If it is
illuminated in green, toggle the connection state off by clicking on
the button.

If you used BTS, exit that program by closing the window.

**IMPORTANT**: Physically disconnecting without taking one of these
steps leaves the amplifier in "edit" mode. If reconnected to USB while
in that mode it discards your carefully crafted patch and restores the
current preset or panel state. In other words, you lose all your work.

Disconnect the amp from the computer and plug it into the device where
you've installed Katana bridge. Wait about ten seconds for the program
to start.

Arm the bridge for settings capture by sending three messages in this
format:

CC#: 3 - Value: 127

within a two second period.  Then strike and hold a chord and select a
program number in the range 11..127 where you would like to store your
settings. The bridge will read and save the patch data and pulse the
volume to acknowledge. This information is permanently saved and can
be recalled instantly by re-selecting the PC#.

If you change your mind after arming the bridge send any other CC
message to cancel.

I have the last preset on my Behringer FCB-1010 controller setup to
issue the CC3 command on a momentary basis.  When I want to capture a
setting, I tap this three times quickly then page through the banks
and press the preset where I wish to save.  This technique should be
possible with other floor controllers.

## In case of difficulty

Check the system logs (/var/log/syslog and /var/log/messages) to see
if the amp and controller were detected.  The bridge code will not
start until they're both seen.

Check the mail spool file for 'root' to see if any exceptions or error
messages are present.

RPi and BBG are a bit fussy about enumeration of new USB devices. If
you are not getting proper communication, try replugging both the amp
and MIDI controller **after** those devices are powered up.

I've had success using a passive USB hub with the single USB on the
BBG, but YMMV since most USB<->5Pin MIDI converters draw some degree
of bus power.  A powered hub might be necessary in some situations.

If all else fails, open an issue here and I'll try to help.  Please
describe as much as you can about your environment and what you have
tried.

katana-midi-bridge

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README