Ctrlr
=====

A Ctrlr (http://hyperglitch.com/articles/ctrlr)  driver and editor for Linux.

Author: Igor Brkic <igor@hyperglitch.com>


Introduction
------------
Ctrlr is a DIY MIDI controller based on Arduino. It consists from main device with
few keys and knobs and footboard with more keys. All controlls can be binded to
arbitrary number of MIDI messages. 


Setting up
----------
Ctrlr depends on PyQt4, PySerial and alsaseq. PyQt4 and PySerial are probably in your
distribution's repository. alsaseq (at least on Arch Linux) is not so you'll
probably need to compile it from source (it can be found at http://pp.com.mx/python/alsaseq/)

After the dependencies are met, you'll maybe need to set some program options. These
are at the top of the ctrlr file. Basically, only thing that you maybe need to
change is the port (under global_configuration). Other thing you may want to change is
option called 'parser_mark_style'. If this is set to 'mark', after code verification
correct lines will have green check mark next to it and incorrect will have red cross.
If this option is set to 'color', then correct lines will be colored green and 
incorrect red.


User interface
--------------
Main GUI of Ctrlr is written using Qt4 toolkit. It consists of two parts: left with
controlls and right with current bank and tools for loading and saving configurations.

Each control shows its current state (knob position or key status) and has one or
more text boxes for commands. Keys have two command boxes: list of events for key press
and list of events for key release. Keys also have a "toggle" checkbox for using
keys as a toggle switches (one press executes 'press' code and another 'release' code).

Pressing 'Update' button in the right part checks the validity of written commands and,
if everything is correct, enables 'Save configuration' button. If there are errors
message will be written to Log (bottom right part of the interface).

Each configuration consists of two 'banks' which can be switched by using bank switch
key on the device or by pressing 'Bank switch' button.

If there is a configuration named default.ctrlr in the current directory, it will be
automatically loaded at startup.


There are two other user interfaces: minimal and CLI. Minimal interface will not
show knobs and keys in realtime and it will also occupy a little less space on screen.

CLI interface will not create GUI window. It will load wanted configuration and
run everything in background. Command line currently supports only commands for
quitting and loading new configuration file. To exit program type 'quit' and to
load new config type 'load <path_to_config_file>' where you can leave out .ctrlr
extension. In the of the future versions there will be (at least I hope so) also
commands to check and/or change code for each control.


Command line arguments
----------------------
Running Ctrlr without any command line arguments will start it in default Qt4 GUI.
Adding --minimal or --nogui will start it in minimal and CLI mode, respectively.

When running in CLI mode you can add aditional path to configuration file to load
at startup (you don't need to type .ctrlr extension).


Syntax and examples
-------------------

Keys can send PC, CC and note on/off messages. Aditionally, there is 'panic' command
which will send AllSoundOff, AllNotesOff and Sustain Off on all channels. Knobs can
currently send only CC messages. 

Every field can hold as many lines (MIDI messages) as you want. Commands are not
case sensitive.

Keys:

  program change (PC) messages:
        
        pc <program> [<channel=1>]

            <program> - program to which you want to change (0-127)
            <channel> - (optional, default=1) on which channel you want message to
                        be sent (1-16)

        examples:
            pc 0        - switch to program 0
            pc 2 3      - switch to program 2 on channel 3

  continuous control (CC) messages:

        cc <cc_number> <value> [<channel=1>]

            <cc_number> - number of CC control (0-127)
            <value>     - value to be set on press or release
            <channel>   - (optional, default=1) on which channel you want message to
                          be sent (1-16)

        examples:
            cc 64 127   - change CC 64 (sustain) to 127 (on)
            cc 1 45 9   - change CC 1 (modulation) to 45 on channel 9

  note on / note off messages:
    
        noteon <note> [<velocity=127> [<channel=1>]]
        noteoff <note> [<velocity=0> [<channel=1>]]

            <note>      - MIDI note to send. This can be MIDI number (24-107) or string
                          representing the wanted note (c1 - b7).
            <velocity>  - (optional, default=127 for note on, 0 for note off) Note 'volume'
                          (0-127)
            <channel>   - (optional, default=1) on which channel you want message to
                          be sent (1-16)

        examples:
            noteon 69           - turn on note 69 (A4) with full velocity (127) and on channel 1
            noteoff c#2         - turn off note C#2 (37) on channel 1
            noteon e3 60 2      - turn on note E3 (52) with velocity 60 on channel 2

Knobs:

    cc <cc_number> [<min=0> [<max=127> [<channel=1>]]]

        cc at the begining is optional but it kinda improves readability

            <cc_number> - number of CC control (0-127)

            <min>       - (optional, default=0) minimal value (when knob is turned "all the way down")
            <max>       - (optional, default=127) minimal value (when knob is turned "all the way up")
        
                If you set min>max, control will reverse - if you turn it up it will go down

            <channel>   - (optional, default=1) on which channel you want message to
                          be sent (1-16)

        examples:
            34            - send CC 34
            cc 23         - send CC 23
            cc 56 22 78   - send CC 56 in range [22, 78]
            cc 33 127 20  - send CC 33 in range [20, 127] but reversed