yealink.rst

  1===============================================
  2Driver documentation for yealink usb-p1k phones
  3===============================================
  4
  5Status
  6======
  7
  8The 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
 18For vendor documentation see http://www.yealink.com
 19
 20
 21keyboard features
 22=================
 23
 24The current mapping in the kernel is provided by the map_p1k_to_key
 25function::
 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
 40The "up" and "down" keys, are symbolised by arrows on the button.
 41The "pickup" and "hangup" keys are symbolised by a green and red phone
 42on the button.
 43
 44
 45LCD features
 46============
 47
 48The 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
 67Format 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
 87Driver usage
 88============
 89
 90For 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
109lineX
110~~~~~
111
112Reading /sys/../lineX will return the format string with its current value.
113
114  Example::
115
116    cat ./line3
117    888888888888
118    Linux Rocks!
119
120Writing 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
135get_icons
136~~~~~~~~~
137
138Reading 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
161show/hide icons
162~~~~~~~~~~~~~~~
163
164Writing to these files will update the state of the icon.
165Only one icon at a time can be updated.
166
167If an icon is also on a ./lineX the corresponding value is
168updated 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
185Sound features
186==============
187
188Sound is supported by the ALSA driver: snd_usb_audio
189
190One 16-bit channel with sample and playback rates of 8000 Hz is the practical
191limit 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
202Troubleshooting
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
219Credits & 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.