From 431e4cfc687e315ecfcf93784fbc86bbc48bda2a Mon Sep 17 00:00:00 2001 From: c vw Date: Mon, 27 May 2019 11:57:27 +0200 Subject: [PATCH] User manual for MIDI support --- README.MIDI | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 README.MIDI diff --git a/README.MIDI b/README.MIDI new file mode 100644 index 0000000..4f248df --- /dev/null +++ b/README.MIDI @@ -0,0 +1,168 @@ +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= ACTION= + + where is the Number of the Midi Note + and is the key-word for a SDR "action" (see below) + and 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. -- 2.45.2