
olpc-kbdshim

----------

Note -- there are several versions of olpc-kbdshim -- one
    integrated with udev, another with HAL, and the other a
    "standalone" daemon.  The first two can monitor USB input
    devices, the third cannot.

    The HAL version is no longer supported or maintained, and the
    "standalone" version will receive only minimal support.

----------

This daemon, handles several distinct tasks for the XO.  The
tasks are related by a need to have full access to keyboard and
touchpad activity, so all keyboard and mouse keys are
intercepted.

    "Grab" key support:
        While a grab key is depressed, it transforms touchpad
        motion events into scroll events (i.e., into presses of
        virtual buttons 4, 5, 6, and 7).  The rate at which this
        tranformation occurs it tunable, as well as the "sign"
        of the tranformation.  The grab keys also affect the
        operation of the keyboard up/down/ left/right arrows --
        they, too, will cause scroll events when one of the grab
        keys is held.

        On non-XO (i.e., USB) keyboards, the 'grab' keys are the
        two "logo" keys, and are treated the same as the XO grab
        keys.

    Touchpad and D-pad rotation and reflection:
        When the screen is rotated, it makes sense to rotate the
        actions of the D-pad arrows and the touchpad to match.
        When in e-book mode, it might be desirable to reflect
        the touchpad to make it useful with the laptop halves
        partially opened.  (In this case the d-pad is not
        reflected.)  These translations are activated with
        small commands injected into a fifo the daemon creates
        for the purpose.  (I.e., there is no direct knowledge
        of screen orientation, but an external script provides it.)

    User (in)activity:
        Since this daemon is watching the user's input devices,
        it can readily generate events related to the user being
        idle.  Event are generated after each of three successive
        idle timeouts, as well as for the user becoming active
        again.  These events take the form of writes to a
        filesystem path (which is probably a fifo created by the
        olpc-powerd package).

    Key binding:
        Five XO-specific keys (rotate, and the up/down keys for
        brightness and speaker volume) can be bound to commands
        to be run when they are pressed.


The commands that control olpc-kbdshim are read from a command
fifo (named by the -R option).  All commands are single
characters -- some have arguments.

  Touchpad and D-pad rotation commands:
     n - normal
     i - invert
     r - rotate right  (see below for notes about rotation)
     l - rotate left   (see below for notes about rotation)

     Correct rotation can be maintained simply by giving the same
     keyword to this daemon as is given to xrandr:

     # xrandr -o $new && echo $new >/var/run/olpc-kbdshim_commands


  Reflection:
     X - reflect the X axis
     Y - reflect the Y axis
     Z - reflect both axes
     x - stop reflecting the X axis
     y - stop reflecting the Y axis
     z - stop reflecting both axes

     Reflection cannot be set automatically, because it doesn't
     have sufficient sensors.  However, if one is working in
     ebook mode and wishes to have the touchpad oriented to match
     the screen, then one can use:
        # echo Z >/var/run/olpc-kbdshim_commands
     To restore normal orientation, use:
        # echo z >/var/run/olpc-kbdshim_commands

  User activity:
     I [ N1 [ N2 [ N3 ] ] ]

     When no keyboard or touchpad activity has been seen for N1,
     N2, and N3 seconds, successively, the strings "useridle1",
     "useridle2", and "useridle3" will be written to the pathname
     specified with the -A option.  Once the user has become idle
     (i.e., N1 has been passed), then their keystroke or mouse
     movement will trigger a "useractive" event.  The 'I' command
     can be used at any time to reset the timers, in which case
     the activity monitor is fully reset along with the timers
     (so the next activity will generate "useractive").
     Specifying N1 as 0 will suppress all activity events.
     Omitting N2 or N3 will cause them to be set to N1+1 or N2+1.

     Example:
        # echo I 120 240 600  >/var/run/olpc-kbdshim_commands



Local/non-local input devices:

    All keyboards and pointer devices connected to the laptop
    will be monitored for user activity.

    All keyboards and pointer devices will participate in the
    translations caused by the "grab" (or "logo") keys.

    Only the XO's local touchpad, and only the XO's local D-pad
    (which is essentially the XO's numeric keypad arrows), will
    have their behavior modified by rotation.

    Only the XO's local brightness, volume, and "rotate" keys
    will be bound to their respective commands.  (The local
    brightness and volume keys can be modified by the local alt
    keys to request "min" and "max" values, rather than an
    incremental change.)


Further configuration:

    The keyboard and input devices which are considered "local"
    can be changed using the -K and -T options.  (Useful if the
    only keyboard or touchpad is a USB model, for instance.)

    Since the keyboard and touchpad are inaccessible when in
    ebook mode, kbdshim will suppress those events when in that
    mode.  Use "-e 0" to disable this feature.  (Events from the
    game keys will still be reported, of course.)

    The identity of the keys used for "grabbing" can be changed
    with the -g or -G options.

    The amount of pointer movement need to cause a scroll event
    during grab operation can be set with -q.

    To allow better control of scrolling in just one direction,
    the -n option can be used:  if either the vertical or
    horizontal motion is less than N percent (normally 33%) of
    the other, then the smaller of the two will be dropped
    entirely.

    The relationship between pointer movement and scrolling direction
    can be inverted with the -v option.

    The daemon can be put into a realtime scheduling class with -s.

    Logging can be forced to syslog with -l.

    The -d (enable more logging) and -X (don't transmit) can aid
    debugging.


Rotation:

    Trac tickets (at dev.laptop.org) #9350 and #10380 deal with
    issues regarding the rotation of the screen and touchpad.

    The goal, of course, is to make the screen, touchpad, and
    d-pad all rotate in the direction printed on the button when
    the button is pushed.  On the widely-distributed XO-1 build
    802 and earlier, the screen goes the wrong way when the
    button is pushed, because of a buglet in the X11 driver. 
    This was fixed in later drivers, so /usr/bin/olpc-rotate
    assumes that xrandr will rotate the screen in the correct
    direction when given "left" and "right" directives.  ("left"
    means counterclockwise, "right" means clockwise.)  Later, it
    was discovered that SWRandR on the XO-1.5 may also rotate the
    screen incorrectly.

    To allow for further "errant" cases, olpc-rotate now honors
    the presence of a flag file (/var/run/olpc-rotate-reverse). 
    When this flag is present, xrandr will be instructed to go
    left instead of right, and vice versa.  Creating this flag
    is left to other software on the system.

    In addition, a "-r" flag to olpc-rotate tells it to reset
    rotation of the touchpad (and d-pad), presumably because the
    screen is known to be in the upright orientation.  This can
    be used when bringing up or restarting X.

    (Note that we've never expected the game keys (circle, square,
    check, cross) to rotate -- they have labels on them, so
    rotating doesn't make sense.)

