Documentation/input/yealink.txt

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