Henk | b71e318 | 2005-08-17 10:40:26 +0200 | [diff] [blame] | 1 | Driver documentation for yealink usb-p1k phones |
Henk | aca951a | 2005-08-16 16:17:43 +0200 | [diff] [blame] | 2 | |
| 3 | 0. Status |
| 4 | ~~~~~~~~~ |
Henk | aca951a | 2005-08-16 16:17:43 +0200 | [diff] [blame] | 5 | The p1k is a relatively cheap usb 1.1 phone with: |
Henk | b71e318 | 2005-08-17 10:40:26 +0200 | [diff] [blame] | 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 | |
| 14 | For vendor documentation see http://www.yealink.com |
Henk | aca951a | 2005-08-16 16:17:43 +0200 | [diff] [blame] | 15 | |
| 16 | |
| 17 | 1. Compilation (stand alone version) |
| 18 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Henk | aca951a | 2005-08-16 16:17:43 +0200 | [diff] [blame] | 19 | Currently only kernel 2.6.x.y versions are supported. |
Henk | af64a5e | 2005-10-12 15:02:56 +0200 | [diff] [blame] | 20 | In order to build the yealink.ko module do |
Henk | aca951a | 2005-08-16 16:17:43 +0200 | [diff] [blame] | 21 | |
| 22 | make |
| 23 | |
| 24 | If you encounter problems please check if in the MAKE_OPTS variable in |
| 25 | the Makefile is pointing to the location where your kernel sources |
| 26 | are located, default /usr/src/linux. |
| 27 | |
| 28 | |
Henk | af64a5e | 2005-10-12 15:02:56 +0200 | [diff] [blame] | 29 | 1.1 Troubleshooting |
| 30 | ~~~~~~~~~~~~~~~~~~~ |
| 31 | Q: Module yealink compiled and installed without any problem but phone |
| 32 | is not initialized and does not react to any actions. |
| 33 | A: 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 | |
| 39 | Q: Phone is working now (displays version and accepts keypad input) but I can't |
| 40 | find the sysfs files. |
| 41 | A: 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 | |
Henk | aca951a | 2005-08-16 16:17:43 +0200 | [diff] [blame] | 44 | |
| 45 | 2. keyboard features |
| 46 | ~~~~~~~~~~~~~~~~~~~~ |
| 47 | The current mapping in the kernel is provided by the map_p1k_to_key |
| 48 | function: |
| 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 | |
| 68 | 3. LCD features |
| 69 | ~~~~~~~~~~~~~~~ |
| 70 | The 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 | |
| 82 | Line 1 Format (see below) : 18.e8.M8.88...188 |
| 83 | Icon names : M D : IN OUT STORE |
| 84 | Line 2 Format : ......... |
| 85 | Icon name : NEW REP SU MO TU WE TH FR SA |
| 86 | Line 3 Format : 888888888888 |
| 87 | |
| 88 | |
| 89 | Format description: |
| 90 | From a user space perspective the world is seperated in "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 | |
Matt LaPlante | 6c28f2c | 2006-10-03 22:46:31 +0200 | [diff] [blame^] | 96 | Reduced capability 7 segm digit, when segments are hard wired together. |
Henk | aca951a | 2005-08-16 16:17:43 +0200 | [diff] [blame] | 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 | |
| 108 | 4. Driver usage |
| 109 | ~~~~~~~~~~~~~~~ |
| 110 | For 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 | |
| 128 | 4.1 lineX |
| 129 | ~~~~~~~~~ |
| 130 | Reading /sys/../lineX will return the format string with its current value: |
| 131 | |
| 132 | Example: |
| 133 | cat ./line3 |
| 134 | 888888888888 |
| 135 | Linux Rocks! |
| 136 | |
| 137 | Writing to /sys/../lineX will set the coresponding 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 | |
| 150 | 4.2 get_icons |
| 151 | ~~~~~~~~~~~~~ |
| 152 | Reading 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 | |
| 175 | 4.3 show/hide icons |
| 176 | ~~~~~~~~~~~~~~~~~~~ |
| 177 | Writing to these files will update the state of the icon. |
| 178 | Only one icon at a time can be updated. |
| 179 | |
| 180 | If an icon is also on a ./lineX the corresponding value is |
| 181 | updated 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 | |
Henk | b71e318 | 2005-08-17 10:40:26 +0200 | [diff] [blame] | 196 | 5. Sound features |
| 197 | ~~~~~~~~~~~~~~~~~ |
| 198 | Sound is supported by the ALSA driver: snd_usb_audio |
| 199 | |
| 200 | One 16-bit channel with sample and playback rates of 8000 Hz is the practical |
| 201 | limit 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 | |
| 210 | 6. Credits & Acknowledgments |
Henk | aca951a | 2005-08-16 16:17:43 +0200 | [diff] [blame] | 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 | |