0001 ===============================================
0002 Driver documentation for yealink usb-p1k phones
0003 ===============================================
0004
0005 Status
0006 ======
0007
0008 The p1k is a relatively cheap usb 1.1 phone with:
0009
0010 - keyboard full support, yealink.ko / input event API
0011 - LCD full support, yealink.ko / sysfs API
0012 - LED full support, yealink.ko / sysfs API
0013 - dialtone full support, yealink.ko / sysfs API
0014 - ringtone full support, yealink.ko / sysfs API
0015 - audio playback full support, snd_usb_audio.ko / alsa API
0016 - audio record full support, snd_usb_audio.ko / alsa API
0017
0018 For vendor documentation see http://www.yealink.com
0019
0020
0021 keyboard features
0022 =================
0023
0024 The current mapping in the kernel is provided by the map_p1k_to_key
0025 function::
0026
0027 Physical USB-P1K button layout input events
0028
0029
0030 up up
0031 IN OUT left, right
0032 down down
0033
0034 pickup C hangup enter, backspace, escape
0035 1 2 3 1, 2, 3
0036 4 5 6 4, 5, 6,
0037 7 8 9 7, 8, 9,
0038 * 0 # *, 0, #,
0039
0040 The "up" and "down" keys, are symbolised by arrows on the button.
0041 The "pickup" and "hangup" keys are symbolised by a green and red phone
0042 on the button.
0043
0044
0045 LCD features
0046 ============
0047
0048 The LCD is divided and organised as a 3 line display::
0049
0050 |[] [][] [][] [][] in |[][]
0051 |[] M [][] D [][] : [][] out |[][]
0052 store
0053
0054 NEW REP SU MO TU WE TH FR SA
0055
0056 [] [] [] [] [] [] [] [] [] [] [] []
0057 [] [] [] [] [] [] [] [] [] [] [] []
0058
0059
0060 Line 1 Format (see below) : 18.e8.M8.88...188
0061 Icon names : M D : IN OUT STORE
0062 Line 2 Format : .........
0063 Icon name : NEW REP SU MO TU WE TH FR SA
0064 Line 3 Format : 888888888888
0065
0066
0067 Format description:
0068 From a userspace perspective the world is separated into "digits" and "icons".
0069 A digit can have a character set, an icon can only be ON or OFF.
0070
0071 Format specifier::
0072
0073 '8' : Generic 7 segment digit with individual addressable segments
0074
0075 Reduced capability 7 segment digit, when segments are hard wired together.
0076 '1' : 2 segments digit only able to produce a 1.
0077 'e' : Most significant day of the month digit,
0078 able to produce at least 1 2 3.
0079 'M' : Most significant minute digit,
0080 able to produce at least 0 1 2 3 4 5.
0081
0082 Icons or pictograms:
0083 '.' : For example like AM, PM, SU, a 'dot' .. or other single segment
0084 elements.
0085
0086
0087 Driver usage
0088 ============
0089
0090 For userland the following interfaces are available using the sysfs interface::
0091
0092 /sys/.../
0093 line1 Read/Write, lcd line1
0094 line2 Read/Write, lcd line2
0095 line3 Read/Write, lcd line3
0096
0097 get_icons Read, returns a set of available icons.
0098 hide_icon Write, hide the element by writing the icon name.
0099 show_icon Write, display the element by writing the icon name.
0100
0101 map_seg7 Read/Write, the 7 segments char set, common for all
0102 yealink phones. (see map_to_7segment.h)
0103
0104 ringtone Write, upload binary representation of a ringtone,
0105 see yealink.c. status EXPERIMENTAL due to potential
0106 races between async. and sync usb calls.
0107
0108
0109 lineX
0110 ~~~~~
0111
0112 Reading /sys/../lineX will return the format string with its current value.
0113
0114 Example::
0115
0116 cat ./line3
0117 888888888888
0118 Linux Rocks!
0119
0120 Writing to /sys/../lineX will set the corresponding LCD line.
0121
0122 - Excess characters are ignored.
0123 - If less characters are written than allowed, the remaining digits are
0124 unchanged.
0125 - The tab '\t'and '\n' char does not overwrite the original content.
0126 - Writing a space to an icon will always hide its content.
0127
0128 Example::
0129
0130 date +"%m.%e.%k:%M" | sed 's/^0/ /' > ./line1
0131
0132 Will update the LCD with the current date & time.
0133
0134
0135 get_icons
0136 ~~~~~~~~~
0137
0138 Reading will return all available icon names and its current settings::
0139
0140 cat ./get_icons
0141 on M
0142 on D
0143 on :
0144 IN
0145 OUT
0146 STORE
0147 NEW
0148 REP
0149 SU
0150 MO
0151 TU
0152 WE
0153 TH
0154 FR
0155 SA
0156 LED
0157 DIALTONE
0158 RINGTONE
0159
0160
0161 show/hide icons
0162 ~~~~~~~~~~~~~~~
0163
0164 Writing to these files will update the state of the icon.
0165 Only one icon at a time can be updated.
0166
0167 If an icon is also on a ./lineX the corresponding value is
0168 updated with the first letter of the icon.
0169
0170 Example - light up the store icon::
0171
0172 echo -n "STORE" > ./show_icon
0173
0174 cat ./line1
0175 18.e8.M8.88...188
0176 S
0177
0178 Example - sound the ringtone for 10 seconds::
0179
0180 echo -n RINGTONE > /sys/..../show_icon
0181 sleep 10
0182 echo -n RINGTONE > /sys/..../hide_icon
0183
0184
0185 Sound features
0186 ==============
0187
0188 Sound is supported by the ALSA driver: snd_usb_audio
0189
0190 One 16-bit channel with sample and playback rates of 8000 Hz is the practical
0191 limit of the device.
0192
0193 Example - recording test::
0194
0195 arecord -v -d 10 -r 8000 -f S16_LE -t wav foobar.wav
0196
0197 Example - playback test::
0198
0199 aplay foobar.wav
0200
0201
0202 Troubleshooting
0203 ===============
0204
0205 :Q: Module yealink compiled and installed without any problem but phone
0206 is not initialized and does not react to any actions.
0207 :A: If you see something like:
0208 hiddev0: USB HID v1.00 Device [Yealink Network Technology Ltd. VOIP USB Phone
0209 in dmesg, it means that the hid driver has grabbed the device first. Try to
0210 load module yealink before any other usb hid driver. Please see the
0211 instructions provided by your distribution on module configuration.
0212
0213 :Q: Phone is working now (displays version and accepts keypad input) but I can't
0214 find the sysfs files.
0215 :A: The sysfs files are located on the particular usb endpoint. On most
0216 distributions you can do: "find /sys/ -name get_icons" for a hint.
0217
0218
0219 Credits & Acknowledgments
0220 =========================
0221
0222 - Olivier Vandorpe, for starting the usbb2k-api project doing much of
0223 the reverse engineering.
0224 - Martin Diehl, for pointing out how to handle USB memory allocation.
0225 - Dmitry Torokhov, for the numerous code reviews and suggestions.
