Merge git://git.kernel.org/pub/scm/linux/kernel/git/wim/linux-2.6-watchdog
[linux-2.6] / Documentation / input / yealink.txt
1 Driver documentation for yealink usb-p1k phones
2
3 0. Status
4 ~~~~~~~~~
5 The p1k is a relatively cheap usb 1.1 phone with:
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
15
16
17 1. Compilation (stand alone version)
18 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
19 Currently only kernel 2.6.x.y versions are supported.
20 In order to build the yealink.ko module do
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
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
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 userspace perspective the world is separated into "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
96     Reduced capability 7 segm digit, when segments are hard wired together.
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 corresponding 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
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
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