Multimedia keyboard hot keys

Introduction

A lot of keyboards now have multimedia hot keys on them. For example, most of the Logitech keyboards have the ability to mute the sound and turn the volume up or down. It is possible to use them under X on Linux.

Keyboard keys pass through a ludicrous number of different remappings on Linux before X applications receive them.

they're not "remapped" at all. The XServer *has* to communicate back to the XClient (via the window manager) the key that was pressed. This isn't remapping whatsoever.

  1. The keyboard generates scancodes
  2. The Linux console driver remaps these to Linux keycodes (see /usr/include/linux/input.h)
  3. The X keyboard/kdb performs a HARD-CODED map to X keycodes

  4. The X server performs a mapping from X keycode to KeySym(bol)

But, being Linux, there is more than one way to do it.

  1. The keyboard generates scancodes
  2. The Linux event driver converts these to key events
  3. The X evdev driver converts events to keycodes
  4. The X server performs a mapping from X keycode to KeySym(bol)

I can't get this second way to do anything with extended keys. The first way works, but there are lots of different maps to configure. Ideally, the aim is to get correct KeySyms to be generated by X when the key is pressed. This will allow all X clients to act on these keys in the expected way.

Finding where extended keys are failing

Run xev from a console. With the mouse pointer over the small white window, pressing the key you want should generate a Key Event in the window. This will list the X keycode and the name of the keysym, if there is one, or NoSymbol otherwise.

If no event is generated, X isn't receiving the event, and your kernel scancode mapping is broken.

If the wrong KeySyms are coming out, your X keyboard map may be wrong. You should experiment with setxkbmap to find the correct keyboard layout. Not all keyboards will have a layout configured; you may have to add a new one in /usr/share/X11/xkb/symbols/inet. If your keyboard map is right, this could be caused by the kernel scancode mapping simply being incorrect.

Fixing an incorrect kernel scancode mapping

If your keyboard is available in Xkb, but the kernel scancode mapping is wrong, it is possible to reconfigure this map, preferably by writing an init script to do so.

  1. Deduce the X keycode the key SHOULD generate by reference to /usr/share/X11/xkb/symbols/inet and /usr/share/X11/xkb/keycodes/xfree86.

  2. Refer to the table below to derive the kernel keycode it should have generated (this is the HARD-CODED map AIUI). If this doesn't match up, more or less, with /usr/include/linux/input.h, it's likely it's the X mapping which is wrong.
  3. Run showkey -s at a text console to determine the scancode generated when you press the key

  4. Run setkeycodes <scancode> <kernel keycode> to set that mapping. Add this line to a script.

  5. Pressing the key should now produce the correct KeySym in X.

X code

Kernel Code

0

0

9

1

10

2

11

3

12

4

13

5

14

6

15

7

16

8

17

9

18

10

19

11

20

12

21

13

22

14

23

15

24

16

25

17

26

18

27

19

28

20

29

21

30

22

31

23

32

24

33

25

34

26

35

27

36

28

37

29

38

30

39

31

40

32

41

33

42

34

43

35

44

36

45

37

46

38

47

39

48

40

49

41

50

42

51

43

52

44

53

45

54

46

55

47

56

48

57

49

58

50

59

51

60

52

61

53

62

54

63

55

64

56

65

57

66

58

67

59

68

60

69

61

70

62

71

63

72

64

73

65

74

66

75

67

76

68

77

69

79

71

80

72

81

73

82

74

83

75

84

76

85

77

86

78

87

79

88

80

89

81

90

82

91

83

93

186

94

86

95

87

96

88

97

102

98

103

99

104

100

105

101

224

102

106

103

107

104

108

105

109

106

110

107

111

108

96

109

97

110

119

111

84

112

98

113

100

115

125

116

126

117

127

118

213

119

214

120

215

121

216

122

136

123

118

126

95

127

91

128

90

129

92

130

172

131

94

132

189

133

124

134

121

135

131

136

176

137

181

138

182

139

120

140

132

142

233

143

178

144

165

146

152

147

147

148

222

149

195

150

196

151

149

152

168

153

163

154

197

155

198

157

117

158

139

159

148

160

113

161

140

162

164

163

160

164

166

165

205

166

154

167

199

168

200

169

201

170

190

171

202

172

203

173

204

174

114

175

206

176

115

177

167

178

150

179

207

180

208

181

101

182

183

183

184

184

185

185

210

186

211

187

212

188

137

190

169

191

134

192

135

193

141

194

218

195

219

196

220

197

221

198

144

199

145

200

146

201

151

202

223

203

153

204

161

205

193

207

194

208

93

209

122

210

123

211

89

212

225

213

234

214

227

215

228

216

229

217

230

218

231

219

191

220

177

221

85

222

116

223

142

227

143

228

232

229

217

230

156

231

173

232

128

233

159

234

158

235

157

236

155

237

226

239

112

240

235

241

236

242

237

243

238

244

239

245

138

246

179

247

188

248

133

249

192

251

180

253

162

Other software packages

If X is providing correct Keysyms for your extended keys, most X clients can accept the extended keys directly. In particular, KDE "Input Actions", KDE Applications' "Global Shortcuts" settings or Beryl/Compiz's "Settings Manager" can be configured to act directly on Keysyms.

If KeySyms aren't coming out correctly, a package called hotkeys can be quite easily configured to respond to X keycodes instead of KeySyms, as long as they generate events.

If X isn't receiving kernel events at all, a package called keytouch combines the hotkeys functionality with a kernel keycode configuration script. This attempts to integrate all the various keyboard mappings together with an event dispatcher. It does not however, have very many keyboards available as yet. It did not work for me (I want to use KDE Keyboard event dispatch, not a separate daemon. Also it didn't get the kernel map right).

Configuring `hotkeys`

The core package is called hotkeys. Debian users can aptitude install hotkeys. Other "useful" packages are libxosd2 (when you press a hot key, get an On Screen Display of what's happening) and xev (should already be installed with X).

How to make it work

First of all:

  $ hotkeys --kbd-list

Look through the list and see if your keyboard is there. If it is listed, there's already a definition for your keyboard. If not, read on and I'll explain what to do.

Now edit /etc/hotkeys.conf (root required) and change as required. The most important bit to change is Kbd so when hotkeys is run, it knows what keyboard type you have (obtained above). Otherwise you must specify the keyboard type with the -t arguement.

My configuration looks like the following (comments removed):

  Kbd=itouch
  !WebBrowser=firefox
  Email=thunderbird
  !FileManager=rox
  !MyComputer=rox
  !MyDocuments=rox
  Search=firefox http://www.google.com

To test hotkeys, simply run hotkeys. It will fork in to the background automatically. Finally, press one of your hot keys!

No keyboard definition?

If your keyboard wasn't listed in hotkeys --kbd-list then you can create your own definition. Definitions are XML files and are stored in /usr/share/hotkeys (Debian). Look at some of the other *.def files to get an idea how they're structured first. You will notice that standard "actions" (i.e. Play, Mute VolUp, WebBorwser) relate to the "standard command definitions" in /etc/hotkeys.conf (i.e. WebBrowser=firefox).

You can't invent your own "action". Instead you have to create a user defined action, such as:

  <userdef keycode="237" command="xmms">Multimedia</userdef>

You will also notice each "action" has a key code related to it. This ties in the code sent from the keyboard to the computer with that this button is suppose to do. To find the key codes run xev and press the hot key on the keyboard. You'll notice in the terminal window xev is running in, that when everytime you press a key it scrolls up some information. From that information look for the keycode xx. Where xx is the code for the key you just pressed. So create your definition and save it.

Lastly, re-read the "How to make it work" section.

Starting with X

If you use a ~/.xsession or any other variations of this, simply add in (anywhere before the WM is started):

  hotkeys -Z

The -Z arguement stops the splash screen from being displayed.

If you use a login manager (XDM, GDM, KDM etc.) to login you will probably need to get your window manager to start this program for you. Some window managers have directories in $HOME for this, such as Autostart etc.


Page written by DavidRamsden 2007-06-07 Modified initial section with a technical explanation and alternative (arguably, better) solutions

LinuxHints/KeyboardHotkeys (last edited 2010-09-17 10:53:32 by AdamTrickett)