1
2 Lineakd - The Linux Easy Access Keyboard Daemon
3
4 This is a quick guide to the lineakd package
5
6
7 History
8 -------
9
10Lineakd was originally written by Mark Smulders. However, at around version 0.4 Mark became too busy to continue to maintain and develop lineakd. At about that time, I was already adding functionality to lineakd, enough so that I had a fairly decent grasp on the code base. As Mark dropped off, I picked up the slack, but at the expense of my own project, klineakconfig, a GUI configuration tool for lineakd.
11
12 Quick Setup
13 -----------
14
15For those who want to setup their configuration quickly, here are the steps:
16
17 run 'lineakd -l' to see a list of available keyboards.
18
19 run 'lineakd -c TYPE' to create a standard configuration file for the keyboard with an identifier of TYPE that you found by running lineakd -l
20 The configuration file will be $HOME/.lineak/lineakd.conf
21
22 Edit the config file to specify commands for the keys. The commands will initially be empty.
23 This file can be modified to suit your needs.
24 Do NOT, however, add extra keys or keynames!
25 You can only change the values of the keys that are already present!
26 If you have a key on your keyboard that is not in the file, please post a definition file for it to lineak-devel@lists.sourceforge.net.
27
28
29 Usage
30 -----
31
32Below is the usage message of lineakd:
33
34Usage: lineakd [options...]
35Valid options are:
36 -l, --kbd-list Show all supported keyboard types
37
38 This option will list all of the keyboards that lineakd can find in lineakkb.def files. It will print out these keyboards by unique identifier and then a description. Eg:
39
40 [TYPE] [Full name]
41
42 ACEAKV12 Acer AirKey V (12 keys)
43 APK7 Apple Pro Keyboard (7 keys)
44 BTC5107 BTC 5107
45 BTC5113RF BTC 5113RF MultiMedia
46 BTC5126T BTC 5126T
47 BTC9000 BTC 9000
48
49 The unique identifier is necessary when asking lineakd to generate a config file, and must be present in the config file in a
50 KeyboardType = IDENTIFIER
51 directive.
52
53 -L, --plugin-list List the loaded plugins and their macros.
54 -D, --directives-list Show all of the default, implicit configuration directives.
55
56 -f FILE, --conffile=FILE Specify the .conf file
57 -e FILE, --deffile=FILE Specify the .def file
58
59 These options allow you to specify the paths to the config and defintion files.
60
61 -d DEVICE, --cdrom-dev=DEVICE Specify the CDROM device
62 -m DEVICE, --mixer-dev=DEVICE Specify the mixer device
63
64 These options allow you to specify the devices to use for the CDROM and mixer. These are only used when the default plugin is also used.
65
66 -c TYPE, --config=TYPE Create a new lineakd.conf file for keyboard TYPE
67 (warning: old one will be overwritten!)
68
69 This options tells lineakd to generate a config file in the users ~/.lineak/ directory. The name of the file will be lineakd.conf and it will contain default configuration directives.
70 TYPE must be the unique identifier of a keyboard definition. These can be gotten by running lineakd -l or lineakd --kdb-list
71
72 -v, --verbose Print verbose messages
73 (only visible when not running in background)
74
75 If you use this option, lineakd will print out a lot of debugging messages that are very informative.
76
77 -h, --help Prints the usage message.
78
79 -r, --reload Reload the configuration files.
80
81 This tells lineakd to reload the configuration and keyboard definition files. It will not however reload plugins. If you have added or removed a plugin, you must stop and start the daemon.
82
83 -z --sleep Disable handling of keyboard events
84 -k --awaken Enable handling of keyboard events
85
86 These options disable (-z) and enable (-k) the processing of events. When the daemon is disabled events will stiil be seen, but no commands will be executed until lineakd is run with the -k or --awaken option.
87
88 -x, --exit Tell the daemon to exit.
89
90 This option will cause lineakd to exit.
91
92 -n, --display-font Set the font the on-screen display will use. It must be in X format.
93 i.e. -bitstream-charter-black-r-normal-*-*-240-*-*-p-*-iso8859-1
94 -o, --display-color Set the color of the on-screen display. It must be given as a color code.
95 i.e. #0aff00
96 -t, --display-timeout Set the amount of time that the on-screen display keeps it's text on screen.
97 -p, --display-pos Set the vertical position where osd will display.
98 Valid values are: top, middle, bottom
99 -a, --display-align Set the horizontal alignment for the on-screen display.
100 Valid values are: left, center, right
101 -y, --display-hoffset Set the horizontal offset from the alignment (see above).
102 -w, --display-voffset Set the vertical offset from the position (see osd-pos above).
103 -s, --display-soffset Set the offset for the shadow behind displayed text.
104
105 These options allow one to specify on the command line, or override what is specified in a config file, various display preferences for the on screen display. These are only useful when using a display plugin such as the lineak_xosdplugin
106
107
108
109 Configuration
110 --------------
111
112Lineak uses two types of configuration files: lineakkb.def files and lineakd.conf files.
113
114lineakkb.def
115-------------
116
117lineakkb.def files contain keyboard descriptions that map key and button names, to keycodes and button codes respectively. A lineakkb.def file can be placed either in a system directory, or in a users home directory (in the .lineak/ subdirectory). The lineakd daemon will first read the system lineakkb.def file, usually at /etc/lineakkb.def and then read the ~/.lineak/lineakkb.def file. It will attempt to reconcile the entries, using the local entries to override the system entries.
118
119Here is an example of a keyboard definition from a lineakkb.def file:
120
121[LTCDP]
122 brandname = "Logitech"
123 modelname = "Cordless Desktop Pro"
124 [KEYS]
125 Sleep = 223
126 Internet = 178
127 Mail = 236
128 [END KEYS]
129 [BUTTONS]
130 Thumb = 2
131 [END BUTTONS]
132[END LTCDP]
133
134The structure is important. Adding a new keyboard is as easy as determining the special keys that you keyboard has, using something like xev, and writing your own definition file. Note that the daemon will only register keys that you also have defined in your lineakd.conf file.
135
136lineakd.conf
137------------
138
139lineakd.conf files can live either in a system directory, or in the users home directory under the .lineak subdirectory. lineakd will attempt to load a users config file before looking for a system wide configuration file.
140
141 Directives
142 ----------
143
144Lineakd supports various configuration file directives. Plugins also can specify their own directives. The standard directives that are supported follow with their defaults:
145
146KeyboardType =
147CdromDevice =
148MixerDevice =
149Display_plugin = internal
150Display_font = -adobe-helvetica-bold-r-normal-*-*-240-*-*-p-*-*-*
151Display_color = 0aff00
152Display_timeout = 3
153Display_pos = bottom
154Display_align = center
155Display_hoffset = 0
156Display_voffset = 50
157Display_soffset = 1
158keystate_capslock =
159keystate_numlock =
160keystate_scrolllock =
161
162KeyboardType is the only mandatory defintion. If KeyboardType is not defined, the daemon will not function properly.
163
164The CdromDevice and MixerDevice settings specify the device files to use. These are only useful when used in conjunction with a plugin that requires them. One such plugin is the defaultplugin.
165
166The Display_* directives control the functioning of the on screen display.
167 Display_plugin specifies with of the installed display plugins to use. Currently the only OSD plugin is the xosd plugin.
168
169 Display_font specifies which font name to use for the on screen display. Currently the xosd plugin requires font names in X format.
170
171 Display_color specifies the color of the font. As xosd currently requires the color in a numeric format, that is the default. You can use something like kcolorchooser or the gimp to get color values for you.
172
173 Display_timeout specifies the amount of time the display should remain on screen. After this number of seconds the display will be removed.
174
175 Display_pos specifies the vertical position for the OSD. Possible values are bottom, middle and top.
176
177 Display_align specifies the horizontal position for the OSD. Possible values are left, center and right.
178
179The keystate_* directives control modifiers. By default, lineakd does not pay attention to the modifiers NumLock, CapsLock and ScrollLock. Set these directives to "enable" to use modifiers. (Note: as of beta3, these options do nothing. We automatically use modifiers if they are defined on a per command basis.)
180
181 Toggleable keys
182 ---------------
183
184lineakd supports toggle keys. A toggleable key is one that can have a various number of states for each push of the key. For example, on many keyboards the Play and Pause keys are the same. When you push the key once it plays, the next time it pauses. The same thing goes for the Mute key. You must define a toggle key as key1|key2 in the definition (lineakkb.def) file. We can define a single action for this key in the config file by specifying the keyname in the form key1|key2 - this effectively treats the toggleable key as a normal key. It tells lineakd that we don't want to use this a a toggleable key, maybe because the command we are going to bind to it supports the notion of toggling. We can also specify seperate actions for the Play and Pause states by assigning actions to key1 and key2. eg.
185
186 On the LTCDP there is the key 'Play|Pause' In my
187 config file I can specify either:
188
189 Play|Pause = "/usr/bin/xmms -t"
190
191 To treat this as a normal key, or, if I want seperate functions for the play and pause
192 states:
193
194 Play = "/usr/bin/xmms -p"
195 Pause = "/usr/bin/xmms -u"
196
197Note that there can be more than two states for a toggleable key. For example key1|key2|key3 could be defined.
198
199 Modifiers
200 ---------
201
202lineakd now supports a variable number of modifiers to a key. However, this only applies to non-toggleable keys so a key such as Play|Pause will not work with modifiers if you use it as a toggleable key by putting entries like this:
203 Play = something
204 Pause = something else
205in your config file. However, if you use the key as a non-toggleable key, i.e. like this:
206 Play|Pause = something
207then it becomes possible to use modifiers.
208
209Currently we support the following modifiers:
210 control
211 alt
212 shift
213 mod2
214 mod3
215 mod4
216 mod5
217To use a modifier, we do something like this in the config file:
218 Sleep+control = something
219 Sleep+alt = something different
220 Sleep+shift = something more different
221 Sleep = sleepiness
222 etc.
223
224Modifiers to buttons, if they are defined in the lineakkb.def file, work the same way.
225
226 On-Screen Display
227 -----------------
228
229lineakd supports custom on screen display messages through the configuration file. However, some plugins may choose to disregard custom on screen display messages if they feel it does not apply. Currently you specify the on screen display message for a command by placing it within square brackets at the beginning of the line. E.g.
230 [On Screen Message] Go = some command
231 [Another Message] Home+alt = some command
232 [Boring Message] Home = some command
233
234
235 Plugins
236 -------
237
238The lineakd daemon does not contain any internal macros or actual on screen display functionality. This functionality is implemented in plugins that are loaded when the lineakd daemon is first run. NOTE: Restarts of the daemon with lineakd -r will not reload plugins, or load new plugins.
239
240The previous functionality that existed in versions of lineakd up uptin 0.8 has been moved into two plugins: lineak_defaultplugin, which contains all of the EAK_* macros and lineak_xosdplugin which contains all of the XOSD on screen display functionality. There is now also a lineak_kdeplugin plugin that brings with it a total of 23 macros or more for handling KDE funtionality via dcop. Some of these macros themselves take arguments which expands their functionality. See the respective plugin packages for more information on MACRO usage.
241
242
243 Helper Applications
244 -------------------
245
246The lineakd package now installs two helper applications, send_to_keyboard and evtest.
247
248evtest: Allows you to see the event layer events your keyboard is generating. This is for debugging to help you determine if indeed your keyboard is sending events, and which events it is sending. It uses the new event layer.
249
250send_to_keyboard (only for arm, x86 and x86_64): This is a simple program which, for now is just for the IBM keyboards. It allows you to send actual control codes to the keyboard device to enable or disable certain functions. For example, some of the IBM keyboards require:
251 send_to_keyboard ea 17
252in order to enable the extra keys. This helper application is actually used from lineakd. Within your lineakkb.def file you can specify a configuration option after the keyboard and model name to initialize the keyboard with. As requirements for this sort of thing increases I'll enable the handling of different options. So far we only look for INITIALIZE.
253
254e.g.
255
256[IBMRA7993]
257 brandname = "IBM"
258 modelname = "Rapid Access Keyboard"
259 RAWCOMMAND[INITIALIZE] = "ea 71" # <--- lineakd will at this point fork and execute: `send_to_keyboard ea 17`
260 [KEYS]
261 WWW = 178
262 WorldBook = 151
263 Option = 176
264 Help = 166
265 Standby = 165
266 AudioMute = 146
267 AudioStop = 164
268 AudioPlay|Pause = 153
269 Back = 163
270 Forward = 161
271 AudioLowerVolume = 158
272 AudioRaiseVolume = 160
273 Custom1 = 174
274 [END KEYS]
275
276[END IBMRA7993]
277
278
279 Notes
280 ------
281
282How to get lineakd to send keyevent from easy access keys
283---------------------------------------------------------
284
285You have a few options.
2861) Try the EAK_SENDKEYS or EAK_SENDKEYS_ROOT macros in the lineak_defaultplugins package.
2872) Use the xsendkeys or xsendkeycode commands in the utils subdirectory.
2883) Download and install the xvkbd program from http://homepage3.nifty.com/tsato/xvkbd/
289e.g.
290
291 Back = "xvkbd -text "\\A\\[Left]""
292 Forward = "xvkbd -text "\\A\\[Right]""
293 Reload = "xvkbd -xsendevent -text "\\Cr""
294 Stop = "xvkbd -xsendevent -text "\\e""
295 fnF1 = "xvkbd -xsendevent -text "\\[Up]""
296 fnF2 = "xvkbd -xsendevent -text "\\[Down]""
297 fnF3 = "xvkbd -xsendevent -text "\\Cx""
298 fnF4 = "xvkbd -xsendevent -text "\\Cv""
299 fnF5 = "xvkbd -xsendevent -text "\\Cc""
300
301How to kill lineakd
302-------------------
303
304In the event that lineakd hangs (which it probably will at some point), you have to kill all of the processes manually. You can do this by executing the following command:
305
306 kill -9 `ps -ef | grep lineakd | grep -v grep | awk ' { print $2 }'`
307
308Then, after a hang or crash (or segfault, etc) you should clean up the shared message queue.
309
310Execute:
311
312 ipcs -q
313
314To see any queues that are hanging around. You'll see something like this (but be relatively sure it's not part of another process, if unsure, look at which queues are there before you run lineakd, or just forget about this step):
315
316 ------ Message Queues --------
317 key msqid owner perms used-bytes messages
318 0x0000050c 884736 sheldonl 640 0 0
319
320To get rid of the queue, type:
321
322 ipcrm msg <msqid>
323
324so, for the example type:
325
326 ipcrm msg 884736
327
328If you have a keyboard defined in lineakkb.def that has a toggle key like the one for the LTCDP keyboard, please update the file with the new key format and send it back to me.
329
330Known bugs
331-----------
332
333Linux 2.6 can cause changes in how the keycodes are interpreted. In some cases, keys that use to work, no longer work at all. If this happens to you try the following:
3341) run xev and see if X reports any keycodes for the key(s) that is/are not working. If there are keycodes being produced, you'll have to update the lineakkb.def file (usually in /etc) with the correct keycodes for your keyboard.
3352) If xev does not report any keycodes for one or more of your keys, then try looking in /var/log/messages. If you have error messages in that file from atkbd.c about unknown scancodes, etc. Then somewhere in your startup scripts (at the end of /etc/rc.sysinit for example). Try binding those scancodes to keycodes with the setkeycodes command. If in doubt just use the keycode from your /etc/lineakkb.def file. Then X should produce a keycode for the key. You'll still have to follow the steps under the procedure 1 above to get lineak to recognize the keys, but it'll work.
3363) If you see nothing in your /var/log/messages, and xev produces no keycodes, you can try running showkey -s as root and see if the keypresses show any scancodes. If they do, follow thre relevant part of procedure 2 above. If not, see 4.
3374) If none of the above work, send an email to the linux-usb mailing list (if your keyboard is USB) or to the atkbd.c maintainer and pray they do something about it. Otherwise your screwed. Take your POS keyboard back to the store and get a supported one. :(
338
339USB keyboards may not work or just partially. If possible, use PS/2 for the time being. If this isn't possible, email the X.org development or Linux USB mailing list. Tell them the make and model keyboard you have, and what scancodes are not generating events. Use:
340 showkey -s
341 while running as root to see what scancodes a key produces.
342
343The EAK_SLEEP action has no functionality yet.
344
345Due to the fact that not all IDE CD-ROM drives provide status info on the tray position, the following can occur:
346 * if lineakd is started with the cdrom tray in open position, the eject button
347 has to be pressed twice the first time to close it.
348 * if you opened the cdrom tray with the eject button and let the tray close
349 automatically after a while (hardware timer), the eject button has to be
350 pressed twice to open it again.
351
352Not everything may be platform independant. There may be some things specific to linux or an X11 version.
353
354
355---------
356
357Helper Applications
358
359--------
360
361evtest
362-------
363
364evtest is an event device testing program for Linux. It allows you to determine
365the event layer events that your keyboard is generating. This is for debugging
366purposes to determine if indeed your keyboard is sending events, and which
367events it is sending. This program uses the event layer on the linux 2.6 series
368of kernels.
369
370
371send_to_keyboard
372----------------
373
374send_to_keyboard is a simple program which allows you to send actual control
375codes to the keyboard device to enable or disable certain functions. For example,
376some of the IBM keyboards require:
377 send_to_keyboard ea 17
378
379 in order to enable the extra keys. This helper application is actually used
380from lineakd(1) by specifying the following directive in your lineakkb.def file.
381 RAWCOMMAND[INITIALIZE] = "<args>"
382
383 The args to enable the IBM keyboard would be "ea 17". Lineakd passes those
384arguments to the send_to_keyboard helper application when it starts up. However,
385in order to use the send_to_keyboard functionality from lineakd, it must be
386installed suid root. This can be done by compiling lineakd with the:
387 --enable-suid-helpers option to the configure script.
388
389 For more information, please read the send_to_keyboard man page.
390
391
392xsendkeycode
393------------
394
395This program sends a key event to X using a keycode and a flag that specifies
396the keydown or keyup state. It is not used from lineakd, but exists as a tool
397for scripting, or as a command to use in a lineakd configuration file. It can
398be run as follows:
399
400 xsendkeycode 38 1
401
402This will send the letter 'a'. For more infomation on detailed usage, please
403read the xsendkeycode manpage.
404
405xsendkeys
406---------
407
408xsendkeys is a simple program which allows you to send a key or key
409combination to X. For example: xsendkeys a will send the letter a. If you
410wanted to send a capital a ’A’ you would have to send: xsendkeys Shift_L+a`
411For detailed usage please read the xsendkeys manpage.
412
413
414
415Cheers, Sheldon. <leewsb@hotmail.com>
416
417