DatacompSerialKeyboard

Feel free to refactor this into a more compact how-to document.

A picture of the keyboard is at http://www.portal-pda.com/reviews/psionkeyboard/psionkeyboard.html

In terms of hardware, I used a standard Agenda sync cable and plugged it directly into the keyboard, and plugged the other end into the Agenda. No null-modem or other adapter is necessary.

For software, you need to compile some kernel support (either directly into the kernel or as modules) and a user-space program inputattach.c. I started with the following kernel sources:

http://www.agendacomputing.de/downloads/vr3-kernel-8.0.tgz

Then I applied the kernel patch at

http://www.doc.ic.ac.uk/~jpc1/linux/ipaq/serial.html

I then had to edit arch/mips/config.in, around line 726 before "endmenu" in section VR4181 I had to add the contents of file drivers/char/joystick/Config?.in (the "source" command should have worked but didn't).

Then I did "make menuconfig" and selected all the options as specified at http://www.doc.ic.ac.uk/~jpc1/linux/ipaq/serial.html:

  * character devices->serial support
  * input core support 
  * input core->keyboard 
  * character devices -> joysticks 
  * character devices -> joysticks -> serial port support -> serial input line discipline 
  * character devices -> joysticks -> newton keyboard 

Note that the "joysticks" option only appears if you edit arch/mips/config.in as specified above.

You can choose to make these modules, which I did at first, but this leads to a problem at run-time with insmod complaining about local_symtab_size, so it may be safer to compile these into the kernel statically (i.e. select "Y" instead of "M" for all of the above options).

Compile the kernel and flash it to the VR3.

Then cross-compile inputattach.c from http://www.doc.ic.ac.uk/~jpc1/linux/ipaq/serial.html. Add the following two lines at the top of the file:

1. define SERIO_NEWTON 0x1f
2. define SERIO_STOWAWAY 0x20

This is because the snow toolchain doesn't use the patched kernel include file so it doesn't know about these constants, so we re-define them in the inputattach.c file. (Anyone know the proper way to make the snow toolchain use the updated kernel include files?)

Now, you have to run cross-compile and run xmodmap on the agenda (do a google search for xmodmap.c; there are about 4 .c files you need to download and compile). This is because by default the keycodes used on the agenda are different than those used by standard hardware keyboards. After compiling xmodmap for the vr3, then run xmodmap with the following file (e.g. if you call this file "key.map" then run "xmodmap key.map")

FILE key.map

!
! $XFree86: xc/programs/Xserver/hw/xfree86/etc/xmodmap.std,v 3.4 1996/02/04 09:09:12 dawes Exp $
!
! Standard key mapping for XFree86 (for US keyboards).
!
! This file can be fed to xmodmap to restore the default mapping.
!
! $XConsortium: xmodmap.std /main/7 1996/02/21 17:48:55 kaleb $
!
! First, clear the modifiers
!
clear    shift
clear    lock
clear    control
clear    mod1
clear    mod2
clear    mod3
clear    mod4
clear    mod5
!
! Set the mapping for each key
!
keycode   8 =
keycode   9 = Escape
keycode  10 = 1 exclam
keycode  11 = 2 at
keycode  12 = 3 numbersign
keycode  13 = 4 dollar
keycode  14 = 5 percent
keycode  15 = 6 asciicircum
keycode  16 = 7 ampersand
keycode  17 = 8 asterisk
keycode  18 = 9 parenleft
keycode  19 = 0 parenright
keycode  20 = minus underscore
keycode  21 = equal plus
keycode  22 = BackSpace
keycode  23 = Tab
keycode  24 = q Q
keycode  25 = w W
keycode  26 = e E
keycode  27 = r R
keycode  28 = t T
keycode  29 = y Y
keycode  30 = u U
keycode  31 = i I
keycode  32 = o O
keycode  33 = p P
keycode  34 = bracketleft braceleft
keycode  35 = bracketright braceright
keycode  36 = Return
keycode  37 = Control_L
keycode  38 = a A
keycode  39 = s S
keycode  40 = d D
keycode  41 = f F
keycode  42 = g G
keycode  43 = h H
keycode  44 = j J
keycode  45 = k K
keycode  46 = l L
keycode  47 = semicolon colon
keycode  48 = apostrophe quotedbl
keycode  49 = grave asciitilde
keycode  50 = Shift_L
keycode  51 = backslash bar
keycode  52 = z Z
keycode  53 = x X
keycode  54 = c C
keycode  55 = v V
keycode  56 = b B
keycode  57 = n N
keycode  58 = m M
keycode  59 = comma less
keycode  60 = period greater
keycode  61 = slash question
keycode  62 = Shift_R
keycode  63 = KP_Multiply
keycode  64 = Alt_L Meta_L
keycode  65 = space
keycode  66 = Caps_Lock
keycode  67 = F1
keycode  68 = F2
keycode  69 = F3
keycode  70 = F4
keycode  71 = F5
keycode  72 = F6
keycode  73 = F7
keycode  74 = F8
keycode  75 = F9
keycode  76 = F10
keycode  77 = Num_Lock
keycode  78 = Multi_key
keycode  79 = KP_Home KP_7
keycode  80 = KP_Up KP_8
keycode  81 = KP_Prior KP_9
keycode  82 = KP_Subtract
keycode  83 = KP_Left KP_4
keycode  84 = NoSymbol KP_5
keycode  85 = KP_Right KP_6
keycode  86 = KP_Add
keycode  87 = KP_End KP_1
keycode  88 = KP_Down KP_2
keycode  89 = KP_Next KP_3
keycode  90 = KP_Insert KP_0
keycode  91 = KP_Delete KP_Decimal
!keycode  92 = X386Sys_Req
keycode  93 =
keycode  94 =
keycode  95 = F11
keycode  96 = F12
! keycodes 97-107 are not available on 84-key keyboards
keycode  97 = Home
keycode  98 = Up
keycode  99 = Prior
keycode 100 = Left
keycode 101 = Begin
keycode 102 = Right
keycode 103 = End
keycode 104 = Down
keycode 105 = Next
keycode 106 = Insert
keycode 107 = Delete
keycode 108 = KP_Enter
keycode 109 = Control_R
keycode 110 = Pause
keycode 111 = Print
keycode 112 = KP_Divide
keycode 113 = Alt_R Meta_R
keycode 114 = Break
! keycodes 115-117 are only available on some extended keyboards
! (e.g., Microsoft's ergonomic keyboard).
keycode 115 = Meta_L
keycode 116 = Meta_R
keycode 117 = Menu
!
! Set the modifiers
!
add     shift   = Shift_L Shift_R
add     lock    = Caps_Lock
add     control = Control_L Control_R
add     mod1    = Alt_L Alt_R
! If you have ServerNumlock set in your XF86Config, you can comment out
add     mod2    = Num_Lock
!
!
!
! If you use any of the special default key mappings in Xconfig, they should be
! duplicated in this file.  Mappings should be added before the section above
! which sets the modifiers.
!
!  For the key specs:
!     LeftAlt     =>  keycode  64
!     RightAlt    =>  keycode 113
!     AltGr       =>  keycode 113
!     ScrollLock  =>  keycode  78
!     RightCtl    =>  keycode 109
!     
!  For the mappings:
!     Meta        =>  Alt_L Meta_L
!                     Alt_R Meta_R
!     Compose     =>  Multi_key
!     ModeShift   =>  Mode_switch
!     ModeLock    =>  Mode_switch X386Mode_Lock
!     ScrollLock  =>  Scroll_Lock
!     Control     =>  Control_R
!    
!  If you use ModeShift or ModeLock, the following modifier must be set:
!
!add     mod5    = Mode_switch
!
!  For example, to get the equivalent of:
!
!  ScrollLock  ModeLock
!  RightAlt    ModeShift
!  LeftAlt     Meta
!  RightCtl    Compose
!
!  use the following:
!
!keycode  78 = Mode_switch X386Mode_Lock
!keycode 113 = Mode_switch
!keycode  64 = Alt_L Meta_L
!keycode 109 = Multi_key
!
!add    mod5   = Mode_switch

! When using ServerNumLock in your XF86Config, the following codes/symbols
! are available in place of 79-81, 83-85, 87-91
!keycode  136 = KP_7
!keycode  137 = KP_8
!keycode  138 = KP_9
!keycode  139 = KP_4
!keycode  140 = KP_5
!keycode  141 = KP_6
!keycode  142 = KP_1
!keycode  143 = KP_2
!keycode  144 = KP_3
!keycode  145 = KP_0
!keycode  146 = KP_Decimal
!keycode  147 = Home
!keycode  148 = Up
!keycode  149 = Prior
!keycode  150 = Left
!keycode  151 = Begin
!keycode  152 = Right
!keycode  153 = End
!keycode  154 = Down
!keycode  155 = Next
!keycode  156 = Insert
!keycode  157 = Delete

After running on the vr3 xmodmap with the above key translation table, then on the vr3 run

• xmodmap -e "add shift = Shift_L Shift_R"
• xmodmap -e "add control = Control_L"
• xmodmap -e "add mod1 = Alt_L"
• xmodmap -e "add lock = Caps_Lock"
• inputattach --newtonkbd /dev/ttyS0 &

(N.B., these commands might be able to be integrated into the key.map file)

Make sure pppd (or anything else which might tie up /dev/ttyS0) on the vr3 is not running. Also make sure you can write to /dev/ttyS0 (either run inputattach as root or chmod go+rw /dev/ttyS0)

The keyboard should now work. Note that the built-in software keyboard won't work afterwards apparently because it was started at boot time in the background with a different xmodmap mapping, so it produces garbage characters when combined with the above xmodmap mapping. To use the software keyboard, you have to restore the old xmodmap mapping (by running "xmodmap -pke > old.map" beforehand, then running "xmodmap old.map" to restore the old map, and also running the shift/control/mod/lock xmodmap commands again, to map shift/control/mod/lock to the old keycodes).

I wrote two scripts and put then in my start menu - one script to start the hardware keyboard driver and one to stop the hardware keyboard driver.

The xmodmap mapping above is not optimal but the major keys work. It is the standard US-keyboard mapping, but I had to change the KP_Up, KP_Down, KP_Left, and KP_Right codes to be Up, Down, Left, and Right. There is no ESC; you have to press CTRL+[. Other quirks are that the "fn" modifier key isn't handled, alt is apparently incorrectly mapped, and Option has the function of alt. Anyone who feels like correcting the map, please do. Ideally FN+Up would be page-up, for instance. It is rather tedious to experiment with the keyboard mapping because you if you mess up the keyboard mapping you can't input characters anymore, and then you have to telnet in to fix the situation, but you can't have a network connection and connect the keyboard at the same time because they both use the serial port, so you have to plug and unplug constantly.

Also the keyboard has its own power supply, 3 AAA batteries == 4.5 volts. It also works without power (there is a small power switch) but this drains the VR3 batteries. As long as you connect the keyboard through the standard Agenda sync cable, the voltage difference should be no problem or danger because the cable contains a voltage converter chip in the plug which converts Agenda 3V levels to serial 5V levels.

So the keyboard works. There are links on the wiki about how to modify a PC/AT keyboard to send serial newton-compatible signals; I am fairly confident that, with the above procedure, this would in fact work for using a PC/AT keyboard with the VR3. However you would need a bulky external circuit to change the PC/AT keyboard signals to newton-compatible serial, so it is more compact to use the newton-compatible keyboard.

Oh, and, for the curious, the DPK62's serial rate is 9600bps N81, but this is automatically handled by the driver (apparently the newton has the same settings).

The newton driver could also be loaded as a kernel module, however I received warnings of the sort "local symbol xxx with index xxx exceeds local_symtab_size xxx" when I insmod'd my modules. The modules seemed to work, but I didn't like the warning, so I compiled everything in statically. Any idea what this warning could mean? For those interested in getting the newton/DPK-62 keyboard to work without recompiling the kernel, just the modules, you have to compile the following modules (select "M" instead of "Y" for all the kernel options I mentioned in my last mail, with the exception of "serial support", which should still be "Y" and which by default is compiled statically into the standard Agenda kernels, so you shouldn't compile it separately as a module)

• serio.o
• serport.o
• input.o
• keybdev.o
• newtonkbd.o

insmod'ing them in this order should work. Again, serial.o by default is statically compiled into the standard Agenda kernel, which is why you don't have to compile or insmod serial.o.

Also, I received the information that the insmod problem is caused by an old binutil for mips. There's also the suggestion to do an ld -r for your module:

mipsel-linux-ld -r noraCfgN?.o -o noraCfgNN?.o