Next: , Previous: , Up: Top   [Contents][Index]

4 Defining a New Device

If you want to use Librekontrol to configure a device, particularly if you want to do this via the high-level configuration commands, you will want to fully define the device in advance. This can be done within your initialization script, or you can put the definitions in a new module, which you can then load from your initialization script (see (guile)Modules).

If you define a new device module, please consider contributing it to Librekontrol so that other owners of the device may use the definitions.

Defining a device consists of the following steps:

  1. Determine the device’s input and ALSA names (if any).

    You might find the input name by using the evtest. The input device name is listed on the right. If it’s not clear which name refers to your device, you can use evtest to test each potential candidate until you find the right one. Alternatively, you can read the kernel source code.

    You can find the ALSA name using the ALSA aplay command by running ‘aplay --list-pcms’. Several devices might be listed so you will have to determine which one refers to the device you would like to configure. Use the name directly following the bit that says ‘CARD=’ (nevermind if the device isn’t actually a sound card).

    By convention, you would bind these values to input-name and alsa-name, respectively.

  2. Deduce and define the input events associated with each input control, if any.

    The easiest way to do this is to open the device (after you’ve determined its input name; see Low-Level Devices) in your initialization script and then run librekontrol with the --debug option. See Invoking Librekontrol. Start interacting with the device.

    So, your init.scm looks like this:

    (use-modules (librekontrol core))
    (define input-name "My Device Name")
    (open-device #f input-name #f #f)

    After running the program and pressing a button on the device, the output will look something like this:

    EV_KEY event: KEY_A     '(1 . 30)       1
    EV_KEY event: KEY_A     '(1 . 30)       0

    This tells us that hitting that button sends a keypress event (ev-key) corresponding to hitting the a key (key-a). See Input Events. These correspond to event type 1 and event code 30, although you probably don’t need these numeric values unless your device is sending undefined events (which is possible). The final number just tells you the value of the event: 1 means the button is pressed and 0 means it’s released. The value might be useful for understanding absolute or relative-position events.

    You would then define this event via the define-input-event syntax from ‘(librekontrol input)’:

    (define-input-event my-button ev-key key-a)

    For absolute-position events (ev-abs), you will want also to define the minimum and maximum possible values. You can either read the kernel code to find this or you can use the abs-input-max procedure in ‘(librekontrol core)’. See Low-Level Input Events. By convention, you should define variables holding maximum values using make-input-max-parameter from ‘(librekontrol device)’ (TODO: there should be a make-input-min-parameter):

    (define my-slider-max (make-input-max-parameter 999))
  3. Deduce and define the ALSA hardware control IDs associated with each LED (or other feature), if any.

    You can find these via the command amixer by running ‘amixer controls’ (note that you might have to select the device using the -c/--card option. Define the controls using define-alsa-ctl from ‘(librekontrol alsa)’.

    amixer will list ‘numid=N’ next to each control; this is the numeric id (numid) to pass to define-alsa-ctl as the first argument. The second argument should be ’boolean (i.e. it can be either on or off) or ’integer (it can take a range of values, e.g. an LED that can have a range of brightnesses).

    (define-alsa-ctl my-led 1 'boolean)
  4. Define high-level controls that are compatible with the callback-function system. These consist of an input event and, optionally, an associated ALSA hardware control.

    This is pretty straight-forward. Just use define-control from ‘(librekontrol device)’. The first argument is the input event (from define-input-event) associated with the control and the second argument is the ALSA hardware control (from define-alsa-ctl, or ‘#f’ if there is no associated ALSA ctl).

    (define-control button my-button my-led)
    (define-control slider my-slider #f)

Next: , Previous: , Up: Top   [Contents][Index]