Commit 51218941 authored by Brandon Invergo's avatar Brandon Invergo

Flesh out the rest of the documentation.

parent 74e60157
......@@ -59,6 +59,7 @@ The document was typeset with
* Introduction::
* Getting Started::
* Invoking Librekontrol::
* New Devices::
* Reference::
* Copying This Manual::
* Concept Index::
......@@ -393,6 +394,12 @@ actually configuring it within a programming language. We're not
quite there yet, but this is much simpler than using the underlying,
@dfn{low-level} programming interface.
You would stick that code in your Librekontrol initialization script,
which is usually located at
@file{$HOME/.config/librekontrol/init.scm}, and then you would run
the @command{librekontrol} command to start using the device.
@xref{Invoking Librekontrol}.
We'll take a look at this example in chunks in the following sections:
@menu
......@@ -732,6 +739,159 @@ safe, we clean up a bit.
@node Invoking Librekontrol
@chapter Invoking Librekontrol
You start Librekontrol by running @command{librekontrol} at the
command line. Librekontrol will then read your configuration from an
initialization script and it will then start listening for events.
By default, the program will load the initialization script from
@file{$XDG_CONFIG_HOME/librekontrol/init.scm}. Usually,
@env{XDG_CONFIG_HOME} will point to @env{$HOME/.config}, so the file
should be in @env{$HOME/.config/librekontrol/init.scm}. If
@env{XDG_CONFIG_HOME} is not set, then the program tries to load the
file directly from @env{$HOME/.config/librekontrol/init.scm}.
To specify an initialization file at a different location, you can use
the command's @option{--load-file} (short option: @option{-f}).
You can request Librekontrol to emit debug information by passing the
@option{--debug} (@option{-d}) option.
To get a list of available command-line options, you can pass the
@option{--help} (@option{-?}) or @option{--usage} options.
Finally, to view the version of Librekontrol that you have installed,
pass the @option{--version} (@option{-V}) option.
@node New Devices
@chapter 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
(@pxref{Modules,,,guile}).
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:
@enumerate
@item
Determine the device's input and ALSA names (if any).
You might find the input name by using the @command{evtest}. The
input device name is listed on the right. If it's not clear which
name refers to your device, you can use @command{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 @command{aplay} command by
running @samp{aplay --list-devices}. 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
@samp{card X:} (i.e. use the first name that you see for the ``card'',
not the subsequent ``device'' name; nevermind if the device isn't
actually a sound card).
By convention, you would bind these values to @var{input-name} and
@var{alsa-name}, respectively.
@item
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; @pxref{Low-Level Devices}) in your
initialization script and then run @command{librekontrol} with the
@option{--debug} option. @xref{Invoking Librekontrol}. Start
interacting with the device.
So, your @file{init.scm} looks like this:
@example
(use-modules (librekontrol core))
(define input-name "My Device Name")
(open-device #f input-name #f #f)
@end example
After running the program and pressing a button on the device, the
output will look something like this:
@example
EV_KEY event: KEY_A '(1 . 30) 1
EV_KEY event: KEY_A '(1 . 30) 0
@end example
This tells us that hitting that button sends a keypress event
(@var{ev-key}) corresponding to hitting the @kbd{a} key (@var{key-a}).
@xref{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 @var{define-input-event}
syntax from @samp{(librekontrol input)}:
@example
(define-input-event my-button ev-key key-a)
@end example
For absolute-position events (@var{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 @var{abs-input-max}
procedure in @samp{(librekontrol core)}. @xref{Low-Level Input
Events}. By convention, you should define variables holding maximum
values using @var{make-input-max-parameter} from @samp{(librekontrol
device)} (TODO: there should be a @var{make-input-min-parameter}):
@example
(define my-slider-max (make-input-max-parameter 999))
@end example
@item
Deduce and define the ALSA hardware control IDs associated with each
LED (or other feature), if any.
You can find these via the command @command{amixer} by running
@samp{amixer controls} (note that you might have to select the device
using the @option{-c}/@option{--card} option. Define the controls
using @var{define-alsa-ctl} from @samp{(librekontrol alsa)}.
@command{amixer} will list @samp{numid=N} next to each control; this
is the numeric id (@var{numid}) to pass to @var{define-alsa-ctl} as the
first argument. The second argument should be @var{'boolean} (i.e. it
can be either on or off) or @var{'integer} (it can take a range of
values, e.g. an LED that can have a range of brightnesses).
@example
(define-alsa-ctl my-led 1 'boolean)
@end example
@item
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 @var{define-control} from
@samp{(librekontrol device)}. The first argument is the input event
(from @var{define-input-event}) associated with the control and the
second argument is the ALSA hardware control (from
@var{define-alsa-ctl}, or @samp{#f} if there is no associated ALSA
ctl).
@example
(define-control button my-button my-led)
(define-control slider my-slider #f)
@end example
@end enumerate
@node Reference
@chapter Reference
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment