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. 226