HowTo SetupKeyboard

Note: LonWillett has documented how he got his keyboard working, but since the 2006 release of maemo the plugin he mentions appears to be unnecessary. I have a VKB Bluetooth virtual keyboard which pairs but does not become the activeinput device. Further and more recent assitance would be extremely welcome -- SteveHolden

This document describes how to set up an external bluetooth (HID) keyboard for the Nokia 770, based on my (LonWillett) experiences with the Freedom mini-keyboard. Most of it should apply to the vast majority of HID keyboards, and a good bit of it may be useful for any external keyboard (including USB keyboards). Non HID Bluetooth keyboards need to install an external application, for instance kbdd.

I'm afraid that I'm not much of a documentation writer, and this assumes a fairly high level of technical knowledge, e.g. it assumes that you know what X keysyms are. Feel free to make improvements or add clarifications.

The place to start is http://770.fs-security.com/keyboards.html. Unfortunately, the current version of the plugin available there (mid-January 2006) still doesn't seem to fully work; e.g. my screen still blanks, despite keyboard usage. But it does seem to be improving, so I'm hoping for a better version soon. And it is still easier than the alternative (which is to edit /etc/default/bluez-utils to start up hidd, and pair manually using hidd --connect).

After installing this plugin, you should have a basic working keyboard. But you will probably want some additional enhancements and/or workarounds before you are satisfied.

The first thing you will want to do is to define your keyboard layout. As mentioned on the plugin description page, the 770 X server uses the old xmodmap style of key mapping; so you will want to create a /home/user/.xmodmap file that describes your keyboard layout.

Handily, the keyboard plugin does include a copy of the xmodmap program for the 770 (installed as /var/lib/install/usr/bin/xmodmap). Unfortunately, contrary to the documentation, the keyboard plugin does not seem to automatically load the definitions from /home/user/.xmodmap (BTW, I only use paired mode, (what other modes are there?) so perhaps this makes the difference). My solution to this problem was to edit the file /etc/osso-af-init/real-af-startup, changing the section that reads:

  echo "Running xset770 -- the future of xset!"
  # disable keyrepeat for select, menu, plus, minus, escape
  xset770 -r 36 0 -r 70 0 -r 73 0 -r 74 0 -r 9 0

  # block here if device lock is on

to

  echo "Running xset770 -- the future of xset!"
  # disable keyrepeat for select, menu, plus, minus, escape
  # also for keycode 8 (special key-modifier for a number of mini-keyboards)
  xset770 -r 36 0 -r 70 0 -r 73 0 -r 74 0 -r 9 0 -r 8 0

  # Install user's .xmodmap mapping, if present (and xmodmap installed)
  if [ -x /var/lib/install/usr/bin/xmodmap -a -r /home/user/.xmodmap ]; then
      /var/lib/install/usr/bin/xmodmap /home/user/.xmodmap
  fi

  # block here if device lock is on

Yes, this does require root, and is an ugly kludge. I would welcome a better solution.

Also note that I added -r 8 0 to the xset770 command; more on this below. Your may not want this for your keyboard.

As for the contents of your .xmodmap file, I will not deal with the basic keys. If you are content with the standard US keyboard layout, then you should be fine there. Otherwise, there are plenty of sources for the appropriate definitions. With my Freedom mini-keyboard, there is no chance of touch typing, and the labeling is for the US layout, so I haven't had to worry myself about this. But there are some other issues as well.

The biggest of these the now infamous Opera text input bug. The 770's Opera browser reacts badly to unknown, non-text keysyms (it inserts rubbish) in multi-line text fields (and perhaps elsewhere). This is true even of modifier keys and undefined keys. And it has a very limited set of non-text keysyms that it does know. The most troublesome effect of this is that the Alt Gr key (which is the Mode_switch keysym) becomes unusable, as do the extra keys added to mini-keyboards to access extended key definitions (e.g. the numeric keys). On the Freedom mini-keyboard, the extra key is labelled Num and generates keycode 8. I understand that the Think Outside keyboards have a similar key that generates the same keycode. The solution to this problem is to map these keys to a keysym that Opera ignores, while not interfering with their functionality. I recommend using the Alt_R keysym for this. So you will probably want the following lines in you .xmodmap file:

! Work around Opera bug for the "Num" and "AltGr" keys
keycode 8 = Alt_R
keycode 108 = Alt_R NoSymbol Mode_switch

NB: The purpose of the -r 8 0 passed to the xset770 program above is to disable auto-repeat for keycode 8, which is my mini-keyboards Num key. Note that auto-repeat needn't be explicitly turned off for the Alt Gr key, because it is bound to a modifier, and so the X server automagically disables it.

Another fact worthy of note is that the 770's buttons are really "keys", so you can get most of their functionality on your keyboard. The relevant keysyms are Up, Down, Left, Right, Return, Escape, F4 (menu), F5 (home), F6 (full-screen), F7 (zoom +), and F8 (zoom -). (OK, I left out the power key, but a simple keysym mapping didn't make it work for me). Any of these keys that are missing from your keyboard can conveniently be put on Alt Gr bindings. e.g. my .xmodmap has the lines:

keysym s = s S F4
keysym Tab = Tab ISO_Left_Tab F8
keysym z = z Z F6
keysym x = x X F7
keysym space = space NoSymbol F5

While the choice of keys may seem strange (unless you also have a Freedom mini-keyboard, and perhaps even then), the point is that I can type Alt**Gr+s** to get the menu, Alt**Gr+x** to zoom in, Alt**Gr+Tab** to zoom out, etc.

Moving on from xmodmap, the /home/users/.matchbox/kbdconfig file can be used to accomplish some interesting things. See http://projects.o-hand.com/matchbox and your /etc/matchbox/kbdconfig for details. Be aware that not everything works. And note that while the command matchbox-remote -keys-reload can be useful after installing a new kbdconfig file, it stopped working for me a couple of times (just randomly, as far as I can tell), and I had to reboot to get things working again.

There is one especially useful, non-obvious use of this file. The command maemo-gtk-im-switch xim sets the input method to the keyboard, and the command maemo-gtk-im-switch osso-input-method sets the input method to the on-screen keyboard. Binding these to keys can be very handy. e.g. my .matchbox/kbdconfig file contains the lines:

<Alt>k=!maemo-gtk-im-switch xim
<Alt>v=!maemo-gtk-im-switch osso-input-method

With this in effect, I can type Alt+v to pull up the on-screen keyboard, e.g. to tap in some character or symbol that my keyboard does not have, and can then type Alt+k to switch off the on-screen keyboard.

In full, my /home/user/.matchbox/kbdconfig file consists of:

<Alt>Escape=close

#<Alt>s=taskmenu
<Alt>p=prev
<Alt>z=fullscreen
<Alt>n=next
<Alt>space=desktop
<Alt>h=hidetitle

<Alt>k=!maemo-gtk-im-switch xim
<Alt>v=!maemo-gtk-im-switch osso-input-method

#<Alt>t=!$osso-xterm

Note that the taskmenu action doesn't do anything, and, sadly, that the !$ and !! actions don't seem to work either.

For Freedom mini-keyboard owners only, here are a couple of other tips. The key labelled Start is undefined by default, but is a fine choice for an Alt key. Adding the following lines to your .xmodmap file accomplishes this:

keycode 133 = Alt_L
clear mod1
add mod1 = Alt_L

This is just standard xmodmap usage, but one needs to know that the magic keycode is 133.

Also, the key combination Shift+Insert can be handy. Noting that the underscore key generates the key combination Shift+minus, adding the line

keysym minus = minus underscore Insert

to your .xmodmap file will allow you to press Alt**Gr+underscore** to generate the Shift+Insert combination.

And finally, for a really involved example, here is my .xmodmap file. I filled out all the accessible Alt**Gr** bindings with keysyms that are missing from my keyboard. I really wanted to be able to type all the ASCII characters, and the extra German and Swedish characters as well, even if I was forced to put them in rather strange locations.

My /home/user/.xmodmap:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Modifier setup

! Note that Shift_L is generated by the keyboard automatically
! (for the symbols that require it), and that Shift_R is generated
! by the shift key on the keyboard.
clear shift
!keycode 50 = Shift_L
!keycode 62 = Shift_R
add shift = Shift_L Shift_R

! Caps_Lock (generated by Num-Shift)
! Change to Shift_Lock
keycode  66 = Shift_Lock
clear lock
add lock = Shift_Lock

! Use the "Start" key as Alt modifier (which the mini-kbd doesn't have).
! xxx NB: Make sure not to include Alt_R in the modifier list, since
! Alt_R is used to work around an opera bug (see below).
!keycode 64 = Alt_L
keycode 133 = Alt_L
clear mod1
add mod1 = Alt_L

! The mini-kbd only has Control_R
!keycode 37 = Control_L
!keycode 105 = Control_R
!clear control
!add control = Control_L Control_R

! Num_Lock -- generated by AltGr+Num on the mini-kbd (and locks the "Num"
! key state).
!keycode 77 = Num_Lock
!clear mod2
!add mod2 = Num_Lock

! The "Num" key (when not combined with "AltGr"); this key should just be
! ignored.
! NB: Should also turn off autorepeat with "xset770 -r 8 0"
!xxx Work around opera bug: bind to "Alt_R" instead of "VoidSymbol"
!xxx keycode 8 = VoidSymbol
keycode 8 = Alt_R

! No mod3
!clear mod3

! mod4 -- alternate symbols ("AltGr")
! xxx Work around opera bug: use "Alt_R" as the primary keysym, and
! Mode_switch as the secondary one (this really should be bound only
! to Mode_switch).
!xxx keycode 108 = Mode_switch
keycode 108 = Alt_R NoSymbol Mode_switch
clear mod4
add mod4 = Mode_switch

! No mod5
!clear mod5

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! Keysym modifications

! Would like to add an extra BackSpace on AltGr+Escape, but
! it messes up the virtual keyboard.
!keysym Escape = Escape NoSymbol BackSpace
keysym Escape = Escape NoSymbol Delete

keysym q = q Q asciitilde
keysym w = w W notsign
keysym e = e E dollar
keysym r = r R sterling
keysym t = t T EuroSign
keysym y = y Y aring Aring
keysym u = u U udiaeresis Udiaeresis
keysym i = i I ssharp
keysym o = o O ampersand
keysym p = p P bar

keysym a = a A asciicircum
keysym s = s S F4
keysym d = d D eacute Eacute
keysym f = f F degree
keysym g = g G grave
keysym h = h H guillemotleft
keysym j = j J guillemotright
keysym k = k K braceleft
keysym l = l L adiaeresis Adiaeresis
keysym semicolon = semicolon colon odiaeresis Odiaeresis
keysym BackSpace = BackSpace NoSymbol Delete

keysym Tab = Tab ISO_Left_Tab F8
keysym z = z Z F6
keysym x = x X F7
keysym c = c C less
keysym v = v V greater
keysym b = b B bracketleft
keysym n = n N bracketright
keysym m = m M braceright
keysym Return = Return

keysym minus = minus underscore Insert
keysym space = space NoSymbol F5