yealink.txt 6.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216
  1. Driver documentation for yealink usb-p1k phones
  2. 0. Status
  3. ~~~~~~~~~
  4. The p1k is a relatively cheap usb 1.1 phone with:
  5. - keyboard full support, yealink.ko / input event API
  6. - LCD full support, yealink.ko / sysfs API
  7. - LED full support, yealink.ko / sysfs API
  8. - dialtone full support, yealink.ko / sysfs API
  9. - ringtone full support, yealink.ko / sysfs API
  10. - audio playback full support, snd_usb_audio.ko / alsa API
  11. - audio record full support, snd_usb_audio.ko / alsa API
  12. For vendor documentation see http://www.yealink.com
  13. 1. Compilation (stand alone version)
  14. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15. Currently only kernel 2.6.x.y versions are supported.
  16. In order to build the yealink.ko module do
  17. make
  18. If you encounter problems please check if in the MAKE_OPTS variable in
  19. the Makefile is pointing to the location where your kernel sources
  20. are located, default /usr/src/linux.
  21. 1.1 Troubleshooting
  22. ~~~~~~~~~~~~~~~~~~~
  23. Q: Module yealink compiled and installed without any problem but phone
  24. is not initialized and does not react to any actions.
  25. A: If you see something like:
  26. hiddev0: USB HID v1.00 Device [Yealink Network Technology Ltd. VOIP USB Phone
  27. in dmesg, it means that the hid driver has grabbed the device first. Try to
  28. load module yealink before any other usb hid driver. Please see the
  29. instructions provided by your distribution on module configuration.
  30. Q: Phone is working now (displays version and accepts keypad input) but I can't
  31. find the sysfs files.
  32. A: The sysfs files are located on the particular usb endpoint. On most
  33. distributions you can do: "find /sys/ -name get_icons" for a hint.
  34. 2. keyboard features
  35. ~~~~~~~~~~~~~~~~~~~~
  36. The current mapping in the kernel is provided by the map_p1k_to_key
  37. function:
  38. Physical USB-P1K button layout input events
  39. up up
  40. IN OUT left, right
  41. down down
  42. pickup C hangup enter, backspace, escape
  43. 1 2 3 1, 2, 3
  44. 4 5 6 4, 5, 6,
  45. 7 8 9 7, 8, 9,
  46. * 0 # *, 0, #,
  47. The "up" and "down" keys, are symbolised by arrows on the button.
  48. The "pickup" and "hangup" keys are symbolised by a green and red phone
  49. on the button.
  50. 3. LCD features
  51. ~~~~~~~~~~~~~~~
  52. The LCD is divided and organised as a 3 line display:
  53. |[] [][] [][] [][] in |[][]
  54. |[] M [][] D [][] : [][] out |[][]
  55. store
  56. NEW REP SU MO TU WE TH FR SA
  57. [] [] [] [] [] [] [] [] [] [] [] []
  58. [] [] [] [] [] [] [] [] [] [] [] []
  59. Line 1 Format (see below) : 18.e8.M8.88...188
  60. Icon names : M D : IN OUT STORE
  61. Line 2 Format : .........
  62. Icon name : NEW REP SU MO TU WE TH FR SA
  63. Line 3 Format : 888888888888
  64. Format description:
  65. From a userspace perspective the world is separated into "digits" and "icons".
  66. A digit can have a character set, an icon can only be ON or OFF.
  67. Format specifier
  68. '8' : Generic 7 segment digit with individual addressable segments
  69. Reduced capability 7 segm digit, when segments are hard wired together.
  70. '1' : 2 segments digit only able to produce a 1.
  71. 'e' : Most significant day of the month digit,
  72. able to produce at least 1 2 3.
  73. 'M' : Most significant minute digit,
  74. able to produce at least 0 1 2 3 4 5.
  75. Icons or pictograms:
  76. '.' : For example like AM, PM, SU, a 'dot' .. or other single segment
  77. elements.
  78. 4. Driver usage
  79. ~~~~~~~~~~~~~~~
  80. For userland the following interfaces are available using the sysfs interface:
  81. /sys/.../
  82. line1 Read/Write, lcd line1
  83. line2 Read/Write, lcd line2
  84. line3 Read/Write, lcd line3
  85. get_icons Read, returns a set of available icons.
  86. hide_icon Write, hide the element by writing the icon name.
  87. show_icon Write, display the element by writing the icon name.
  88. map_seg7 Read/Write, the 7 segments char set, common for all
  89. yealink phones. (see map_to_7segment.h)
  90. ringtone Write, upload binary representation of a ringtone,
  91. see yealink.c. status EXPERIMENTAL due to potential
  92. races between async. and sync usb calls.
  93. 4.1 lineX
  94. ~~~~~~~~~
  95. Reading /sys/../lineX will return the format string with its current value:
  96. Example:
  97. cat ./line3
  98. 888888888888
  99. Linux Rocks!
  100. Writing to /sys/../lineX will set the corresponding LCD line.
  101. - Excess characters are ignored.
  102. - If less characters are written than allowed, the remaining digits are
  103. unchanged.
  104. - The tab '\t'and '\n' char does not overwrite the original content.
  105. - Writing a space to an icon will always hide its content.
  106. Example:
  107. date +"%m.%e.%k:%M" | sed 's/^0/ /' > ./line1
  108. Will update the LCD with the current date & time.
  109. 4.2 get_icons
  110. ~~~~~~~~~~~~~
  111. Reading will return all available icon names and its current settings:
  112. cat ./get_icons
  113. on M
  114. on D
  115. on :
  116. IN
  117. OUT
  118. STORE
  119. NEW
  120. REP
  121. SU
  122. MO
  123. TU
  124. WE
  125. TH
  126. FR
  127. SA
  128. LED
  129. DIALTONE
  130. RINGTONE
  131. 4.3 show/hide icons
  132. ~~~~~~~~~~~~~~~~~~~
  133. Writing to these files will update the state of the icon.
  134. Only one icon at a time can be updated.
  135. If an icon is also on a ./lineX the corresponding value is
  136. updated with the first letter of the icon.
  137. Example - light up the store icon:
  138. echo -n "STORE" > ./show_icon
  139. cat ./line1
  140. 18.e8.M8.88...188
  141. S
  142. Example - sound the ringtone for 10 seconds:
  143. echo -n RINGTONE > /sys/..../show_icon
  144. sleep 10
  145. echo -n RINGTONE > /sys/..../hide_icon
  146. 5. Sound features
  147. ~~~~~~~~~~~~~~~~~
  148. Sound is supported by the ALSA driver: snd_usb_audio
  149. One 16-bit channel with sample and playback rates of 8000 Hz is the practical
  150. limit of the device.
  151. Example - recording test:
  152. arecord -v -d 10 -r 8000 -f S16_LE -t wav foobar.wav
  153. Example - playback test:
  154. aplay foobar.wav
  155. 6. Credits & Acknowledgments
  156. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  157. - Olivier Vandorpe, for starting the usbb2k-api project doing much of
  158. the reverse engineering.
  159. - Martin Diehl, for pointing out how to handle USB memory allocation.
  160. - Dmitry Torokhov, for the numerous code reviews and suggestions.