Driver documentation for Yealink phones and ATA adapter.

0. Status
~~~~~~~~~
Phone models:
USB-P1K  USB 1.1 hand phone with LCD, keypad and ringer.
USB-P1KH USB 1.1 hand phone with LCD, keypad and ringer.
USB-P4K  USB 1.1 speaker phone desktop model.
USB-B2K  USB 1.1 telbox, ATA adapter for PSTN.
USB-B3K  USB 1.1 telbox, ATA adapter for PSTN
	 (Caller-ID and PSTN-USB-bridge currently not supported)

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

The original development branch can be found at:
http://cvs.savannah.gnu.org/viewcvs/usbb2k-api/yealink-module/

The updated sources supporting the P1KH and B3G can be found at:
http://www.devbase.at/svn/view.cgi/yealink-module/?root=voip


Matrix of supported features:
function	API	P1K(H)	P4K	B2K	B3G
---------------------------------------------------
audio playback	alsa 	ok	ok	ok	ok
audio record	alsa	ok	ok	ok	ok
keyboard	input	ok	ok	ok	ok
hookflash	input		ok	ok	ok
PSTN ring	input			ok	ok
LCD		sysfs	ok	ok
LED		sysfs	ok
DIALTONE	sysfs		ok	ok	ok
RINGTONE	sysfs	ok		ok	ok
BACKLIGHT	sysfs		ok
SPEAKER		sysfs		ok
PSTN		sysfs			ok	ok
LED (USB/PSTN)	sysfs			ok	ok
Caller-ID					wip
PSTN-USB-Bridge					wip


Notes:
P4K: Ring tones are implemented by switching on the SPEAKER
and sending a ring tone pcm via the dsp interface.


0.1 User space applications
~~~~~~~~~~~~~~~~~~~~~~~~~~~

0.1.1 Yeaphone
~~~~~~~~~~~~~~
Thomas Reitmayr has released Yeaphone, a great addition to linphone, this
will turn your P1K(H) into a full blown SIP phone. There are even packages
for the Linksys NSLU2 for an energy efficient and fanless solution!

Please check out: http://www.devbase.at/voip/yeaphone.php


1. Compilation (stand alone version)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Currently only kernel versions >= 2.6.18 are supported.
In order to build the yealink.ko module do

  make

If you encounter problems please check if in the MAKE_OPTS variable
in the Makefile is pointing to the location where your kernel sources
are located, default /usr/src/linux.


1.1 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.
   UPDATE: since kernel version 2.6.18 the HID driver is patched in order to
   prevent grabbing the yealink device.

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.


2. Keyboard features
~~~~~~~~~~~~~~~~~~~~
Keyboard events are processes through the input layer. A user space application
may issue the EVIOCGRAB ioctl() on the corresponding /dev/input/eventX device
to prevent the key codes from the event device to go to the rest of the system.

The current mappings from scancode to input event are provided by the
map_p1k_to_key, map_p4k_to_key, ... functions.
See yealink.c for a description.


2.1 P1K keyboard layout
~~~~~~~~~~~~~~~~~~~~~~~

   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 symbolized by arrows on the button.
  The "pickup" and "hangup" keys are symbolized by a green and red phone
  on the button.


2.2 Hookflash
~~~~~~~~~~~~~
The B2K, B3K, and P4K generate KEY_PHONE up and down events when the phone
taken off- or on-hook.


2.3 PSTN Ring
~~~~~~~~~~~~~
The B2K and B3K report each individual ringtone on the PSTN line with KEY_P
down (start of tone) and up (end of tone) events.


3. LCD features
~~~~~~~~~~~~~~~
The models P1K(H) and P4K feature an LCD which is divided and organized 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 user space perspective the world is separated in "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 segm digit, when segments are hard wired together.
    '1' : 2 segment 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.


4. 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
			for P1K(H) models, see yealink.c.

	   model	Read, returns the detected phone model.

  module parameters:

	   none

4.1 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.


4.2 get_icons
~~~~~~~~~~~~~
Reading will return all available icon names for the detected model 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
     RINGTONE


4.3 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 ring tone for 10 seconds:
  echo -n RINGTONE > /sys/..../show_icon
  sleep 10
  echo -n RINGTONE > /sys/..../hide_icon


4.4 model
~~~~~~~~~
This file can be read to print the current phone model.

  Example - show the current phone model:
  cat ./model
  P1K


5. 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 devices.

  Example - recording test:
  arecord -v -d 10 -r 8000 -f S16_LE -t wav  foobar.wav

  Example - playback test:
  aplay foobar.wav


6. Credits & Acknowledgments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See yealink.c