← Back to branch summary

~ubuntu-branches/ubuntu/precise/linux-lowlatency/precise

« back to all changes in this revision

Viewing changes to Documentation/input/yealink.txt

  • Committer: Package Import Robot
  • Author(s): Alessio Igor Bogani
  • Date: 2011-10-26 11:13:05 UTC
  • Revision ID: package-import@ubuntu.com-20111026111305-tz023xykf0i6eosh
Tags: upstream-3.2.0
Import upstream version 3.2.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
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