Documentation/input/devices/yealink.rst

   1 ===============================================
   2 Driver documentation for yealink usb-p1k phones
   3 ===============================================
   4
   5 Status
   6 ======
   7
   8 The p1k is a relatively cheap usb 1.1 phone with:
   9
  10   - keyboard            full support, yealink.ko / input event API
  11   - LCD                 full support, yealink.ko / sysfs API
  12   - LED                 full support, yealink.ko / sysfs API
  13   - dialtone            full support, yealink.ko / sysfs API
  14   - ringtone            full support, yealink.ko / sysfs API
  15   - audio playback      full support, snd_usb_audio.ko / alsa API
  16   - audio record        full support, snd_usb_audio.ko / alsa API
  17
  18 For vendor documentation see http://www.yealink.com
  19
  20
  21 keyboard features
  22 =================
  23
  24 The current mapping in the kernel is provided by the map_p1k_to_key
  25 function::
  26
  27    Physical USB-P1K button layout       input events
  28
  29
  30               up                             up
  31         IN           OUT                left,   right
  32              down                           down
  33
  34       pickup   C    hangup              enter, backspace, escape
  35         1      2      3                 1, 2, 3
  36         4      5      6                 4, 5, 6,
  37         7      8      9                 7, 8, 9,
  38         *      0      #                 *, 0, #,
  39
  40 The "up" and "down" keys, are symbolised by arrows on the button.
  41 The "pickup" and "hangup" keys are symbolised by a green and red phone
  42 on the button.
  43
  44
  45 LCD features
  46 ============
  47
  48 The LCD is divided and organised as a 3 line display::
  49
  50     |[]   [][]   [][]   [][]   in   |[][]
  51     |[] M [][] D [][] : [][]   out  |[][]
  52                               store
  53
  54     NEW REP         SU MO TU WE TH FR SA
  55
  56     [] [] [] [] [] [] [] [] [] [] [] []
  57     [] [] [] [] [] [] [] [] [] [] [] []
  58
  59
  60   Line 1  Format (see below)    : 18.e8.M8.88...188
  61           Icon names            :   M  D  :  IN OUT STORE
  62   Line 2  Format                : .........
  63           Icon name             : NEW REP SU MO TU WE TH FR SA
  64   Line 3  Format                : 888888888888
  65
  66
  67 Format description:
  68   From a userspace perspective the world is separated into "digits" and "icons".
  69   A digit can have a character set, an icon can only be ON or OFF.
  70
  71   Format specifier::
  72
  73     '8' :  Generic 7 segment digit with individual addressable segments
  74
  75     Reduced capability 7 segment digit, when segments are hard wired together.
  76     '1' : 2 segments digit only able to produce a 1.
  77     'e' : Most significant day of the month digit,
  78           able to produce at least 1 2 3.
  79     'M' : Most significant minute digit,
  80           able to produce at least 0 1 2 3 4 5.
  81
  82     Icons or pictograms:
  83     '.' : For example like AM, PM, SU, a 'dot' .. or other single segment
  84           elements.
  85
  86
  87 Driver usage
  88 ============
  89
  90 For userland the following interfaces are available using the sysfs interface::
  91
  92   /sys/.../
  93            line1        Read/Write, lcd line1
  94            line2        Read/Write, lcd line2
  95            line3        Read/Write, lcd line3
  96
  97            get_icons    Read, returns a set of available icons.
  98            hide_icon    Write, hide the element by writing the icon name.
  99            show_icon    Write, display the element by writing the icon name.
 100
 101            map_seg7     Read/Write, the 7 segments char set, common for all
 102                         yealink phones. (see map_to_7segment.h)
 103
 104            ringtone     Write, upload binary representation of a ringtone,
 105                         see yealink.c. status EXPERIMENTAL due to potential
 106                         races between async. and sync usb calls.
 107
 108
 109 lineX
 110 ~~~~~
 111
 112 Reading /sys/../lineX will return the format string with its current value.
 113
 114   Example::
 115
 116     cat ./line3
 117     888888888888
 118     Linux Rocks!
 119
 120 Writing to /sys/../lineX will set the corresponding LCD line.
 121
 122  - Excess characters are ignored.
 123  - If less characters are written than allowed, the remaining digits are
 124    unchanged.
 125  - The tab '\t'and '\n' char does not overwrite the original content.
 126  - Writing a space to an icon will always hide its content.
 127
 128   Example::
 129
 130     date +"%m.%e.%k:%M"  | sed 's/^0/ /' > ./line1
 131
 132   Will update the LCD with the current date & time.
 133
 134
 135 get_icons
 136 ~~~~~~~~~
 137
 138 Reading will return all available icon names and its current settings::
 139
 140   cat ./get_icons
 141   on M
 142   on D
 143   on :
 144      IN
 145      OUT
 146      STORE
 147      NEW
 148      REP
 149      SU
 150      MO
 151      TU
 152      WE
 153      TH
 154      FR
 155      SA
 156      LED
 157      DIALTONE
 158      RINGTONE
 159
 160
 161 show/hide icons
 162 ~~~~~~~~~~~~~~~
 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
 172     echo -n "STORE" > ./show_icon
 173
 174     cat ./line1
 175     18.e8.M8.88...188
 176                   S
 177
 178   Example - sound the ringtone for 10 seconds::
 179
 180     echo -n RINGTONE > /sys/..../show_icon
 181     sleep 10
 182     echo -n RINGTONE > /sys/..../hide_icon
 183
 184
 185 Sound features
 186 ==============
 187
 188 Sound is supported by the ALSA driver: snd_usb_audio
 189
 190 One 16-bit channel with sample and playback rates of 8000 Hz is the practical
 191 limit of the device.
 192
 193   Example - recording test::
 194
 195     arecord -v -d 10 -r 8000 -f S16_LE -t wav  foobar.wav
 196
 197   Example - playback test::
 198
 199     aplay foobar.wav
 200
 201
 202 Troubleshooting
 203 ===============
 204
 205 :Q: Module yealink compiled and installed without any problem but phone
 206     is not initialized and does not react to any actions.
 207 :A: If you see something like:
 208     hiddev0: USB HID v1.00 Device [Yealink Network Technology Ltd. VOIP USB Phone
 209     in dmesg, it means that the hid driver has grabbed the device first. Try to
 210     load module yealink before any other usb hid driver. Please see the
 211     instructions provided by your distribution on module configuration.
 212
 213 :Q: Phone is working now (displays version and accepts keypad input) but I can't
 214     find the sysfs files.
 215 :A: The sysfs files are located on the particular usb endpoint. On most
 216     distributions you can do: "find /sys/ -name get_icons" for a hint.
 217
 218
 219 Credits & Acknowledgments
 220 =========================
 221
 222   - Olivier Vandorpe, for starting the usbb2k-api project doing much of
 223     the reverse engineering.
 224   - Martin Diehl, for pointing out how to handle USB memory allocation.
 225   - Dmitry Torokhov, for the numerous code reviews and suggestions.