
!MidiMan 0.31 (18 Feb 2007) : User Guide
========================================

Document date : 21 Feb 2007


0.0  Contents
     ========
     1  Overview
     2  Iconbar
          Iconbar menu
     3  Front Panel
          Button bar
          Panic Options menu
          Application launching
          Panel menu
     4  Configuration window
          Configuration - Drivers
          Configuration - Parallel
          Configuration - Serial
          Configuration - Routing
          Configuration - MidiMan
     5  Routing window
          Automated routing
          Driver information
     6  MIDI Spy

     Appendices
     ==========
     1  Configuration files

============================================================================

1.0  Overview

     Refer to the '!MidiSupp.!Help' file for an overview of the
     MIDISupport system.

     MidiMan is a front end application, enabling management and
     configuration of the MIDI Support system. It is easily accessed via
     the ROMApps icon on the iconbar.

     It allows the user to load and remove MIDI hardware driver modules
     (from the Drivers section of the Configuration window) and to control
     the flow of MIDI data through the system (from the Routing window).

     It also provides a MIDI Spy window, providing a visual indication of
     MIDI activity, and a Panic button (to restore order to MIDI sound
     generators that have got themselves in a bit of a tizz).

     The current setup (which drivers are installed, the routing, the MIDI
     Spy settings and the Panic options) can be saved to be used as the
     default in subsequent sessions.

     As well as providing access to the main windows, the Front Panel can
     act as a simple application launcher.  The intention is for MidiMan
     to act as the hub of your MIDI universe, from where you launch MIDI
     related applications and set up the routing of MIDI data between
     them.  MidiMan can even automate your preferred routing for each MIDI
     Support compliant application.

     Interactive help is extensively supported - for which BubbleHelp is
     highly recommended.

----------------------------------------------------------------------------

2.0  Iconbar

     Click SELECT to open/surface the Front Panel window.
     Click ADJUST to open/close the Front Panel window.

     Holding the Ctrl key whilst clicking SELECT/ADJUST will
     open/surface/close the Configuration window.

     Using the Shift key acts similarly for the Panel, Routing and MIDI
     Spy windows together, depending on the state of the Panel window.
     If the Panel window is closed, then all three windows will be opened,
     otherwise any that are open will be closed.

     Click MENU to open the iconbar menu.

2.1  Iconbar menu

     * Info : The usual.  Note that the window's toggle size icon may be
         used to reveal the version numbers for the currently installed
         MIDI and MIDISupport modules.

     * Config ... : Opens the Configuration window.

     * Help : Loads either the Text or HTML version of this file.

     * Re-scan : This should be redundant as MidiMan monitors the loading
         and removal of drivers and any routing changes, though it has
         been retained 'just in case'.

     * Quit : The usual.

----------------------------------------------------------------------------

3.0  Front Panel

     This is split into 2 sections, the upper button bar and the lower
     filer-like plug-in/application launcher.

3.1  Button bar

     For the first 3 buttons :
       Click SELECT to open/surface the associated window,
       Click ADJUST to open/close the associated window.

     1) Configure : Open/surface/close the Configuration window.

     2) Routing : Open/surface/close the Routing window.

     3) MIDI Spy : Open/surface/close the MIDI Spy window.

     4) Panic : This is to be used to (eg) silence 'hanging notes'.

          Click MENU on the Panic button to popup a menu of Panic options.

          Click SELECT or ADJUST to send MIDI commands (as defined in the
            Panic options menu) to all currently installed receive-capable
            drivers.

            If none of the Panic menu items are currently ticked, then
            clicking SELECT or ADJUST on the Panic button will, instead of
            doing nothing, open the Panic options menu.

3.2  Panic Options menu

     This determines which messages will be sent when the Panic button is
     clicked on.

     * All Notes Off : If ticked, send an 'All notes Off' message
         (controller 123) on each of the 16 MIDI channels.

     * Individual Note Offs : If ticked, send a 'Note Off' message for
         each note (0-127) on each MIDI channel.

         NB.
           This comprises about 6k of MIDI data.  To help prevent over-run
           at the MIDI INs of any connected devices, the data is sent out
           in bursts (all 128 notes on one MIDI channel) with a wait delay
           of 2 csecs between bursts.

     * Reset All Controllers : If ticked, send a 'Reset All Controllers'
         message (controller 121) on each MIDI channel.

     * MIDI Reset : If ticked, send a 'MIDI Reset' system realtime
         message.

     * XG Reset : If ticked, send a 'XG System On' system exclusive
         message.

     Your preferred 'panic level' can be set from the MidiMan section of
     the Configuration window.

3.3  Application launching

     The filer-like lower section displays applications which may be
     launched by double-clicking on their icon.  Also in filer-fashion,
     holding down SHIFT whilst double-clicking will open a filer window of
     that application's directory.  If the ADJUST button is used then the
     Panel window will be closed after running/opening the application.

     MidiMan treats applications in two ways :

     * Resident MIDI Support plug-ins :
         These applications live in the '<MIDISupport$Dir>.PlugIns'
         directory.  Any applications saved in this directory will
         automatically be displayed in the Front Panel launcher.

     * Externally referenced applications :
         This is the general purpose application launcher aspect.

         The idea behind this is that MidiMan can serve as a hub for MIDI
         activities in general.  Ie installing/removing drivers, launching
         MIDI applications (such as !Synth, !Player, !MelIDI, etc.),
         making changes to the routing, and just generally fiddling about.

         To include an application in this display, just drag it from a
         filer window to anywhere on the Front Panel.  To remove it, use
         the Panel menu.

         The list of external applications is kept in the file
         '<MIDISupport$Dir>.Choices.MidiApps' (or
         'Choices:ESP.MidiSupp.MidiApps'), and is updated as
         neccessary without user intervention.  See Appendix 1.

3.4  Panel menu

     * Info : The usual, as on the iconbar menu.

     * App '' : If an application in the Panel's lower section is
         highlighted, or if the pointer was over an application when MENU
         was pressed, then the name of the application will appear between
         the apostrophes in this menu item, and a submenu will be
         available, containing the following four options :

         * Run : Run the application.  Same as double-clicking on the
             icon.

         * Help : Runs the application's !Help file if one is present.
             In the absence of a !Help file, this option is faded.

         * Open dir : Opens a filer window for the application.  Same as
             shift-double-clicking on the icon.

         * Remove : Selecting this will remove this application from the
             Front Panel's display.  Don't worry, the application is not
             removed from disc.

             This menu item will be greyed out if the application is
             stored in '!MidiSupp.PlugIns' (ie only externally referenced
             applications can be removed in this way).

----------------------------------------------------------------------------

4.0  Configuration window

     There are five sections to the Configuration window, covering :
       Drivers, Parallel, Serial, Routing, and MidiMan.
     Each is presented via its own window pane.  Use the radio icons on
     the right to select one.

     There are three buttons that relate to all sections :

     * Set : Will apply the settings for all sections (apart from Routing)
         for the current session only.

     * Save : Will act as Set, though additionally saving the settings for
         all five sections, as your preferred default for future sessions.

         ParallelMIDI and SerialMIDI settings (see sections 4.2 and 4.3)
         are saved at the same time as the remaining settings, though in
         separate files, and only if the relevant driver module is
         currently installed.  It is not possible to save just the Serial
         or Parallel configuration files without also saving the main
         (MidiMan) configuration file.  See Appendix 1 for details of the
         various configuration files.

     * Cancel : Restores settings to their state prior to opening the
         Configuration window, and then closes the window.

     Clicking on Set or Save with SELECT will close the window.  Use
     ADJUST if you wish to keep the window open.

     Closing the window in the normal way acts as though Cancel was
     clicked.

4.1  Configuration - Drivers

     This section lists the name and version details for all the MIDI
     hardware driver modules found within your !MidiSupp resource, and
     allows them to be loaded or removed (when ticked, a module will be
     loaded).

     A module is not actually loaded or removed until you click on the
     Configuration window's Set or Save button.

     Various checks are made to ensure the validity of loading a module. 
     The Name and Version fields of those considered invalid are greyed
     out, and loading the disc copy will be prohibited (the precise reason
     is given via Acorn's interactive help system).

     The Parallel and Serial drivers are special in a number of ways :
     * Unlike normal expansion cards, their hardware cannot be
       automatically detected.
     * Each has a number of additional features specific to that driver.
     * Each can be loaded, though inactive (ie not actually installed).

     Consequently they each have their own configuration sections.

     Upon loading either of the Parallel or Serial drivers (ie clicking on
     Set), if AutoStart is not set for that driver, then the Configuration
     window will not be closed and the relevant pane selection radio icon
     text will turn red, indicating that that particular pane should be
     viewed in order to actually start the module.

     The complete list of hardware drivers is (using the names that appear
     in this window) :

       AKA10          Acorn AKA10 expansion card
       AKA16          Acorn AKA16/AKA12 expansion card (*)
       DMI50          ESP (prev Audio Dynamics) DMI50 expansion card (*)
       EagleMIDI      Computer Concepts Eagle expansion card
       LarkMIDI       Computer Concepts Lark expansion card (*)
       MIDIMax        Computer Concepts MidiMax expansion card (*)
       MIDIMaxII      ESP MidiMaxII expansion card (*)
       MidiPod        ACE MidiPod expansion card (*)
       MKA16          Morley MKA16 expansion card (*)
       ParallelMIDI   ESP Parallel Port MIDI interface
       SerialMIDI     ESP Serial Port MIDI interface (*)
       RiscStation_MPU401  RiscStation internal MIDI interface
       Mico_MPU401         Microdigital Mico internal MIDI interface

     They are all suitable for use on 26-bit operating systems, however
     only those marked '*' are suitable for use on 32-bit operating
     systems (ie for use with Iyonix/A9).

4.2  Configuration - Parallel

     This section is only available if the ParallelMIDI module is loaded.
     Otherwise the 'Parallel' radio icon is faded.

     * MIDI filters popup menu : Tick boxes are provided enabling specific
         types of MIDI data to be filtered from the MIDI IN stream.

     * Time clock popup menu : The timing rate and the MIDI code to be
         used as a timing byte, can be specified.

     * Auto start : When ticked, the driver will automatically be
         installed and set up when the module is loaded.

     * Start : If this driver is not set up to Auto-start, then this
         button should be used to install the driver and 'Set' the
         parameters in this pane (only) - ie settings for the other
         configuration sections will not be applied.

     It is recommended that you only have Auto Start set if you always
     have the ParallelMIDI interface connected to your printer port.
     Otherwise configure it to be loaded, though manually install the
     driver only when needed (by clicking on Start).

4.3  Configuration - Serial

     This section is only available if the SerialMIDI module is loaded.
     Otherwise the 'Serial' radio icon is faded.

     * Serial device popup menu : You need to specify the type of serial
         MIDI device that you are using : Yamaha MU10 or Portman.

     * MIDI Thru : When ticked, any MIDI data appearing at the Serial IN
         port will be passed on to its OUT port.

     * Auto start : When ticked, the driver will automatically be
         installed and set up when the module is loaded.

     * Start : If this driver is not set up to Auto-start, then this
         button should be used to install the driver and 'Set' the
         parameters in this pane (only) - ie settings for the other
         configuration sections will not be applied.

4.4  Configuration - Routing

     This section lists all of the routing links as currently set up in
     the main Routing window, PLUS any other connections that are
     mentioned in the MidiMan configuration file (loaded at run time). 
     You can toggle whether or not to include each connection prior to
     (re)saving the configuration file.

     Whereas the other Configuration sections affect the current setup,
     changes made in the Routing section apply only to the saved MidiMan
     configuration file.  Changes made in this section do not affect the
     current routing.  Thus the Set button has no effect re this section.

     Any changes made in the main Routing window, whilst this
     configuration section is open, will be reflected here.

     The driver names in this list are coloured, thus :
     * Blue  : A currently active link that is also mentioned in the
               configuration file.
     * Green : A currently active link that is not mentioned in the
               configuration file.
     * Red   : Not a currently active link, but it is mentioned in the
               configuration file.

     Clicking on the arrow between the two driver names will toggle
     whether or not details of this connection will be included in the
     configuration file (when it is saved) :
       Orange = include.
       Grey   = don't include.

     Upon opening the Configuration window, the list of connections in the
     Routing pane are all initially tagged for saving (orange arrow), so
     none of the 'links' will be lost as a result of opening the
     Configuration window, making changes in any of the other sections
     (Drivers, Parallel, Serial, MidiMan) and then saving.

     Being able to retain connections that are not currently active (ie
     those labled with red text) means that you won't lose connection
     details involving drivers that aren't currently installed (unless you
     choose to).

     Thus routing details can be added to the configuration file in an
     incremental fashion.  In time, the configuration file will contain
     preferred connection details for ALL of the user's MIDISupport-aware
     applications.  MidiMan will then automatically set up your preferred
     connections as these applications come and go.


4.5  Configuration - MidiMan

     This contains front-end (ie MidiMan) related settings, ie MIDI Spy
     options, Panic options, and Routing window options :

     * MIDI Spy options : These duplicate the buttons available in the
         MIDI Spy window, and allow you to set your preferred settings.

     * Panic options : These duplicate the entries from the Panic menu,
         allowing you to set your preferred 'panic level'.

     * Routing window options : These allow you to toggle Auto Popups
         on/off, and to specify the maximum size to which the Routing
         window will automatically grow.

----------------------------------------------------------------------------

5.0  Routing window

     This lists all the MIDI drivers currently installed, and allows the
     user to alter the routing between them and thus direct the flow of
     MIDI data through the system.  It is automatically kept current as
     drivers are installed / removed (whether by MidiMan or by other
     applications coming and going).

     Initially this window may appear to be a little confusing, though
     basically the middle Name and 'i' (Info) columns list each driver
     currently installed, with icons to the left relating to sources and
     those to the right relating to destinations for each driver.

     The icons in each row, from left to right :

     * Source driver popup menu : This allows the user to connect the
         output of other drivers to this one's input.  When clicked, it
         pops up a menu of all drivers which are able to send data.  Those
         already connected are shown ticked.  Selecting an item from this
         menu will toggle whether or not that driver will send data to
         this one.

         The popup icon will be faded if this driver is not able to
         receive data.

     * Source links : This shows the number of drivers connected to this
         driver's input (ie the number of Source drivers).

     * From arrow : This arrow will be blue if this driver is able to
         receive MIDI data.  Otherwise it will be grey.

         If the Auto Popups option is on (see the MidiMan section of the
         Configuration window), then if this icon is not grey, and if
         there are currently one or more sources, then when the pointer is
         placed over this arrow a window is momentarily popped up, listing
         the connected source drivers.

     * Name : This field shows the driver's name.  All the other icons on
         the same row in this window relate to this driver.

     * Info : Clicking on this will open/surface/close the Driver Info
         window (see section 5.2, below).
           Click SELECT to open/surface the window,
           Click ADJUST to open/close the window.

         When the Driver Info window is open, the appropriate 'i' icon
         turns red to indicate which driver the Info window relates to.

     * To arrow : This arrow will be green if this driver is able to send
         MIDI data.  Otherwise it will be grey.

         If the Auto Popups option is on (see the MidiMan section of the
         Configuration window), then if this icon is not grey, and if
         there are currently one or more destinations, then when the
         pointer is placed over this arrow a window is momentarily popped
         up, listing the connected destination drivers.

     * Destination links : This shows the number of drivers that this
         driver's output is connected to (ie the number of Destination
         drivers).

     * Destination driver popup menu : This allows the user to connect
         this driver's output to the input of others.  When clicked, it
         pops up a menu of all drivers which are able to receive data. 
         Those already connected are shown ticked.  Selecting an item from
         this menu will toggle whether or not that driver will receive
         data from this one.

         The popup icon will be faded if this driver is not able to send
         data.

5.1  Automated routing

     MidiMan keeps a copy in RAM of the driver connection details
     mentioned in the MidiMan configuration file.  Whenever it detects a
     driver being installed, it automatically makes any connections
     involving this new driver that are mentioned in the configuration
     file.

5.2  Driver information

     This window is opened by clicking on one of the blue 'i' icons in the
     Routing window.

     It shows version (number and date) and flag information for a driver
     (eg whether this driver can send and/or receive data).

     It is closed automatically whenever the Routing window is closed.

----------------------------------------------------------------------------

6.0  MIDI Spy

     The main part of this window comprises a VU meter type display of
     channel based MIDI data that is being transmitted by the specified
     driver(s).

     * Source driver popup menu : This allows the user to specify which
         driver outputs are to be spied upon.  When clicked, it pops up a
         menu of all send-capable drivers.  Those already connected to
         MIDI Spy are shown ticked.  Selecting an item from this menu will
         toggle whether that driver's output is spied upon.

     * SysEx message activity LED (red) : Illuminates briefly when a
       system exclusive message is detected.  Note that it does not remain
       illuminated for the duration of the sysex message - it just flashes
       briefly when such a message starts.

     * System message activity LED (green) : Illuminates briefly when any
       system realtime or system common messages are detected.

     Note that the window's toggle size icon (top right corner) should be
     used to reveal the following 3 icons at the bottom of the window :

     * Density : When selected, the display will indicate the amount of
         all channel-related data (NoteOns, Controllers, PitchBend, etc).

     * Notes : When selected, the display will show the NoteOn velocity
         values (analogous to how hard a note was played).

     * Decay : When ticked, the display will be less instantaneous, as the
         bars decay more slowly.  This gives the user more chance to see
         the levels involved, particularly when in Notes mode.

     Your preferred settings for Density/Notes and Decay On/Off can be
     defined from the MidiMan section of the Configuration window, the
     details being saved in the MidiMan configuration file along with
     installed drivers and routing details.

============================================================================

A.1  Configuration files

     There are a total of four configuration files - MidiMan, Parallel,
     Serial and MidiApps.  They are all plain Text files, so are easily
     readable.  However, the user is advised not to edit them manually.

     They are stored in the 'new boot' Choices if available, otherwise
     within the !MidiSupp resource.

     * MidiMan :

       This is the main MIDI Support configuration file, containing
       settings from the Drivers, Routing and MidiMan sections of the
       Configuration window.

       This file is located in either :

         <MIDISupport$Dir>.Choices.MidiMan       (if new boot not present)
         <Choices$Write>.ESP.MidiSupp.MidiMan    (if new boot is present)

     * Parallel :

       This file contains settings from the Parallel section of the
       Configuration window, ie specifically for the Parallel Port MIDI
       interface.  It is saved only if the ParallelMIDI driver is
       installed.

       This file is located in either :

         <MIDISupport$Dir>.Choices.Parallel      (if new boot not present)
         <Choices$Write>.ESP.MidiSupp.Parallel   (if new boot is present)

     * Serial :

       This file contains settings from the Serial section of the
       Configuration window, ie specifically for the Serial MIDI
       interface.  It is saved only if the SerialMIDI driver is installed.

       This file is located in either :

         <MIDISupport$Dir>.Choices.Serial        (if new boot not present)
         <Choices$Write>.ESP.MidiSupp.Serial     (if new boot is present)

     NB.
       It should be noted that although these 3 configuration files are
       saved from MidiMan, they are also made use of by MidiSupp, when
       that is run (which will generally be as part of your main boot
       sequence).  Ie upon a system boot, MidiSupp sets up the MIDI system
       as previously specified using MidiMan.

     * MidiApps :

       This file contains the full pathnames of applications that are to
       appear in the Panel window's launcher.  It is saved by MidiMan
       whenever the list of external applications changes (ie when
       dragging an application to the Panel, or using the Panel menu's
       Remove option).

       This file is located in either :

         <MIDISupport$Dir>.Choices.MidiApps      (if new boot not present)
         <Choices$Write>.ESP.MidiSupp.MidiApps   (if new boot is present)

============================================================================
