[ardour.git] / manual / xml / bcf2000.xml

<?xml version="1.0" standalone="no"?>

<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

]>

<section id="sn-bcf2000">
        <title>Using a BCF2000</title>
        <para>
                This will walk you through the process of configuring and using a
                <ulink url="http://www.behringer.com/BCF2000/index.cfm">Behringer BCF2000
                MIDI control surface</ulink> , or BCF, with Ardour. This should also work
                with the
                <ulink url="http://www.behringer.com/BCR2000/index.cfm">BCR2000</ulink>, but
                has not been tested.
        </para>

        <section id="bcf2000-connecting-device">
                <title>Connecting Device</title>
                <para>
                        It's assumed that your USB ports are functional under Linux. The easiest
                        way to tell if you've got a functional link is to simply connect the
                        BCF2000 to your computer with a USB cable, connect the power, and turn it
                        on. You should see the USB MODE light come on in the upper right corner of
                        the BCF. If that's not on, you'll need to figure out how to make your
                        <ulink url="http://www.linux-usb.org/">USB port work under Linux.</ulink>
                </para>

                <para>
                        If the USB MODE light is on, doublecheck that Linux knows of the device.
                </para>
<screen>
xtc:~% aconnect -o
client 64: 'M Audio Delta 1010 MIDI - Rawmidi 0' [type=kernel]
   0 'M Audio Delta 1010 MIDI'
client 72: 'BCF2000 - Rawmidi 1' [type=kernel]
   0 'BCF2000 MIDI 1  '
</screen>
        </section>

        <section id="updating-firmware">
                <title> Firmware Updating (v1.07) </title>
                <para>
                        The first thing you're likely to have to do is update the firmware in the
                        unit. This is a relatively painless process.
                </para>
                <orderedlist>
                        <listitem>
                                <para>
                                        Download the firmware from Behringers
                                        <ulink url="http://www.behringer.com/05_support/bc_download/bc_downloads.cfm">downloads
                                        page</ulink>. There will be a
                                        <ulink url="http://www.behringer.com/BCF2000/bcf2000_107.zip">zip
                                        file</ulink> available which should be downloaded. (This example uses
                                        version 1.07 of the firmware, the latest available at the time of this
                                        writing. There may be a newer version available now.)
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        Unzip the file you downloaded. You'll typically extract 2 files, a PDF
                                        file with release notes and an SYX file, which is the firmware update.
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        Find the system device of the BCF
                                </para>
<screen>
xtc:~% cat /proc/asound/cards
0 [M1010          ]: ICE1712 - M Audio Delta 1010
                     M Audio Delta 1010 at 0xdf80, irq 
2 [BCF2000        ]: USB-Audio - BCF2000
                     BEHRINGER BCF2000 at usb-00:1d.1-2, full speed
</screen>
                        </listitem>
                </orderedlist>
                <para>
                        In this case there are 2 devices. The number at the left indicates the card
                        number. The BCF is almost certain, then, to use the device
                        <filename>/dev/snd/midiCnD0</filename> where <emphasis>n</emphasis> is the
                        card number, in this case, 2.
                </para>

                <para>
                        Write the firmware to the BCF with the command
                </para>
<screen>
cat bcf2000_1-07.syx > /dev/snd/midiC2D0        
</screen>
                <caution>
                        <para>
                                Make sure you use the actual device you determined in the previous step
                        </para>
                </caution>

                <para>
                        The BCF display will show a whirling figure-8 animation and count up to 18.
                        Once the whirling stops, you should turn off the BCF, count to 5, then turn
                        it on again. You should then see the version number of the upgraded
                        firmware displayed for a few seconds as the BCF starts.
                </para>
        </section>

        <section id="bcf2000-connecting-to-ardour">
                <title> Connecting to Ardour </title>
                <para>
                        After starting Ardour, it's important to connect the MIDI device ports of
                        Ardour and the BCF together so that they will communicate with each other.
                        There are a few ways to do this.
                </para>

                <section id="bcf2000-connecting-with-qjackctl">
                        <title> With qjackctl </title>
                        <para>
                                If you use the program <application>qjackctl</application> to control
                                JACK, there's an easy way to connect Ardour to the BCF. Run qjackctl, and
                                click on the <guibutton>Connect</guibutton> button in the main qjackctl
                                window. This will bring up the Connection window. You should see at least
                                2 items listed, the BCF and Ardour:
                        </para>
                        <mediaobject>
                                <imageobject>
                                        <imagedata fileref="images/con1.jpg"/>
                                </imageobject>
                        </mediaobject>
                        <para>
                                Connect the BCF output to the Ardour input, and vice versa:
                        </para>
                        <mediaobject>
                                <imageobject>
                                        <imagedata fileref="images/con2.jpg"/>
                                </imageobject>
                        </mediaobject>
                        <section id="bcf2000-automating-qjackctl-connection">
                                <title> Automating the qjackctl connection </title>
                                <para>
                                        You can set qjackctl to automatically make the MIDI connections (and
                                        others) by using the Patchbay feature in qjackctl. Start qjackctl and
                                        Ardour, and make the MIDI connections as shown above. Click on the
                                        <guibutton>Patchbay</guibutton> button, then click on
                                        <guibutton>New</guibutton>. Qjackctl will ask if you want to create a
                                        patchbay definition as a snapshot of all actual client connections.
                                        Clicking on <guibutton>Yes</guibutton> will bring in a set of all ports
                                        available.
                                </para>
                                <mediaobject>
                                        <imageobject>
                                                <imagedata fileref="images/qjpatch.jpg"/>
                                        </imageobject>
                                </mediaobject>
                                <para>
                                        Make sure you've got both connections as described above, and click
                                        <guibutton>Save...</guibutton> and choose a filename. Once this is saved,
                                        you can close the patchbay.
                                </para>

                                <para>
                                        Next, click on the qjackctl <guibutton>Setup</guibutton> button, then
                                        click on the <guibutton>Options</guibutton> tab.
                                </para>
                                <mediaobject>
                                        <imageobject>
                                                <imagedata fileref="images/qjopts.jpg"/>
                                        </imageobject>
                                </mediaobject>
                                <para>
                                        Click on <guibutton>Activate patchbay persistence</guibutton> and use the
                                        filename you used to save the patchbay above. The patchbay connections
                                        will now be made after qjackctl starts up the clients.
                                </para>
                        </section>
                </section>

                <section id="bcf2000-connecting-from-command-line">
                        <title> From the command line </title>
                        <para>
                                The command <command>aconnect</command>, which is the ALSA sequencer
                                connection manager, can do the job of connecting the BCF to Ardour. First
                                find the numbers of the MIDI device ports for the two:
                        </para>
<screen>
xtc:~% aconnect -o
client 64: 'M Audio Delta 1010 MIDI - Rawmidi 0' [type=kernel]
    0 'M Audio Delta 1010 MIDI'
client 80: 'BCF2000 - Rawmidi 2' [type=kernel]
    0 'BCF2000 MIDI 1  '
client 129: 'ardour' [type=user]
    0 'seq             '
</screen>
                        <para>
                                Here, the BCF is 80, and Ardour is 129. The proper connections can be made
                                between the two with two commands:
                        </para>
<screen>
xtc:~% aconnect 80:0 129:0
xtc:~% aconnect 129:0 80:0
</screen>
                </section>

                <section id="bcf2000-automatic-midi-connection">
                        <title> Automating the MIDI connection from the command line </title>
                        <para>
                                It's sometimes handy to start Ardour from the command line. I found it
                                irritating to have Ardour come up, and then have to manually make the
                                connections for the BCF. This was quickly solved by the following script,
                                which starts Ardour, finds the proper MIDI device ports, and connects
                                them:
                        </para>
<screen>
#!/bin/ksh
# /usr/local/bin/start_ardour.sh
#
# April 17, 2005 - Joe Hartley (jh@brainiac.com)
# A quick script to start Ardour and then make the MIDI connections between
# the BCF2000 and Ardour.

# start Ardour and give it a little time before setting the MIDI connections
nohup /usr/bin/ardour &amp;
sleep 3
  
# Set the IDs - note that they'll both end with a colon
BCF_ID=$(aconnect -o | grep BCF2000 | grep client | awk '{print $2}')
ARD_ID=$(aconnect -o | grep ardour | awk '{print $2}')
  
aconnect "$BCF_ID"0 "$ARD_ID"0
aconnect "$ARD_ID"0 "$BCF_ID"0 
</screen>
                        <para>
                                As an alternative to the patchbay in qjackctl, you could have it run this
                                script to start Ardour and make the MIDI connections. Click the
                                <guibutton>Setup</guibutton> button and choose the
                                <guibutton>Options</guibutton> tab. Enable the <guibutton>Execute script
                                after Startup</guibutton> option, and change the line to call the
                                <filename>start_ardour.sh</filename> script. In this example, I change
                                directories to the drive I record to so new sessions will open there by
                                default before I run the script.
                        </para>
                        <mediaobject>
                                <imageobject>
                                        <imagedata fileref="qjopt.jpg"/>
                                </imageobject>
                        </mediaobject>
                </section>
        </section>

        <section id="bcf2000-programming">
                <title> Programming the BCF2000 for effective use </title>
                <para>
                        One problem that I ran into with the BCF2000 was that none of the factory
                        presets really did what I needed to control Ardour. I had a modest set of
                        things I wanted to use the BCF to control for a track:
                </para>

                <itemizedlist>
                        <listitem>
                                <para>
                                        Volume
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        Panning
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        Mute, solo and rec-enable
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        Transport (play, stop, ffwd, rewind)
                                </para>
                        </listitem>
                </itemizedlist>

                <para>
                        Preset 2 (P2), the Simple Mixer, was almost there, but I could not map the
                        mute, solo and rec-enable controls in Ardour to a pushbutton on the BCF.
                        This was because in P2, the buttons sent a Program Change signal, but
                        Ardour expects a Control Change signal. This required re-programming the
                        BCF a bit. Here's a list of the controls and what I mapped them to send:
                </para>

                <itemizedlist>
                        <listitem>
                                <para>
                                        Rotary knobs 1 through 8, when pressed: CC33 through CC40
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        First row of buttons: CC65 through CC72
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        second row of buttons: CC73 through CC80
                                </para>
                        </listitem>
                </itemizedlist>

                <para>
                        Here's a quick walkthrough to program the controls on the BCF. First we'll
                        do the rotary knobs:
                </para>
                <orderedlist>
                        <listitem>
                                <para>
                                        Hold down the EDIT button and press the rotary control. The display will
                                        show b1.
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        Turn the rotary control labeled "TYPE" until the display reads "CC".
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        Turn the rotary control labeled "PAR" until the display reads "33".
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        Turn the rotary control labeled "MODE" until the display reads "t on".
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        Press the EXIT button.
                                </para>
                        </listitem>
                </orderedlist>
                <para>
                        Continue to program the other rotary controls in the same way, incrementing
                        the value set by the "PAR" control by 1 each time. This will set the CC
                        parameter for the second knob to 34, the third knob to 35, and so on.
                </para>

                <para>
                        The steps are the same for the two rows of pushbuttons under the rotary
                        knobs. The CC values for the first row of buttons run from 65 to 72, and
                        from 73 to 80 for the second row.
                </para>

                <para>
                        Finally, you need to store these changes so that they'll be kept even when
                        the BCF has its power cycled.
                        <orderedlist>
                                <listitem>
                                        <para>
                                                Press the STORE button. Its LED will start to flash.
                                        </para>
                                </listitem>
                                <listitem>
                                        <para>
                                                Select a different preset number if you wish with the left and right
                                                PRESET buttons.
                                        </para>
                                </listitem>
                                <listitem>
                                        <para>
                                                Press STORE again to write the settings to an empty preset. If you want
                                                to overwrite an existing preset, press STORE twice. You can cancel the
                                                store at any time by pressing EXIT.
                                        </para>
                                </listitem>
                        </orderedlist>
                </para>

                <para>
                        Your BCF2000 is now ready to control Ardour!
                </para>

                <section id="bcf2000-preconfigured-preset-file">
                        <title> Preconfigured Preset File </title>
                        <para>
                                Here is a <ulink url="http://zappa.brainiac.com/preset1.syx">saved preset
                                file</ulink>, which has the definitions described above. You can use
                                <command>amidi</command> to load this into the BCF as
                                <xref linkend="bcf2000-loading-a-preset"/>.
                        </para>
                </section>
        </section>

        <section id="bcf2000-mapping-ardour-controls">
                <title> Mapping Ardour controls to the BCF2000 </title>
                <para>
                        The final step to control surface Nirvana is to map the controls in Ardour
                        to the knobs, buttons and faders on the BCF.
                </para>

                <para>
                        Before you can map things properly, you'll need to set the MIDI options
                        within Ardour. In the Editor window of Ardour, choose <menuchoice>
                        <guimenu>Windows</guimenu> <guisubmenu>Options Editor</guisubmenu>
                        </menuchoice>. Make sure the seq device is online, and make sure
                        <guibutton>MTC</guibutton>, <guibutton>MMC</guibutton> and <guibutton>MIDI
                        Parameter Control</guibutton> is set for the seq device. Also make sure
                        that the 4 boxes below are checked:
                </para>

                <itemizedlist>
                        <listitem>
                                <para>
                                        <guibutton>MMC control</guibutton>
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        <guibutton>MIDI parameter control</guibutton>
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        <guibutton>Send MMC</guibutton>
                                </para>
                        </listitem>
                        <listitem>
                                <para>
                                        <guibutton>Send MIDI parameter feedback</guibutton>
                                </para>
                        </listitem>
                </itemizedlist>
                <mediaobject>
                        <imageobject>
                                <imagedata fileref="images/midiopts.jpg"/>
                        </imageobject>
                </mediaobject>
                <para>
                        Now you're ready to do the actual mapping. This is a pretty simple process,
                        all controlled with a <keycombo><keycap>Ctrl</keycap>
                        <mousebutton>Button2</mousebutton> </keycombo> click. This will pop up a
                        little window which says <guilabel>operate MIDI controller now</guilabel>.
                        Simply press the BCF button (or move the slider) that you want to have
                        control the Ardour function.
                </para>

                <section id="bcf2000-example">
                        <title>Example</title>
                        <para>
                                We want to map the Master fader in Ardour to the first slider on the BCF.
                                Hold down the <keycap>Ctrl</keycap> key on your keyboard, and click with
                                <mousebutton>Button2</mousebutton> on the Master fader in Ardour. You
                                should see the <guilabel>operate MIDI controller now</guilabel>. Move the
                                first slider on the BCF up or down a bit. The window should disappear, and
                                you should see the master fader move up and down as you move the slider on
                                the BCF. If that works, move the fader in Ardour with your mouse. You
                                should see the slider on the BCF move up and down in tandem with the
                                Master fader!
                        </para>

                        <para>
                                If the "operate MIDI controller now" window does not go away, there is no
                                connection between Ardour and the BCF. Make sure you've properly connected
                                the two as outlined in the Connecting to Ardour section.
                        </para>
                </section>

                <section id="bcf2000-transport-controls">
                        <title> Transport Controls </title>
                        <para>
                                The 4 buttons in the lower right corner are already mapped in Preset 2 to
                                the MMC transport controls Home (or rewind to the beginning of the
                                session), Fast Forward, Stop and Play, as shown here.
                        </para>
                        <mediaobject>
                                <imageobject>
                                        <imagedata fileref="images/transctls.jpg"/>
                                </imageobject>
                        </mediaobject>
                </section>
        </section>

        <section id="bcf2000-saving-and-loading-presets">
                <title> Saving and Loading Presets </title>
                <para>
                        After beating my head against a wall trying to get various programs that
                        handle SysEx messages to do what I wanted, I realized that once again, the
                        simplest way for me to do this the first time through is from the command
                        line. <glossterm linkend="gt-alsa">ALSA</glossterm> provides the perfect
                        tool for saving and loading files: <command>amidi</command>
                </para>

                <para>
                        First, use <command>amidi</command> to list the available ports:
                </para>
<screen>
xtc:~% amidi -l
Device    Name
hw:0,0    M Audio Delta 1010 MIDI
hw:2,0,0  BCF2000 MIDI 1
</screen>
                <para>
                        There's the BCF, at port hw:2 (we can ignore everything after the first
                        number after the colon). We'll tell amidi to use this port with the -p
                        option
                </para>

                <section id="bcf2000-saving-a-preset">
                        <title> Saving a Preset </title>
                        <para>
                                There's 2 parts to saving a preset: telling the BCF to send the data, and
                                telling the computer to accept it.
                        </para>

                        <section id="bcf2000-recieving-the-data">
                                <title> Receiving the Data </title>
                                <para>
                                        Run <command>amidi</command>, using the <option>-p</option> option to
                                        specify the port, and the <option>-r</option> option to receive the date
                                        into.
                                </para>
<screen>
xtc:~% amidi -p hw:2 -r preset1.syx
</screen>
                                <para>
                                        The system will collect data from the MIDI port now until it's told to
                                        stop with a <keycombo><keycap>Ctrl</keycap><keycap>C</keycap> </keycombo>
                                        so it's time to send some data.
                                </para>
                        </section>

                        <section id="bcf2000-sending-the-data">
                                <title> Sending the Data </title>
                                <para>
                                        To send the MIDI data for the current preset to the computer, hold down
                                        the Edit key on the BCF and press the Store button. They should both stay
                                        lit and the display should read
<screen>
        EG
</screen>
                                        . This is the Global Edit mode.
                                </para>

                                <para>
                                        You can choose whether to send the current preset's data or the data for
                                        all 32 presets by turning the Mode knob, #6, and selecting either
<screen>
        All
</screen>
                                        or
<screen>
        SnGl
</screen>
                                        . When ready to send the data, press knob 6. The display on the BCF will
                                        circle around while it's sending data, and return to
<screen>
        EG
</screen>
                                        when complete. At this point,
                                        <keycombo><keycap>Ctrl</keycap><keycap>C</keycap> </keycombo> out of
                                        amidi. You'll see a report on the amount of data read:
                                </para>
<screen>
xtc:~% amidi -p hw:2 -r preset1.syx
13169 bytes read
 
xtc:~% ls -l preset1.syx 
-rw-r--r--    1 jh       jh          13169 May  1 22:14 preset1.syx
</screen>
                                <para>
                                        The data for the preset is now saved in the file
                                        <filename>preset1.syx</filename>. Press Exit on the BCF to exit the
                                        Global Edit mode.
                                </para>
                        </section>
                </section>

                <section id="bcf2000-loading-a-preset">
                        <title> Loading a Preset </title>
                        <para>
                                Loading a .syx file, such as the one saved above, is very simple. First,
                                select the preset on the BCF to choose the preset to overwrite. Then call
                                <command>amidi</command> using the <option>-s</option> option instead of
                                <option>-r</option> to send a file.
                        </para>
<screen>
xtc:~% amidi -p hw:2 -s preset1.syx
</screen>
                        <para>
                                There will be a quick left-to-right flash of the encoder LEDs along the
                                top of the BCF, followed by the display circling around until the data is
                                loaded. It will then display the preset number again.
                        </para>

                        <para>
                                The preset is now loaded with the settings from the file. They are only
                                active as long as the preset is not changed. If you go to another preset
                                and back to the one you loaded, all the changes will have disappeared. To
                                save the settings,
                        </para>
                        <orderedlist>
                                <listitem>
                                        <para>
                                                Press the STORE button. Its LED will start to flash.
                                        </para>
                                </listitem>
                                <listitem>
                                        <para>
                                                Select a different preset number if you wish with the left and right
                                                PRESET buttons.
                                        </para>
                                </listitem>
                                <listitem>
                                        <para>
                                                Press STORE again to write the settings to an empty preset. If you want
                                                to overwrite an existing preset, press STORE twice. You can cancel the
                                                store at any time by pressing EXIT.
                                        </para>
                                </listitem>
                        </orderedlist>
                </section>
        </section>

        <section id="bcf2000-bcedit">
                <title> Using BCEdit </title>
                <para>
                        The tool provided by Behringer to manage presets and other things on the
                        BCF is the Java program
                        <ulink url="http://www.behringer.com/05_support/bc_download/bc_downloads.cfm">BCEdit</ulink>.
                        This program will start up under Linux provided the correct version of Java
                        is used. I've found that
                        <ulink url="http://java.sun.com/j2se/1.5.0/download.jsp">JRE 5.0 Update
                        2</ulink> starts up correctly, but earlier versions of 5.0 will not.
                        <ulink url="http://behringer-en.custhelp.com/cgi-bin/behringer_en.cfg/php/enduser/std_alp.php?sm=2">The
                        Behringer support page</ulink> says that the "editor software was
                        originally developed under J2SE-1_4_2_05". I tested it with J2RE1.4.2_08
                        and BCEdit started, but was unable to see the BCF when the "Scan" button
                        was pressed. Running under JRE_1.5.0_02, pressing the "Scan" button found
                        the BCF, and I was able to load presets from the BCF to BCEdit, but when I
                        simply renamed the preset and tried to write it back to the BCF, I got a
                        Timeout Error while sending "$rev F1" in the application.
                </para>

                <para>
                        At this point, I don't consider <application>BCEdit</application> to be
                        fully usable under Linux yet.
                </para>
        </section>
<!--
        <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
                href="Some_Subsection.xml" />
        -->
</section>