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