Driver Documentation for Yealink USB-P1K Phones

USB-P1K 기능 상태와 키패드 매핑

Yealink USB-P1K는 USB 1.1 전화기입니다. 키보드, LCD, LED, dialtone, ringtone은 `yealink.ko`가 input event 또는 sysfs API로 완전히 지원하고, 오디오 재생·녹음은 `snd_usb_audio.ko`와 ALSA API가 지원합니다.

커널의 실제 키 매핑은 `map_p1k_to_key` 함수가 제공합니다. 원문의 물리 버튼 ASCII 배치를 Linux input event 표로 다시 구성하면 다음과 같습니다.

===============================================
Driver documentation for yealink usb-p1k phones
===============================================

Status
======

The p1k is a relatively cheap usb 1.1 phone with:

  - keyboard                full support, yealink.ko / input event API
  - LCD                        full support, yealink.ko / sysfs API
  - LED                        full support, yealink.ko / sysfs API
  - dialtone                full support, yealink.ko / sysfs API
  - ringtone                full support, yealink.ko / sysfs API
  - audio playback           full support, snd_usb_audio.ko / alsa API
  - audio record             full support, snd_usb_audio.ko / alsa API

For vendor documentation see http://www.yealink.com


keyboard features
=================

The current mapping in the kernel is provided by the map_p1k_to_key
function::

   Physical USB-P1K button layout        input events


              up                             up
        IN           OUT                left,        right
             down                            down

      pickup   C    hangup                enter, backspace, escape
        1      2      3                        1, 2, 3
        4      5      6                        4, 5, 6,
        7      8      9                        7, 8, 9,
        *      0      #                        *, 0, #,

The "up" and "down" keys, are symbolised by arrows on the button.
The "pickup" and "hangup" keys are symbolised by a green and red phone
on the button.

3줄 LCD, digit 형식과 icon

LCD는 세 줄로 나뉩니다. 첫 줄은 날짜·시간 digit과 `M`, `D`, `:`, `IN`, `OUT`, `STORE` icon을 포함하고, 둘째 줄은 `NEW`, `REP`와 요일 icon, 셋째 줄은 12개의 일반 7-segment digit입니다.

사용자 공간에서 화면 요소는 digit과 icon으로 구분됩니다. Digit은 문자 집합을 가질 수 있지만 icon은 ON 또는 OFF만 가능합니다.

LCD features
============

The LCD is divided and organised as a 3 line display::

    |[]   [][]   [][]   [][]   in   |[][]
    |[] M [][] D [][] : [][]   out  |[][]
                              store

    NEW REP         SU MO TU WE TH FR SA

    [] [] [] [] [] [] [] [] [] [] [] []
    [] [] [] [] [] [] [] [] [] [] [] []


  Line 1  Format (see below)        : 18.e8.M8.88...188
          Icon names                :   M  D  :  IN OUT STORE
  Line 2  Format                : .........
          Icon name                : NEW REP SU MO TU WE TH FR SA
  Line 3  Format                : 888888888888


Format description:
  From a userspace perspective the world is separated into "digits" and "icons".
  A digit can have a character set, an icon can only be ON or OFF.

  Format specifier::

    '8' :  Generic 7 segment digit with individual addressable segments

    Reduced capability 7 segment digit, when segments are hard wired together.
    '1' : 2 segments digit only able to produce a 1.
    'e' : Most significant day of the month digit,
          able to produce at least 1 2 3.
    'M' : Most significant minute digit,
          able to produce at least 0 1 2 3 4 5.

    Icons or pictograms:
    '.' : For example like AM, PM, SU, a 'dot' .. or other single segment
          elements.

LCD line과 공통 7-segment sysfs 사용

`ringtone`은 async와 sync USB call 사이의 race 가능성 때문에 experimental입니다. `map_seg7`의 문자 집합은 `map_to_7segment.h`를 참조합니다.

`lineX`를 읽으면 format string과 현재 값이 함께 반환됩니다. 예를 들어 `line3`은 `888888888888` 다음 줄에 `Linux Rocks!`를 돌려줍니다. 쓸 때는 대응 LCD 줄만 갱신합니다.

원문 예제 `date +"%m.%e.%k:%M" | sed 's/^0/ /' > ./line1`은 현재 날짜와 시간을 첫 줄 형식에 맞춰 갱신합니다.

Driver usage
============

For userland the following interfaces are available using the sysfs interface::

  /sys/.../
           line1        Read/Write, lcd line1
           line2        Read/Write, lcd line2
           line3        Read/Write, lcd line3

           get_icons    Read, returns a set of available icons.
           hide_icon    Write, hide the element by writing the icon name.
           show_icon    Write, display the element by writing the icon name.

           map_seg7        Read/Write, the 7 segments char set, common for all
                        yealink phones. (see map_to_7segment.h)

           ringtone        Write, upload binary representation of a ringtone,
                        see yealink.c. status EXPERIMENTAL due to potential
                        races between async. and sync usb calls.


lineX
~~~~~

Reading /sys/../lineX will return the format string with its current value.

  Example::

    cat ./line3
    888888888888
    Linux Rocks!

Writing to /sys/../lineX will set the corresponding LCD line.

 - Excess characters are ignored.
 - If less characters are written than allowed, the remaining digits are
   unchanged.
 - The tab '\t'and '\n' char does not overwrite the original content.
 - Writing a space to an icon will always hide its content.

  Example::

    date +"%m.%e.%k:%M"  | sed 's/^0/ /' > ./line1

  Will update the LCD with the current date & time.

Icon 상태 조회와 표시·숨김

`get_icons`를 읽으면 지원 icon 이름과 현재 ON 상태를 반환합니다. 목록에는 `M`, `D`, `:`, `IN`, `OUT`, `STORE`, `NEW`, `REP`, 요일 `SU`~`SA`, 그리고 `LED`, `DIALTONE`, `RINGTONE`이 포함됩니다.

`show_icon`과 `hide_icon`에는 한 번에 icon 이름 하나만 쓸 수 있습니다. Icon이 `lineX`에도 배치되어 있으면 대응 값은 icon 이름의 첫 글자로 갱신됩니다.

get_icons
~~~~~~~~~

Reading will return all available icon names and its current settings::

  cat ./get_icons
  on M
  on D
  on :
     IN
     OUT
     STORE
     NEW
     REP
     SU
     MO
     TU
     WE
     TH
     FR
     SA
     LED
     DIALTONE
     RINGTONE


show/hide icons
~~~~~~~~~~~~~~~

Writing to these files will update the state of the icon.
Only one icon at a time can be updated.

If an icon is also on a ./lineX the corresponding value is
updated with the first letter of the icon.

  Example - light up the store icon::

    echo -n "STORE" > ./show_icon

    cat ./line1
    18.e8.M8.88...188
                  S

  Example - sound the ringtone for 10 seconds::

    echo -n RINGTONE > /sys/..../show_icon
    sleep 10
    echo -n RINGTONE > /sys/..../hide_icon

8 kHz 오디오와 드라이버 바인딩 문제 해결

오디오는 ALSA의 `snd_usb_audio`가 지원합니다. 장치의 실용 한계는 16비트 한 채널, 녹음과 재생 sample rate 8000 Hz입니다.

전화기가 초기화되지 않고 반응하지 않으며 `dmesg`에 `hiddev0: USB HID v1.00 Device [Yealink ...]`가 보이면 일반 HID driver가 장치를 먼저 잡은 것입니다. 다른 USB HID driver보다 `yealink` module을 먼저 로드하도록 배포판 module 설정을 조정합니다.

버전이 표시되고 키패드는 동작하지만 sysfs 파일을 찾을 수 없다면 해당 파일이 특정 USB endpoint 아래에 있다는 점을 확인해야 합니다. 대부분의 배포판에서 `find /sys/ -name get_icons`로 위치를 찾을 수 있습니다.

문서는 usbb2k-api 역공학을 시작한 Olivier Vandorpe, USB memory allocation 처리 방법을 제안한 Martin Diehl, 코드 리뷰를 제공한 Dmitry Torokhov에게 감사를 표합니다.

Sound features
==============

Sound is supported by the ALSA driver: snd_usb_audio

One 16-bit channel with sample and playback rates of 8000 Hz is the practical
limit of the device.

  Example - recording test::

    arecord -v -d 10 -r 8000 -f S16_LE -t wav  foobar.wav

  Example - playback test::

    aplay foobar.wav


Troubleshooting
===============

:Q: Module yealink compiled and installed without any problem but phone
    is not initialized and does not react to any actions.
:A: If you see something like:
    hiddev0: USB HID v1.00 Device [Yealink Network Technology Ltd. VOIP USB Phone
    in dmesg, it means that the hid driver has grabbed the device first. Try to
    load module yealink before any other usb hid driver. Please see the
    instructions provided by your distribution on module configuration.

:Q: Phone is working now (displays version and accepts keypad input) but I can't
    find the sysfs files.
:A: The sysfs files are located on the particular usb endpoint. On most
    distributions you can do: "find /sys/ -name get_icons" for a hint.


Credits & Acknowledgments
=========================

  - Olivier Vandorpe, for starting the usbb2k-api project doing much of
    the reverse engineering.
  - Martin Diehl, for pointing out how to handle USB memory allocation.
  - Dmitry Torokhov, for the numerous code reviews and suggestions.