Documentation/input/yealink.txt

   1 yealink - Linux driver for usb-p1k phones
   2
   3 0. Status
   4 ~~~~~~~~~
   5
   6 The p1k is a relatively cheap usb 1.1 phone with:
   7   - keyboard            full support
   8   - LCD                 full support
   9   - LED                 full support
  10   - dialtone            full support
  11   - ringtone            full support
  12   - audio playback      via generic usb audio diver
  13   - audio record        via generic usb audio diver
  14
  15
  16 1. Compilation (stand alone version)
  17 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18
  19 Currently only kernel 2.6.x.y versions are supported.
  20 In order to build the yealink.ko module do:
  21
  22   make
  23
  24 If you encounter problems please check if in the MAKE_OPTS variable in
  25 the Makefile is pointing to the location where your kernel sources
  26 are located, default /usr/src/linux.
  27
  28
  29
  30 2. keyboard features
  31 ~~~~~~~~~~~~~~~~~~~~
  32 The current mapping in the kernel is provided by the map_p1k_to_key
  33 function:
  34
  35    Physical USB-P1K button layout       input events
  36
  37
  38               up                             up
  39         IN           OUT                left,   right
  40              down                           down
  41
  42       pickup   C    hangup              enter, backspace, escape
  43         1      2      3                 1, 2, 3
  44         4      5      6                 4, 5, 6,
  45         7      8      9                 7, 8, 9,
  46         *      0      #                 *, 0, #,
  47
  48   The "up" and "down" keys, are symbolised by arrows on the button.
  49   The "pickup" and "hangup" keys are symbolised by a green and red phone
  50   on the button.
  51
  52
  53 3. LCD features
  54 ~~~~~~~~~~~~~~~
  55 The LCD is divided and organised as a 3 line display:
  56
  57     |[]   [][]   [][]   [][]   in   |[][]
  58     |[] M [][] D [][] : [][]   out  |[][]
  59                               store
  60
  61     NEW REP         SU MO TU WE TH FR SA
  62
  63     [] [] [] [] [] [] [] [] [] [] [] []
  64     [] [] [] [] [] [] [] [] [] [] [] []
  65
  66
  67 Line 1  Format (see below)      : 18.e8.M8.88...188
  68         Icon names              :   M  D  :  IN OUT STORE
  69 Line 2  Format                  : .........
  70         Icon name               : NEW REP SU MO TU WE TH FR SA
  71 Line 3  Format                  : 888888888888
  72
  73
  74 Format description:
  75   From a user space perspective the world is seperated in "digits" and "icons".
  76   A digit can have a character set, an icon can only be ON or OFF.
  77
  78   Format specifier
  79     '8' :  Generic 7 segment digit with individual addressable segments
  80
  81     Reduced capabillity 7 segm digit, when segments are hard wired together.
  82     '1' : 2 segments digit only able to produce a 1.
  83     'e' : Most significant day of the month digit,
  84           able to produce at least 1 2 3.
  85     'M' : Most significant minute digit,
  86           able to produce at least 0 1 2 3 4 5.
  87
  88     Icons or pictograms:
  89     '.' : For example like AM, PM, SU, a 'dot' .. or other single segment
  90           elements.
  91
  92
  93 4. Driver usage
  94 ~~~~~~~~~~~~~~~
  95 For userland the following interfaces are available using the sysfs interface:
  96   /sys/.../
  97            line1        Read/Write, lcd line1
  98            line2        Read/Write, lcd line2
  99            line3        Read/Write, lcd line3
 100
 101            get_icons    Read, returns a set of available icons.
 102            hide_icon    Write, hide the element by writing the icon name.
 103            show_icon    Write, display the element by writing the icon name.
 104
 105            map_seg7     Read/Write, the 7 segments char set, common for all
 106                         yealink phones. (see map_to_7segment.h)
 107
 108            ringtone     Write, upload binary representation of a ringtone,
 109                         see yealink.c. status EXPERIMENTAL due to potential
 110                         races between async. and sync usb calls.
 111
 112
 113 4.1 lineX
 114 ~~~~~~~~~
 115 Reading /sys/../lineX will return the format string with its current value:
 116
 117   Example:
 118   cat ./line3
 119   888888888888
 120   Linux Rocks!
 121
 122 Writing to /sys/../lineX will set the coresponding LCD line.
 123  - Excess characters are ignored.
 124  - If less characters are written than allowed, the remaining digits are
 125    unchanged.
 126  - The tab '\t'and '\n' char does not overwrite the original content.
 127  - Writing a space to an icon will always hide its content.
 128
 129   Example:
 130   date +"%m.%e.%k:%M"  | sed 's/^0/ /' > ./line1
 131
 132   Will update the LCD with the current date & time.
 133
 134
 135 4.2 get_icons
 136 ~~~~~~~~~~~~~
 137 Reading will return all available icon names and its current settings:
 138
 139   cat ./get_icons
 140   on M
 141   on D
 142   on :
 143      IN
 144      OUT
 145      STORE
 146      NEW
 147      REP
 148      SU
 149      MO
 150      TU
 151      WE
 152      TH
 153      FR
 154      SA
 155      LED
 156      DIALTONE
 157      RINGTONE
 158
 159
 160 4.3 show/hide icons
 161 ~~~~~~~~~~~~~~~~~~~
 162 Writing to these files will update the state of the icon.
 163 Only one icon at a time can be updated.
 164
 165 If an icon is also on a ./lineX the corresponding value is
 166 updated with the first letter of the icon.
 167
 168   Example - light up the store icon:
 169   echo -n "STORE" > ./show_icon
 170
 171   cat ./line1
 172   18.e8.M8.88...188
 173                S
 174
 175   Example - sound the ringtone for 10 seconds:
 176   echo -n RINGTONE > /sys/..../show_icon
 177   sleep 10
 178   echo -n RINGTONE > /sys/..../hide_icon
 179
 180
 181 5. Credits & Acknowledgments
 182 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 183   - Olivier Vandorpe, for starting the usbb2k-api project doing much of
 184         the reverse engineering.
 185   - Martin Diehl, for pointing out how to handle USB memory allocation.
 186   - Dmitry Torokhov, for the numerous code reviews and suggestions.
 187