--- /dev/null
+MIDI support in piHPSDR - Manual for Users
+==========================================
+
+
+To use MIDI devices in piHPSDR, you must provide a file "midi.inp" that resides
+in the current working dir of piHPSDR (that is, where the "*.props" file and
+the WDSP wisdom files also reside).
+
+A sample midi.inp file for the popular Behringer "CMD PL-1" MIDI console is
+provided as an example. The basic rules for the file are
+
+- the file is line-oriented. Each line contains a directive
+
+- in each line, a "#" sign denotes a comment, that is:
+ a line beginning with a "#" is skipped
+ in all other lines, the "#" and all following characters are skipped.
+
+- the first non-comment line specifies the MIDI device (just in case, when
+ several MIDI controllers are connected to the computer). This line MUST
+ contain the string "DEVICE=", and everything following is treated as the
+ device name (without trailing blanks). Only MIDI devices are accepted whose
+ name starts with the given device name. for example, the line
+
+ DEVICE=CMD PL
+
+ will accept the "CMD PL-1" MIDI controller. Note that events are processed
+ without looking at the channel number. This is so because for the Behringer
+ controller, one can accidentally change the channel number by hitting a key.
+
+- The following lines all must contain one of the strings
+ "KEY=", "CTRL=", or "PITCH=". The syntax is as follows:
+
+ KEY: buttons which generate Note-On/Note-Off MIDI events
+ ========================================================
+
+ The syntay is
+
+ KEY=<nr> ACTION=<action> <modifier>
+
+ where <nr> is the Number of the Midi Note
+ and <action> is the key-word for a SDR "action" (see below)
+ and <modifier> can be omitted, or can be the string "ONOFF".
+ If the "ONOFF" modifier is there, an action is taken both upon
+ Note-On and Note-Off events (usually: when pressing and releasing
+ the button), while otherwise actions are only take upon "Note-on"
+ events.
+ Example without "ONOFF":
+ When using a button for the "TUNE" function, the
+ radio will go "tune" state when hitting the button, and return
+ to normal operation when hitting the button a second time.
+ Example with "ONOFF":
+ When using the same button for the "TUNE" function with the "ONOFF"
+ modifier, the radion will go to "tune" state when pressing the
+ button and return to normal operation when releasing it.
+
+ For example, in the sample file midi.inp you find the line
+
+ KEY=34 ACTION=MOX
+
+ and this means that the "Cue" button of the Behringer controller,
+ whiche generates Note on/off message for Note 34, is used to
+ switch MOX.
+
+ CTRL: MIDI controllers
+ ======================
+
+ Here we must distinguish between controllers that give a value in a
+ fixed range (0-127), and controller that only encode the direction and
+ speed of turning a knob. We will name the first kind of controllers
+ (usually expression pedals, etc.) "knobs" and the second kind "wheels".
+
+ For example, the line
+
+ CTRL=20 ACTION=RFPOWER
+
+ will set the TX drive power, with value 0 for the minimum controller
+ position and the maximum value (100) for the maximum controller
+ position. Note that the Behringer controller has no "knobs", only
+ "wheels".
+
+ Wheels generate values which indicate the direction (left/right) and
+ speed of the rotation. A typical use would be to control the VFO
+ frequency. The description of wheel must contain the key-word "WHEEL"
+ and the critical values for normal/fast/very-fast left/right turns.
+ For example, the line
+
+ CTRL=31 WHEEL THR=59 61 63 65 67 69 ACTION=VFO
+
+ in the sample midi.inp file indicates that the VFO is controlled
+ by a MIDI controller with "note" 31 (this is the big knob for the
+ Behringer controller). The controller values sent by the MIDI
+ hardware are <64 for left turns and >64 for right turns, and the
+ larger the speed of rotation the larger the deviation from 64.
+ The sample line means that the frequency is reduced by 100 VFO-steps
+ if the controller value sent is <= 59, the frequency is reduced by
+ 10 VFO-steps for controller values 59 and 60, and the VFO frequency
+ is reduced by one VFO-step is the controller sends the values 62
+ and 63. Likewise, the thresholds for an increase of the VFO frequency
+ by 1/10/100 VFO-steps are 65, 67, 69.
+ This allows to move from one band edge to the other easily.
+
+ If fast or very-fast motions are not wanted, set the threshold
+ accordingly. For example,
+
+ CTRL=4 WHEEL THR=-1 -1 63 65 128 128 ACTION=AGC
+
+ changes the AGC value by a constant amount for each MIDI message
+ generated, since the controller values are always in the range
+ 0-127 and the threshold for fast and very-fast are never reached.
+
+ PITCH: MIDI PITCH sliders
+ =========================
+
+ Sometimes a MIDI controller features a "pitch" controller. This
+ controller sends values between 0 and 16385. It can be used to
+ control all sorts of "sliders", e.g. TX drive level, AF level,
+ etc. Since there can only be a single pitch controller, the
+ line in file midi.inp is simply
+
+ PITCH ACTION=AFGAIN
+
+ and this means that with the pitch controller, the AF volume
+ is controlled. MIDI pitch controllers are treated as "KNOBS",
+ that is, the same way as MIDI controllers that generate values
+ in a fixed range.
+
+
+LIST OF ACTIONS
+===============
+
+Here is a list of actions implemented. Note that not all actions
+can be used with all sorts of MIDI events. For example, activating
+MOX makes only sense with a button (KEY), while setting the TX
+drive could be used with a knob (CTRL but no WHEEL), with a wheel
+(CTRL with WHEEL), or even with a pitch controller.
+
+Here is a list of actions currently implemented, in alphabetical
+order. We also give for which types of MIDI events (KEY, KNOB,
+WHEEL, PITCH) this action is defined
+
+
+Action Event Explanation
+----------------------------------------------------------------------------------------------
+AFGAIN KNOB,WHEEL AF audio volume
+AGC KNOB,WHEEL AGC level
+ATT KEY cycle through "ALEX attenuator" settings
+ATT KNOB,WHEEL set RX attenuation (0-31dB)
+BANDUP KEY,WHEEL cycle through the bands (upwards)
+BANDDOWN KEY,WHEEL cycle through the bands (downwards)
+COMPRESS KNOB,WHEEL set TX compression level (if compression is activated)
+FILTERUP KEY,WHEEL cycle through the filters (upwards)
+FILTERDOWN KEY,WHEEL cycle through the filster (downwards)
+MICGAIN KNOB,WHEEL MIC gain
+MODEUP KEY,WHEEL cycle through the modes (upwards)
+MODEDOWN KEY,WHEEL cycle through the modes (downwards)
+MOX KEY MOX on/off
+PANHIGH WHEEL change "high" level of current pan-adapter
+PANLOW WHEEL change "bottom" level of current pan-adapter
+PREAMP KEY cycle through preamp settings (only available for CHARLY25 filter boards)
+RITTOGGLE KEY RIT on/off
+RITVAL WHEEL change RIT frequency offset
+RFPOWER KNOB,WHEEL TX power
+SWAPVFO KEY Swap VFO-A/VFO-B
+TUNE KEY Tune on/off
+VFO WHEEL change VFO frequency
+
+
+If you need more or different type of actions, the implementation should be straightforward.
projects / pihpsdr.git / commitdiff