226 lines · plain
1===============================================2Driver documentation for yealink usb-p1k phones3===============================================4 5Status6======7 8The p1k is a relatively cheap usb 1.1 phone with:9 10 - keyboard full support, yealink.ko / input event API11 - LCD full support, yealink.ko / sysfs API12 - LED full support, yealink.ko / sysfs API13 - dialtone full support, yealink.ko / sysfs API14 - ringtone full support, yealink.ko / sysfs API15 - audio playback full support, snd_usb_audio.ko / alsa API16 - audio record full support, snd_usb_audio.ko / alsa API17 18For vendor documentation see http://www.yealink.com19 20 21keyboard features22=================23 24The current mapping in the kernel is provided by the map_p1k_to_key25function::26 27 Physical USB-P1K button layout input events28 29 30 up up31 IN OUT left, right32 down down33 34 pickup C hangup enter, backspace, escape35 1 2 3 1, 2, 336 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 phone42on the button.43 44 45LCD features46============47 48The LCD is divided and organised as a 3 line display::49 50 |[] [][] [][] [][] in |[][]51 |[] M [][] D [][] : [][] out |[][]52 store53 54 NEW REP SU MO TU WE TH FR SA55 56 [] [] [] [] [] [] [] [] [] [] [] []57 [] [] [] [] [] [] [] [] [] [] [] []58 59 60 Line 1 Format (see below) : 18.e8.M8.88...18861 Icon names : M D : IN OUT STORE62 Line 2 Format : .........63 Icon name : NEW REP SU MO TU WE TH FR SA64 Line 3 Format : 88888888888865 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 segments74 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 segment84 elements.85 86 87Driver usage88============89 90For userland the following interfaces are available using the sysfs interface::91 92 /sys/.../93 line1 Read/Write, lcd line194 line2 Read/Write, lcd line295 line3 Read/Write, lcd line396 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 all102 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 potential106 races between async. and sync usb calls.107 108 109lineX110~~~~~111 112Reading /sys/../lineX will return the format string with its current value.113 114 Example::115 116 cat ./line3117 888888888888118 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 are124 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/ /' > ./line1131 132 Will update the LCD with the current date & time.133 134 135get_icons136~~~~~~~~~137 138Reading will return all available icon names and its current settings::139 140 cat ./get_icons141 on M142 on D143 on :144 IN145 OUT146 STORE147 NEW148 REP149 SU150 MO151 TU152 WE153 TH154 FR155 SA156 LED157 DIALTONE158 RINGTONE159 160 161show/hide icons162~~~~~~~~~~~~~~~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 is168updated with the first letter of the icon.169 170 Example - light up the store icon::171 172 echo -n "STORE" > ./show_icon173 174 cat ./line1175 18.e8.M8.88...188176 S177 178 Example - sound the ringtone for 10 seconds::179 180 echo -n RINGTONE > /sys/..../show_icon181 sleep 10182 echo -n RINGTONE > /sys/..../hide_icon183 184 185Sound features186==============187 188Sound is supported by the ALSA driver: snd_usb_audio189 190One 16-bit channel with sample and playback rates of 8000 Hz is the practical191limit of the device.192 193 Example - recording test::194 195 arecord -v -d 10 -r 8000 -f S16_LE -t wav foobar.wav196 197 Example - playback test::198 199 aplay foobar.wav200 201 202Troubleshooting203===============204 205:Q: Module yealink compiled and installed without any problem but phone206 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 Phone209 in dmesg, it means that the hid driver has grabbed the device first. Try to210 load module yealink before any other usb hid driver. Please see the211 instructions provided by your distribution on module configuration.212 213:Q: Phone is working now (displays version and accepts keypad input) but I can't214 find the sysfs files.215:A: The sysfs files are located on the particular usb endpoint. On most216 distributions you can do: "find /sys/ -name get_icons" for a hint.217 218 219Credits & Acknowledgments220=========================221 222 - Olivier Vandorpe, for starting the usbb2k-api project doing much of223 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