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