+++ /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.
-
-- 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> CHAN=<chan> ACTION=<action> <modifier>
-
- where <nr> is the Number of the Midi Note, <chan> is the MIDI
- channel where the event is expected.
-
- The key words with the line can be given in any order. If
- CHAN= is omitted, MIDI events from any channel are accepted.
-
- <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.
-
- For wheels, there can be an additional directive DELAY=<delay>,
- if this is given, it specifies a delay time (in msec) in which no
- further WHEEL event is processed. If a wheel is used, for example,
- to cycle through the filter settings, a delay takes care that this
- does not go too fast.
-
- 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) this action is defined. We further have a "dummy" action
-NONE which means that there is nothing to do.
-
-
-Action Event Explanation
-----------------------------------------------------------------------------------------------
-AFGAIN KNOB,WHEEL AF audio volume
-AGC KNOB,WHEEL AGC level
-AGCATTACK KEY cycle through AGC settings (fast/slow, etc.)
-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
-CTUN KEY toggle CTUN mode
-FILTERUP KEY,WHEEL cycle through the filters (upwards)
-FILTERDOWN KEY,WHEEL cycle through the filster (downwards)
-LOCK KEY lock VFO(s)
-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
-NB KEY cycle through NoiseBlanker settings
-NR KEY cycle through NoiseReduction settings
-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)
-PURESIGNAL KEY toggle PURESIGNAL (on/off)
-RITCLEAR KEY clear RIT frequency
-RITVAL WHEEL change RIT frequency offset
-RFPOWER KNOB,WHEEL TX power
-SPLIT KEY toggle Split mode
-SWAPVFO KEY Swap VFO-A/VFO-B
-TUNE KEY Tune on/off
-VFO WHEEL change VFO frequency
-VFOA2B KEY frequency VFO A -> VFO B
-VFOB2A KEY frequency VFO B -> VFO A
-VOX KEY toggle VOX (on/off)
-
-
-If you need more or different type of actions, the implementation should be straightforward.
projects / pihpsdr.git / commitdiff