Next: , Up: High-Level Configuration   [Contents][Index]

5.1.1 Defining Devices

These procedures are used to configure devices. This generally involves defining the controls on the device and then calling the high-level configuration function define-device. The procedures in this function are contained in the module ‘(librekontrol device)’.

Record type: control input-event alsa-ctl

The control record type contains information about a control. A control (e.g. a button) is associated with a particular input-event (the event it sends when the user manipulates the control) and it may also have an associated alsa-ctl (which controls an LED on the device, as defined by ALSA). If there is no ALSA ctl, alsa-ctl will be ‘#f’.

Function: make-control input-event alsa-ctl

Make a new control record combining input-event and alsa-ctl.

Function: control? x

Return ‘#t’ if x is a control record

Function: input-event control
Function: alsa-ctl control

Return the input event or ALSA ctl handle associated with control.

Syntax: define-control symbol input-event alsa-ctl

Make a control record for input-event and alsa-ctl and bind it to symbol.

Function: make-input-max-parameter max-value

Parameterize max-value, ensuring that any new values assigned to it are greater than zero but less-than or equal to max-value. This is for defining the maximum value that an input event can take (which should be set in the device’s driver code in the kernel).

Function: connect-control device control callback [keyword option ...]

Connect control on device to the function callback. Whenever control is activated (i.e. Librekontrol detects its associated input event), callback is called.

callback must be a procedure that takes the following arguments: device, input-event, input-value, alsa-ctl. It may also take any number of optional keyword arguments. The optional keyword arguments and their values must be specified in the call to make-input-max-parameter as keyword and option.

For example, to connect a device to the midi-note-button callback:

(connect-control my-device button 'midi-note-button #:channel 1 #:note
  'midi-note-c3 #:velocity 63)

These optional arguments will then be passed to the midi-note-button procedure each time button is pressed.

Function: configure-device [alsa-name input-name open-midi-seq create-input-remapper remap-events controls idle-wait idle-hooks exit-hooks init]

Open a device using ALSA device alsa-name and/or input device input-name.

If open-midi-seq is ‘#t’ open an ALSA MIDI sequencer for the device (which will be called “Librekontrol <alsa-name> read/write”). If create-input-remapper is ‘#t’, an input remapper is created for the device, which is required to send new input events. Both open-midi-seq and create-input-remapper default to ‘#t’ if they are not specified.

The device is further configured through additional keyword arguments. An argument that is not present or set to ‘#f’ is ignored.

Any “virtual” input events to be generated by the device through event-remapping must first be listed in remap-events. The argument must consist of a list of events created using the make-input-event procedure. See Input Events.

Device controls and their connection to callbacks are defined in controls. This argument must contain a list, where each item is a control specification. Each control specification is a list containing a control (created via make-control), a callback function, and any keyword arguments to be passed to the callback function.

The idle-hooks argument consists of a list of procedures that take no arguments. These procedures will be called every idle-wait seconds (1 second if not specified).

exit-hooks must contain a list of procedures that take no arguments. These procedures are to be run when Librekontrol exits.

Additional initialization procedures can be listed in the init argument. As with other hooks, these must not take any arguments.

Next: , Up: High-Level Configuration   [Contents][Index]